spol-api-schemas
Zod schemas, the OpenAPI registry, and the committed openapi.json for the sPOL REST API — the single source of truth for the API contract.
Three consumers read this one contract, so they can never drift out of sync:
- The service (
@polygonlabs/spol-rest-api) validates requests against these schemas and serves the generated spec at/openapi.json. - The generated client (
@polygonlabs/spol-api-client) is codegen'd from the sameopenapi.jsonand imports these exact Zod values, so it validates against precisely what the backend accepts. - The spec artifact (
openapi.json) is committed and regenerated on build, so a schema change that isn't reflected in the spec fails thecodegen-drift-checkgate rather than shipping silently.
Codec-typed fields (BigIntegerCodec, IsoDateCodec from @polygonlabs/zod-codecs) carry a wire type distinct from their runtime type — a wei amount is a decimal string on the wire and a bigint after parsing — so the client decodes to the right runtime type end-to-end without a parallel schema.
Install
pnpm add @polygonlabs/spol-api-schemasEntry points
| Entry point | Contents |
|---|---|
@polygonlabs/spol-api-schemas |
The Zod schemas — registered response components and the shared building blocks / query shapes |
@polygonlabs/spol-api-schemas/registry |
buildRegistry() — the @asteasolutions/zod-to-openapi registry that drives both openapi.json generation and the client codegen |
@polygonlabs/spol-api-schemas/openapi.json |
The committed OpenAPI 3.0 document (regenerated on build) |
Naming convention
Schemas registered as OpenAPI components (.openapi('Name')) are exported under the registered name verbatim (Transaction, SummaryResponse, TransactionsListV1Response, …) — the @polygonlabs/zod-to-openapi-heyapi codegen imports them by that name and audits the export at build time, so renaming one breaks the generated client. Building blocks that are not registered components (NetworkSchema, AddressSchema, query/filter shapes) keep the *Schema suffix to distinguish them at call sites.
Development
pnpm --filter @polygonlabs/spol-api-schemas run build # typecheck, emit dist/, regenerate openapi.json
pnpm --filter @polygonlabs/spol-api-schemas run test # codec round-trip testsopenapi.json is generated from the registry by scripts/generate-spec.ts; never hand-edit it. See apps-team-ops/docs/best-practices/rest-api-clients-codegen.md for the full contract-first pattern.