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 same openapi.json and 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 the codegen-drift-check gate 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-schemas

Entry 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 tests

openapi.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.