41 lines
2.0 KiB
Markdown
41 lines
2.0 KiB
Markdown
# 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.
|