Initial Commit

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.