skills/plugins/document-navigator/docs/api-stack/api/api-schemas/README.md

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

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