Initial Commit

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

@@ -0,0 +1,40 @@
+# 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.

openspec/archive/2026-04-19-enterprise-api-schemas/specs/api-schemas/spec.md

@@ -0,0 +1,30 @@
+# Capability Spec: api-schemas
+
+**Package**: `@suaveplan/api-schemas`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### AS-01 — Zod facade re-export
+The package MUST re-export `z` from Zod. Consumers MUST be able to write `import z from '@suaveplan/api-schemas'`.
+
+### AS-02 — Domain barrels
+Each of `./admin`, `./auth`, `./common`, `./events` MUST be a dedicated subpath export containing a group of Zod schemas. Barrels MUST NOT pull in other domain groups to preserve tree-shaking.
+
+### AS-03 — Input/output pairing
+Every operation MUST ship an `<Operation>Input` + `<Operation>Output` Zod object pair. Pagination, sort, filter, and id-param schemas MUST compose via `.extend` / `.merge`.
+
+### AS-04 — Error envelope
+`ErrorEnvelope` MUST match the shape emitted by `@suaveplan/error`: `{ code: string, message: string, details?: unknown, httpStatus?: number, cause?: ErrorEnvelope }`. Server and client layers MUST use the same schema.
+
+### AS-05 — Event schemas
+`DomainEvent` MUST include `{ type: string, version: number, occurredAt: ISO-string, payload: unknown }`. `EventEnvelope` MUST wrap a `DomainEvent` with `metadata` (`{ traceId?, spanId?, causationId?, correlationId? }`).
+
+### AS-06 — JSON Schema / OpenAPI helpers
+`toJsonSchema(schema)` MUST produce a valid JSON Schema Draft 2020-12 document. `toOpenApi(schema)` MUST produce a `components.schemas` fragment compatible with OpenAPI 3.1.
+
+### AS-07 — Error lifting
+`toSuaveplanError(zodError, code)` MUST return a `SuaveplanError` whose `cause.details` contains every `ZodIssue` from the input.

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

@@ -0,0 +1,33 @@
+# Tasks: enterprise-api-schemas
+
+## 1. Scaffold
+- [x] 1.1 `universal/docs/api-schemas/`; 100/100/100/100; guard tests; CLAUDE/README/FOLDERS.
+
+## 2. Common group
+- [x] 2.1 `src/common/pagination.ts`, `sort.ts`, `filter.ts`, `id-param.ts`, `timestamps.ts`, `error-envelope.ts`.
+- [x] 2.2 Co-located `.md` + unit tests per schema.
+
+## 3. Auth group
+- [x] 3.1 `src/auth/login.ts`, `register.ts`, `refresh.ts`, `logout.ts`, `context.ts`.
+
+## 4. Admin group
+- [x] 4.1 `src/admin/ping.ts`, `health.ts`, `status.ts`.
+
+## 5. Events group
+- [x] 5.1 `src/events/domain-event.ts`, `envelope.ts`, `metadata.ts`.
+
+## 6. Helpers
+- [x] 6.1 `src/helpers/to-suaveplan-error.ts` — ZodError → SuaveplanError lift.
+- [x] 6.2 `src/helpers/to-json-schema.ts` — JSON Schema dump.
+- [x] 6.3 `src/helpers/to-openapi.ts` — OpenAPI path/component fragment generator.
+
+## 7. Barrel / subpath exports
+- [x] 7.1 `./admin`, `./auth`, `./common`, `./events`, `./helpers`.
+
+## 8. Property tests
+- [x] 8.1 fast-check arbitraries for every top-level schema round-trip.
+
+## 9. Docs / README / benchmarks
+
+## 10. Ship gate
+- [x] 10.1 Verification sequence; fold + archive.