first commit
This commit is contained in:
72
docs/api-stack/api/api-schemas/README.md
Normal file
72
docs/api-stack/api/api-schemas/README.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# @suaveplan/api-schemas - Shared Zod schemas describing Suaveplan API request/response shapes — single source of truth for server plugins, React data hooks, and generated OpenAPI documents
|
||||
|
||||
## Summary
|
||||
|
||||
Shared Zod schemas describing Suaveplan API request/response shapes. The single source of truth for server plugins, React data hooks, and generated OpenAPI documents.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [health](./src/admin/health.md) — Defines Zod schemas for the admin health check endpoint (`GET /admin/health`). The health endpoint exposes a structured…
|
||||
- [ping](./src/admin/ping.md) — Provides Zod schemas for the admin ping endpoint (`GET /admin/ping`). The ping endpoint is the simplest possible health…
|
||||
- [status](./src/admin/status.md) — Defines the Zod schema for the admin status endpoint (`GET /admin/status`), which exposes static deployment metadata fo…
|
||||
- [context](./src/auth/context.md) — Defines the `AuthContext` Zod schema representing the authenticated caller's identity as it flows through a request lif…
|
||||
- [login](./src/auth/login.md) — Defines Zod schemas for the login request and response shapes used by Suaveplan's authentication endpoints. These schem…
|
||||
- [logout](./src/auth/logout.md) — Provides Zod schemas for the logout request and response shapes used by Suaveplan's `POST /auth/logout` endpoint. Logou…
|
||||
- [refresh](./src/auth/refresh.md) — Defines Zod schemas for the token-refresh request and response shapes used by Suaveplan's `POST /auth/refresh` endpoint…
|
||||
- [register](./src/auth/register.md) — Provides Zod schemas for the user registration request and response shapes used by Suaveplan's `POST /auth/register` en…
|
||||
- [error-envelope](./src/common/error-envelope.md) — Defines Zod schemas for the standard error response envelope used across all Suaveplan API endpoints. By sharing these…
|
||||
- [filter](./src/common/filter.md) — Defines Zod schemas for filter predicate inputs used in Suaveplan list and search endpoints. These schemas provide a st…
|
||||
- [id-param](./src/common/id-param.md) — Provides Zod schemas for URL path parameter objects carrying resource identifiers. Rather than validating raw strings a…
|
||||
- [pagination](./src/common/pagination.md) — Defines Zod schemas for pagination input and output shapes used across all Suaveplan list endpoints. These schemas serv…
|
||||
- [sort](./src/common/sort.md) — Provides Zod schemas for sort criteria used in Suaveplan list and search endpoints. By centralising the `SortInput` and…
|
||||
- [timestamps](./src/common/timestamps.md) — Defines Zod schemas for the audit timestamp fields (`createdAt`, `updatedAt`, and optionally `deletedAt`) that appear o…
|
||||
- [domain-event](./src/events/domain-event.md) — Defines the `DomainEvent` Zod schema — the canonical wire format for immutable domain events flowing through the Suavep…
|
||||
- [envelope](./src/events/envelope.md) — Defines the `EventEnvelope` Zod schema — the transport wrapper that carries a domain event across message brokers, even…
|
||||
- [metadata](./src/events/metadata.md) — Defines the `EventMetadata` Zod schema for the distributed tracing and actor context attached to every domain event in…
|
||||
- [helpers](./src/helpers/to-suaveplan-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [to-suaveplan-error](./src/helpers/to-suaveplan-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
<!-- end:auto-docs --> - [to-suaveplan-error](./src/helpers/to-suaveplan-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [to-suaveplan-error](./src/helpers/to-suaveplan-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [to-suaveplan-error](./src/helpers/to-suaveplan-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [to-suaveplan-error](./src/helpers/to-suaveplan-error.md) — <!-- begin:auto-docs --> _(no submodules)_
|
||||
## Modules
|
||||
|
||||
| Module | Description |
|
||||
|---|---|
|
||||
| [common/pagination](src/common/pagination.md) | Cursor-based and offset-based pagination input/output |
|
||||
| [common/sort](src/common/sort.md) | Sort criteria (field + direction, multi-column) |
|
||||
| [common/filter](src/common/filter.md) | Filter predicates with 13 comparison operators |
|
||||
| [common/id-param](src/common/id-param.md) | URL path parameters for single and nested resources |
|
||||
| [common/timestamps](src/common/timestamps.md) | Audit timestamps (createdAt/updatedAt, soft-delete) |
|
||||
| [common/error-envelope](src/common/error-envelope.md) | Structured error responses with field-level details |
|
||||
| [auth/login](src/auth/login.md) | Login request/response (credentials → token + user) |
|
||||
| [auth/register](src/auth/register.md) | Registration request/response |
|
||||
| [auth/refresh](src/auth/refresh.md) | Token refresh with rotation |
|
||||
| [auth/logout](src/auth/logout.md) | Session revocation |
|
||||
| [auth/context](src/auth/context.md) | Decoded auth context (userId, roles, tenantId) |
|
||||
| [admin/ping](src/admin/ping.md) | Sentinel liveness check |
|
||||
| [admin/health](src/admin/health.md) | Aggregate + per-subsystem health status |
|
||||
| [admin/status](src/admin/status.md) | Deployment metadata (version, uptime, environment) |
|
||||
| [events/metadata](src/events/metadata.md) | Event correlation and actor context |
|
||||
| [events/domain-event](src/events/domain-event.md) | Immutable domain event record |
|
||||
| [events/envelope](src/events/envelope.md) | Transport wrapper with sequence number |
|
||||
| [helpers/to-suaveplan-error](src/helpers/to-suaveplan-error.md) | Convert ZodError → ErrorEnvelope |
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/api-schemas
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```ts
|
||||
import { LoginInput, LoginOutput } from "@suaveplan/api-schemas/auth";
|
||||
import { PaginationInput, ErrorEnvelope } from "@suaveplan/api-schemas/common";
|
||||
import { AdminHealthOutput } from "@suaveplan/api-schemas/admin";
|
||||
import { EventEnvelope } from "@suaveplan/api-schemas/events";
|
||||
import { toSuaveplanError } from "@suaveplan/api-schemas/helpers";
|
||||
import z from "@suaveplan/api-schemas"; // re-exported for convenience
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
Runtime: `zod`, `tslib`, `@opentelemetry/api`. No `@suaveplan/*` runtime dependencies (leaf package).
|
||||
Reference in New Issue
Block a user