73 lines
6.0 KiB
Markdown
73 lines
6.0 KiB
Markdown
# @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).
|