@greatwait/contracts

The public contracts for Greatwait: the schemas every response is parsed with, the stable refusal catalog, the operation registry, and the generated OpenAPI documents.

Invited alpha. This package publishes on the alpha dist-tag and has no latest. Install it explicitly, and pin the exact version in anything you care about.

npm install @greatwait/contracts@alpha

Most people arrive here through @greatwait/api-client, which depends on this package. Install it directly when you want the schemas without the client — to validate a callback body, to generate code, or to hold your own client against the published shapes.

Parsing a response

import { responseSchemaFor } from "@greatwait/contracts";

const schedule = responseSchemaFor("schedules.create").parse(body);

Schemas are Zod and are the same objects the service validates with, so a shape is stated once rather than mirrored. The JSON Schema form of each is shipped too, under generated/v1/schemas/, for consumers that are not JavaScript.

What ships

| Path | What it is | | --------------------------------------- | ------------------------------------------------------------------------------------------- | | generated/v1/openapi.json | The public API, as OpenAPI | | generated/v1/openapi.mock.json | The contract mock's surface, labelled separately so it can never be read as the product API | | generated/v1/schemas/ | JSON Schema per operation, request and response | | generated/v1/snippets/ | curl, JavaScript and MCP examples per operation | | generated/v1/first-value-journey.json | The canonical first-value sequence, as data | | generated/v1/policy-matrix.json | Who may call what, derived from the registry | | generated/v1/manifest.json | The index of everything above, with the contract version |

All of it is generated from one registry, so a change to an operation changes every artifact at once. Nothing here is hand-maintained beside the code it describes.

The conventions the schemas encode

• Identifiers are opaque, prefixed and server-assigned. Compare them for equality and nothing else.
• Time is RFC 3339, UTC, milliseconds, literal Z. Durations are whole seconds. An IANA timezone appears only beside a cron recurrence.
• Collections are cursor-paged, never offset-paged, and every page carries freshness so a client can tell an authoritative answer from a projected one.
• Concurrency is a monotonic version surfaced as a strong ETag; a conditional write sends it back in If-Match and is refused version_conflict rather than resolving by luck.
• Refusals are RFC 9457 problem documents with a stable code. Adding a code is additive; removing one, or changing its category or status, is breaking.

CONTRACT_VERSION is the dated version of all of this. It moves independently of any deployment, because a service that ships twice a day must not imply the contract changed twice a day.

The first-value journey

generated/v1/first-value-journey.json is the one sequence that takes a developer from a credential to an observed callback — the same steps the curl quickstart, the JavaScript quickstart and the website walkthrough render. Read it rather than restating the steps: each entry carries the operation, the method, the path, the scopes it needs, the refusals it can produce and what to do about each of them.

MIT licensed. Issues: https://github.com/flowxo/greatwait/issues.