Shared Zod schemas describing Suaveplan API request/response shapes. The single source of truth for server plugins, React data hooks, and generated OpenAPI documents.

Documentation tree

health — Defines Zod schemas for the admin health check endpoint (GET /admin/health). The health endpoint exposes a structured…
ping — Provides Zod schemas for the admin ping endpoint (GET /admin/ping). The ping endpoint is the simplest possible health…
status — Defines the Zod schema for the admin status endpoint (GET /admin/status), which exposes static deployment metadata fo…
context — Defines the AuthContext Zod schema representing the authenticated caller's identity as it flows through a request lif…
login — Defines Zod schemas for the login request and response shapes used by Suaveplan's authentication endpoints. These schem…
logout — Provides Zod schemas for the logout request and response shapes used by Suaveplan's POST /auth/logout endpoint. Logou…
refresh — Defines Zod schemas for the token-refresh request and response shapes used by Suaveplan's POST /auth/refresh endpoint…
register — Provides Zod schemas for the user registration request and response shapes used by Suaveplan's POST /auth/register en…
error-envelope — Defines Zod schemas for the standard error response envelope used across all Suaveplan API endpoints. By sharing these…
filter — Defines Zod schemas for filter predicate inputs used in Suaveplan list and search endpoints. These schemas provide a st…
id-param — Provides Zod schemas for URL path parameter objects carrying resource identifiers. Rather than validating raw strings a…
pagination — Defines Zod schemas for pagination input and output shapes used across all Suaveplan list endpoints. These schemas serv…
sort — Provides Zod schemas for sort criteria used in Suaveplan list and search endpoints. By centralising the SortInput and…
timestamps — Defines Zod schemas for the audit timestamp fields (createdAt, updatedAt, and optionally deletedAt) that appear o…
domain-event — Defines the DomainEvent Zod schema — the canonical wire format for immutable domain events flowing through the Suavep…
envelope — Defines the EventEnvelope Zod schema — the transport wrapper that carries a domain event across message brokers, even…
metadata — Defines the EventMetadata Zod schema for the distributed tracing and actor context attached to every domain event in…
helpers — (no submodules)
- to-suaveplan-error — (no submodules)

- [to-suaveplan-error](./src/helpers/to-suaveplan-error.md) — _(no submodules)_- [to-suaveplan-error](./src/helpers/to-suaveplan-error.md) — _(no submodules)_- [to-suaveplan-error](./src/helpers/to-suaveplan-error.md) — _(no submodules)_- [to-suaveplan-error](./src/helpers/to-suaveplan-error.md) — _(no submodules)_

Modules

Module	Description
common/pagination	Cursor-based and offset-based pagination input/output
common/sort	Sort criteria (field + direction, multi-column)
common/filter	Filter predicates with 13 comparison operators
common/id-param	URL path parameters for single and nested resources
common/timestamps	Audit timestamps (createdAt/updatedAt, soft-delete)
common/error-envelope	Structured error responses with field-level details
auth/login	Login request/response (credentials → token + user)
auth/register	Registration request/response
auth/refresh	Token refresh with rotation
auth/logout	Session revocation
auth/context	Decoded auth context (userId, roles, tenantId)
admin/ping	Sentinel liveness check
admin/health	Aggregate + per-subsystem health status
admin/status	Deployment metadata (version, uptime, environment)
events/metadata	Event correlation and actor context
events/domain-event	Immutable domain event record
events/envelope	Transport wrapper with sequence number
helpers/to-suaveplan-error	Convert ZodError → ErrorEnvelope

Installation

bun add @suaveplan/api-schemas

Usage

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