suaveplan/openspec/archive/2026-04-19-enterprise-api-schemas/proposal.md

OpenSpec Change: enterprise-api-schemas

• Change ID: enterprise-api-schemas
• Package: @suaveplan/api-schemas
• Category: universal
• Target path: universal/docs/api-schemas
• Status: PROPOSED
• Date: 2026-04-19
• Reference spec: /mnt/s/web/suaveplan/enterprise/api-schemas.md

Summary

Shared Zod schemas describing Suaveplan API request / response shapes — the single source of truth consumed by server plugins, React data hooks, and generated OpenAPI documents. Groups: admin, auth, common, events, plus re-exports from extension capability packages. Leaf from workspace perspective.

Current-state audit (genesis)

Package does not exist yet — fresh build. Main branch ships packages/universal/api-schemas with per-domain barrels.

Dependencies

• Workspace: none (leaf)
• External (via catalog): zod → catalog:forms; tslib; @opentelemetry/api
• Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata

Preserved public surface

• Re-export of z (Zod z facade)
• Barrels: ./admin, ./auth, ./common, ./events
• Schema groups (each a Zod object with .input, .output pairs):
  • Admin: AdminPingInput/Output, AdminHealthOutput, AdminStatusOutput
  • Auth: LoginInput/Output, RegisterInput/Output, RefreshInput/Output, LogoutInput/Output, AuthContext
  • Common: PaginationInput, SortInput, FilterInput, IdParam, TimestampsOutput, ErrorEnvelope
  • Events: DomainEvent, EventEnvelope, EventMetadata

New genesis additions

• Codes: API_SCHEMAS.VALIDATION_FAILED (convenience for consumers converting Zod errors to SuaveplanError).
• Helper toSuaveplanError(zodError, code) that lifts a ZodError into a SuaveplanError.
• JSON Schema generator (zod-to-json-schema) and OpenAPI adapter.
• Property tests for every top-level schema via fast-check arbitraries.

Impact

• Adds one new package: universal/docs/api-schemas
• Adds one new spec capability: api-schemas
• Unblocks api-docs and downstream API plugins.