# @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).