openapi-versions 0.0.0-stage → 0.0.0

package/docs/adr/template.md

@@ -0,0 +1,16 @@
+# NNNN. Title
+
+- Status: proposed | accepted | superseded by NNNN
+- Date: YYYY-MM-DD
+
+## Context
+
+What forces the decision.
+
+## Decision
+
+What we do.
+
+## Consequences
+
+What gets easier, what gets harder, what to revisit and when.

package/docs/concepts.md

@@ -0,0 +1,67 @@
+# Concepts
+
+## Why this exists
+
+Web, mobile and backend ship on different clocks. The API releases every two weeks, the web app several times a day, and mobile builds stay installed for months. At any moment several client and API versions talk to each other. A client generated from one spec silently assumes the backend matches it. This tool makes the assumption explicit and safe.
+
+## Vocabulary
+
+| Term                        | Meaning                                                                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| **Major**                   | The `1` in `1.6.0`. Breaking changes allowed. Served under its own prefix: `/api/v1`, `/api/v2`.                                |
+| **Minor**                   | The `6` in `1.6.0`. Additive changes only.                                                                                      |
+| **Spec**                    | One OpenAPI JSON document per released version, stored as `specs/<semver>.json`.                                                |
+| **Floor**                   | The oldest minor of a major that the app still supports. Everything present at the floor is assumed on every supported backend. |
+| **Newest spec**             | The highest spec in `specsDir`. It may be a release the backend has not deployed yet.                                           |
+| **Gated operation / field** | Introduced after the floor. Available only when the connected backend reports a version at or above the one that introduced it. |
+| **Backend ahead**           | The backend is newer than the newest spec. Works: unknown fields are ignored, unknown enum values are tolerated.                |
+
+## The three rules
+
+1. **Within a major, changes are additive.** New endpoints, new optional request fields, new response fields, new values of _extensible_ enums. Removing, renaming, retyping, or adding a required request field needs a new major.
+2. **Each app release supports one major**, over a range of its minors (floor to newest spec). Moving to the next major is a new app release.
+3. **Each major has its own prefix and its own `GET <prefix>/version`**, plus an `X-Api-Version` header on every response, as real semver. The app's base URL includes the major, so it never needs to know other majors exist.
+
+## What the client does for each backend
+
+| Connected backend                   | Behaviour                                                                             |
+| ----------------------------------- | ------------------------------------------------------------------------------------- |
+| Same major, older than newest spec  | Works. Operations added later are hidden or disabled.                                 |
+| Same major, newer than newest spec  | Works. Everything known is on. Unknown fields ignored, unknown enum values tolerated. |
+| Same major, below the floor         | Blocked: `backend-too-old`.                                                           |
+| Same major, `Sunset` header present | Works. `useSunset()` returns the date for a banner.                                   |
+| Another major                       | Blocked: `app-too-old`.                                                               |
+| Version changes mid-session         | The next response's `X-Api-Version` triggers re-evaluation and a refetch.             |
+| `/version` not valid semver         | Blocked: `invalid-version`.                                                           |
+
+## How the pieces fit
+
+```
+specs/1.3.0.json … 1.6.0.json  +  openapi-versions.config.json
+        │  codegen (build time, in CI)
+        │   1. keep specs >= floor
+        │   2. oasdiff breaking on each consecutive pair  → fail on any break
+        │   3. tolerant merge into one document
+        │   4. since maps: which version introduced each op / field
+        │   5. openapi-typescript on the merged doc, extensible enums as open unions
+        ▼
+src/generated/v1/{schema.d.ts, meta.ts, merged.openapi.json}
+        │  runtime
+        ▼
+resolveCompat(version) → supports(op) / hasField(field)   ← the single decision point
+        │
+        ├─ $api    typed WITHOUT gated operations (cannot call newer ops: compile error)
+        └─ $gated  typed WITH everything; queries go through gate(), mutations inside <Feature>
+```
+
+No component compares version numbers. Everything asks `supports()`.
+
+## Tolerant reader
+
+Depend on what you need, ignore the rest. Concretely: merged types make fields added after the floor optional, extensible enums are open (`"a" | "b" | (string & {})`) so a `switch` needs a `default`, and unknown response fields are never an error.
+
+## Trade-offs to accept
+
+- It relies on backend discipline. The oasdiff gate belongs in the **backend** CI as well, otherwise a breaking change shipped in a minor makes the merged types describe a shape no server has.
+- Fields added after the floor are typed optional, so the compiler no longer reminds you newer servers always send them. Use `hasField()` for explicit checks.
+- Open enums are open in request bodies too: a typo in a sent value compiles.

package/docs/ecosystem.md

@@ -0,0 +1,39 @@
+# Fit with the openapi-ts ecosystem
+
+`openapi-versions` is deliberately a thin layer on the openapi-ts packages. It adds one capability they do not have: **one client, a range of server versions**.
+
+| openapi-ts piece             | Role here               | How it is used                                                                                                                                                                         |
+| ---------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `openapi-typescript`         | Generates `schema.d.ts` | Called through its Node API (`openapiTS`, `astToString`) on the _merged_ spec. The only extension point used is the documented `transform` hook (for `x-extensible-enum`). Not forked. |
+| `openapi-fetch`              | The HTTP client         | One `createClient<paths>` instance, plus one middleware (`onResponse`) for `X-Api-Version` and `Sunset`.                                                                               |
+| `openapi-react-query`        | Hooks                   | `createClient(fetchClient)` twice: `$api` (types without gated operations) and `$gated` (everything). Query keys are its own, so loaders and `prefetchQuery` work unchanged.           |
+| `openapi-typescript-helpers` | Shared types            | `StripOps` uses `HttpMethod`. A one-line fix to `Readable<T>` is needed for open enums (below).                                                                                        |
+| `swr-openapi`                | SWR hooks               | Not supported yet.                                                                                                                                                                     |
+
+Conventions followed: peer dependencies on the user's `openapi-typescript` / `openapi-fetch` / `openapi-react-query` (no bundled copies), ESM, types for every entry point, `$`-prefixed query client as in the openapi-react-query docs, one generated `schema.d.ts` per major.
+
+## Gaps this fills
+
+| Tool                                | What is missing for multi-version clients                                                     |
+| ----------------------------------- | --------------------------------------------------------------------------------------------- |
+| openapi-typescript                  | One spec in, one `paths` out. No merging of minors, no since-versions, closed enums           |
+| openapi-fetch / openapi-react-query | Typed against one spec. No capability check at runtime                                        |
+| Hey API `openapi-ts`                | Merges _different_ APIs, prefixing colliding paths; not a union of versions of the _same_ API |
+| oasdiff                             | Detects breaks, produces no client                                                            |
+
+## What could be upstreamed
+
+1. **`Readable<T>` / `Writable<T>` primitives fix** in `openapi-typescript-helpers`. The local patch (`patches/`) makes both helpers return primitives as-is, so `string & {}` open unions survive. Without it, `openapi-fetch` response types lose the known values of open enums. Smallest, most valuable contribution; independent of this package.
+2. **`x-extensible-enum` (or an option) as built-in open enums** in openapi-typescript, replacing the `transform` hook in `codegen/open-enums.ts`.
+3. **Multi-spec input** (merge + since map) as a documented recipe or plugin in the openapi-typescript docs, with this package as the reference implementation.
+
+## Naming and docs placement
+
+- Package name: `openapi-versions` (unclaimed on npm when checked; reserve it before publishing).
+- Fits next to `openapi-fetch` and `openapi-react-query` in the docs sidebar as "Versioning": the pages in `docs/` map to _Introduction_ (concepts), _Setup_ (getting-started), _Recipes_ (how-to), _API_ (reference). The openapi-ts docs are VitePress/Markdown, so these files port as they are.
+- Before proposing it upstream, confirm with the maintainers whether they prefer it as a separate package (as here) or an openapi-typescript feature.
+
+## Known constraints
+
+- openapi-typescript 7 requires TypeScript 5 or 6: TypeScript 7 (native port, `latest` on npm) has no `ts.factory`. Upstream issue #2841; open PRs #2867 (bundle a compiler) and #2872 (no runtime compiler dependency).
+- The package is not published yet; `pnpm build` then `npm pack` produces the tarball. A packed install in a fresh app was verified: codegen, generated `client.ts`, and a typecheck of the gating guarantees all pass.

package/docs/getting-started.md

@@ -0,0 +1,99 @@
+# Getting started
+
+## Prerequisites
+
+- Node 20+, **TypeScript 5 or 6** (verified on 5.9 and 6.0; openapi-typescript 7 does not run on TypeScript 7, the native compiler, tracked in openapi-ts/openapi-typescript#2841).
+- [`oasdiff`](https://github.com/oasdiff/oasdiff) on the `PATH` (or `OASDIFF_BIN=/path/to/oasdiff`), version 1.34 or newer. `brew install oasdiff` on macOS. Optional locally (codegen warns and skips the gate without it); set `"gate": "required"` or pass `--require-gate` in CI.
+- A backend that: serves each major under its own prefix, answers `GET <prefix>/version` with `{ "version": "1.6.0" }`, sends `X-Api-Version` on every response, and publishes one OpenAPI JSON spec per release.
+
+## Install
+
+```bash
+npm i openapi-versions
+npm i openapi-fetch openapi-react-query @tanstack/react-query react   # peers: the openapi-ts runtime you already use
+npm i -D openapi-typescript "typescript@<7"
+```
+
+`openapi-versions` is a layer on the openapi-ts packages, not a replacement: it generates types with `openapi-typescript`, calls with `openapi-fetch`, hooks with `openapi-react-query`. React and TanStack Query are optional; without them use `openapi-versions/core`.
+
+Open enums need a one-line fix to `openapi-typescript-helpers` (see [troubleshooting](troubleshooting.md)); apply `patches/` with `patch-package` in your app until it lands upstream.
+
+## 1. Collect the specs
+
+Put one spec per released version in `specs/`, named `<semver>.json`. Take each from the backend CI artifact of the release commit, not from a branch tip.
+
+```
+specs/1.3.0.json
+specs/1.4.0.json
+specs/1.5.0.json
+specs/1.6.0.json   # may be a release the backend has not deployed yet
+```
+
+Mark enums that may grow with `x-extensible-enum` in the spec (see [how-to](how-to.md#declare-an-enum-that-can-grow)).
+
+## 2. Write the config
+
+`openapi-versions.config.json`:
+
+```json
+{
+  "$schema": "./openapi-versions.schema.json",
+  "specsDir": "specs",
+  "outDir": "src/generated",
+  "majors": { "1": { "floor": "1.3.0" } }
+}
+```
+
+The floor must be a real spec file (`specs/1.3.0.json`). See [reference](reference.md#config).
+
+## 3. Generate
+
+```bash
+npx openapi-versions   # or an npm script
+```
+
+You get `src/generated/v1/{schema.d.ts, meta.ts, merged.openapi.json}` and `src/generated/index.ts`. Do not edit them. Commit them or regenerate in CI, as you prefer, but be consistent.
+
+## 4. Import from the generated client
+
+Codegen writes `<outDir>/v<major>/client.ts`: the runtime already bound to this major's types. The import path is the only place the major appears in app code:
+
+```ts
+import { ApiVersionProvider, useApi, Feature, createApi, type Paths } from "./api/v1/client";
+```
+
+`runtimeImport` in the config sets what `client.ts` imports the runtime from (default `openapi-versions`).
+
+## 5. Use it in React
+
+```tsx
+<QueryClientProvider client={queryClient}>
+  <ApiVersionProvider baseUrl="https://host/api/v1">
+    <App />
+  </ApiVersionProvider>
+</QueryClientProvider>;
+```
+
+```tsx
+const { $api, $gated, gate } = useApi();
+
+// available on every supported backend: plain openapi-react-query
+const user = $api.useQuery("get", "/users/{id}", { params: { path: { id } } });
+
+// added after the floor: gate() turns it into skipToken when the backend lacks it
+const activity = useQuery(gate($gated.queryOptions("get", "/users/{id}/activity", { params: { path: { id } } })));
+
+// gated mutation: render the trigger inside <Feature>
+const archive = $gated.useMutation("post", "/users/{id}/archive");
+<Feature requires="post /users/{id}/archive">
+  <button onClick={() => archive.mutate({ params: { path: { id } } })}>Archive</button>
+</Feature>;
+```
+
+## 6. Try it without a backend
+
+`playground/api/mock-backend.ts` is a fetch-compatible fake backend at any version. `pnpm playground` starts a small app with a control panel that "deploys" versions while the app is open. `pnpm playground:api` prints a table of one build against seven backends.
+
+## 7. Wire CI
+
+See [how-to: CI](how-to.md#wire-ci).

package/docs/how-to.md

@@ -0,0 +1,155 @@
+# How-to
+
+Each recipe lists the exact steps. Run `pnpm codegen`, `pnpm typecheck` and `npm test` after changes.
+- [Add the spec of a new backend release](#add-the-spec-of-a-new-backend-release)
+- [Use a feature before the backend ships it](#use-a-feature-before-the-backend-ships-it)
+- [Gate a query, a mutation, a field](#gate-a-query-a-mutation-a-field)
+- [Declare an enum that can grow](#declare-an-enum-that-can-grow)
+- [Raise the floor](#raise-the-floor)
+- [Handle a breaking-change failure](#handle-a-breaking-change-failure)
+- [Move the app to the next major](#move-the-app-to-the-next-major)
+- [Use the API in a router loader or outside React](#use-the-api-in-a-router-loader-or-outside-react)
+- [Mobile (React Native)](#mobile-react-native)
+- [Show an "update before" banner](#show-an-update-before-banner)
+- [Test against several backend versions](#test-against-several-backend-versions)
+- [Wire CI](#wire-ci)
+
+## Add the spec of a new backend release
+
+1. Download the spec from the backend release artifact. Save it as `specs/<version>.json` (e.g. `specs/1.7.0.json`). The file name must be the exact semver.
+2. `pnpm codegen`. The oasdiff gate checks `1.6.0 → 1.7.0`; new operations land in the gated maps automatically.
+3. `git diff src/generated/v1/meta.ts` shows what is newly gated.
+4. Build the feature (see next recipe).
+
+If the spec changes again before the release, overwrite the file and re-run codegen. The gate catches anything that stopped being additive.
+
+## Use a feature before the backend ships it
+
+This is the point of the tool. Add the upcoming spec (as above), build the feature behind `gate()` / `<Feature>`, and release. Users on the old backend never see it and no request is sent. The moment the backend deploys the new version, the next response carries `X-Api-Version`, the provider re-evaluates and the feature appears without a reload.
+
+## Gate a query, a mutation, a field
+
+Operation introduced after the floor, **query**:
+
+```tsx
+const { $gated, gate } = useApi();
+const activity = useQuery(gate($gated.queryOptions("get", "/users/{id}/activity", init)));
+// activity.data is undefined while the backend lacks the operation (skipToken: never fetched)
+```
+
+`gate()` output cannot be passed to `useSuspenseQuery` (compile error, by design: it may be skipped).
+
+**Mutation**: render the trigger only when supported.
+
+```tsx
+const archive = $gated.useMutation("post", "/users/{id}/archive");
+<Feature requires="post /users/{id}/archive" fallback={null}>
+  …
+</Feature>;
+```
+
+**Anywhere**: `useSupports("get /users/{id}/activity")` returns a boolean; outside React use `api.compat.supports(op)`.
+
+**Field** added after the floor: its type is optional. Check explicitly when it matters.
+
+```tsx
+const showAvatar = useHasField("User.avatarUrl");
+```
+
+Operation keys are `"<method> <path>"` in lower-case method, e.g. `"post /users/{id}/archive"`; field keys are `"<Schema>.<property>"`. Both are typed (`GatedOp`, `GatedField`), so a typo is a compile error. Calling a gated operation through `$api` is also a compile error: it exists only on `$gated`.
+
+## Declare an enum that can grow
+
+Plain `enum` is closed: adding a value is a **breaking** change and oasdiff blocks it. For an enum that will grow within a major, the backend declares it with `x-extensible-enum`:
+
+```json
+"status": { "type": "string", "x-extensible-enum": ["active", "invited", "archived"] }
+```
+
+Codegen turns it into an open union, `"active" | "invited" | "archived" | (string & {})`. Autocomplete lists the known values, unknown ones compile, and a `switch` needs a `default` branch:
+
+```ts
+switch (user.status) {
+  case "active": …
+  default: return user.status; // value from a newer backend: show raw, do not crash
+}
+```
+
+Converting an existing closed `enum` to `x-extensible-enum` is itself an API-contract decision: do it at a major boundary, or by adding the extension to every spec of the range.
+
+## Raise the floor
+
+When a backend minor leaves the support window:
+1. Edit `majors.<n>.floor` in `openapi-versions.config.json` (the new floor needs a spec file).
+2. Optionally delete older specs.
+3. `pnpm codegen`. Operations that were gated only against versions below the new floor become ordinary operations.
+4. `pnpm typecheck`. `useSupports(...)` / `<Feature requires=…>` for operations that are no longer gated now error or become dead; remove them.
+
+## Handle a breaking-change failure
+
+`FAIL v1: 1.6.0 -> 1.7.0` with an oasdiff report means a spec removed, renamed or retyped something, or added a required request field, or added a value to a closed enum. Options, in order of preference:
+1. Fix the **backend** so the change is additive (add a new field, keep the old one).
+2. If it was a growable enum, declare it `x-extensible-enum`.
+3. If the break is intended, it belongs in a new major: [Move to the next major](#move-the-app-to-the-next-major).
+
+Do not hand-edit specs to silence the gate: the merged types would then describe a server that does not exist.
+
+## Move the app to the next major
+
+The backend serves both majors side by side for a bounded window; the app switches only by a new release.
+1. Backend ships `/api/v2` and keeps `/api/v1` running, frozen (patches only). Existing apps are unaffected.
+2. Backend adds `Sunset` to v1 responses. 1.x apps show the banner ([recipe](#show-an-update-before-banner)).
+3. In the app repo: put the 2.x specs in `specsDir`, set `majors` to `{ "2": { "floor": "2.0.0" } }`, run codegen, change imports from `…/v1/client` to `…/v2/client`, point `baseUrl` at `/api/v2`, fix compile errors.
+4. When the sunset date passes, the backend removes `/api/v1`. Remaining 1.x builds get the "update the app" screen.
+
+## Use the API in a router loader or outside React
+
+```ts
+import { createApi } from "./api/v1/client";
+const api = await createApi({ baseUrl: "https://host/api/v1" }); // reads /version, throws if unsupported
+await queryClient.ensureQueryData(api.$api.queryOptions("get", "/users/{id}", init));
+```
+
+Without React (scripts, workers, React Native without hooks) import the core from `openapi-versions/core`; the generated client already re-exports `createApi`.
+
+Query keys are openapi-react-query's own (`[method, path, params]`), so the same options work in components, loaders and `prefetchQuery`.
+
+## Mobile (React Native)
+
+`src/core` is framework-free and the React layer works as is. Only the re-check trigger differs: the provider already refetches `/version` on window focus; on React Native wire app resume with TanStack Query's `focusManager` and `AppState`:
+
+```ts
+import { AppState } from "react-native";
+import { focusManager } from "@tanstack/react-query";
+AppState.addEventListener("change", (s) => focusManager.setFocused(s === "active"));
+```
+
+## Show an "update before" banner
+
+```tsx
+const sunset = useSunset(); // Date | undefined, set once a response carries a Sunset header
+return sunset && <Banner>Update before {sunset.toDateString()}</Banner>;
+```
+
+## Test against several backend versions
+
+`createMockBackend(version, { sunset? })` from `playground/api/mock-backend.ts` (a test helper in this repo; copy it) returns `{ fetch, calls, deploy(next) }`. Pass `fetch` to `ApiVersionProvider` or `createApi`, assert on `calls` that no gated request was sent, and call `deploy("1.6.0")` then invalidate queries to simulate a deploy mid-session. `sideBySide({ "/api/v1": …, "/api/v2": … })` simulates two majors. See `test/react.test.tsx` and `test/majors.test.tsx`. Pin the compile-time guarantees with `@ts-expect-error` as in `test/types.check.ts`.
+
+## Wire CI
+
+Backend CI (the important one): run oasdiff on the previous released spec and the new one and block the merge.
+
+```bash
+oasdiff breaking specs/1.6.0.json new-spec.json --fail-on ERR
+```
+
+Client CI:
+
+```bash
+npm ci
+pnpm codegen        # fails on a breaking pair, bad config, or missing floor spec
+git diff --exit-code src/generated   # if generated code is committed
+pnpm typecheck && npm test
+```
+
+`pnpm check:breaking` runs only the gate and writes nothing.

package/docs/reference.md

@@ -0,0 +1,129 @@
+# Reference
+
+## Config
+
+File: `openapi-versions.config.json`. JSON Schema: [`openapi-versions.schema.json`](../openapi-versions.schema.json); add `"$schema": "./openapi-versions.schema.json"` for editor autocompletion. The CLI also validates it and reports what to fix.
+
+| Key                | Type                                          | Meaning                                                                                                                                                                        |
+| ------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `specsDir`         | string                                        | Folder of `<semver>.json` specs. Other file names are ignored.                                                                                                                 |
+| `outDir`           | string                                        | Generated output folder. Safe to delete and regenerate.                                                                                                                        |
+| `majors`           | object                                        | Keyed by major number (`"1"`). Normally one entry per app release.                                                                                                             |
+| `majors.<n>.floor` | plain semver                                  | Oldest supported minor of major `n`. Must be in major `n` and must have a spec file.                                                                                           |
+| `gate`             | `"auto"` \| `"required"` \| `"off"`, optional | Breaking-change gate. `auto` (default): run oasdiff if installed, otherwise warn and skip. `required`: fail when oasdiff is missing or older than 1.34.0. `off`: never run it. |
+| `runtimeImport`    | string, optional                              | Module the generated `client.ts` imports the runtime from. Default `openapi-versions`. A relative path when developing the runtime in the same repo.                           |
+
+## CLI
+
+```
+openapi-versions [--config <path>] [--check-only] [--require-gate]
+```
+
+| Flag             | Effect                                                                                                          |
+| ---------------- | --------------------------------------------------------------------------------------------------------------- |
+| `--config`       | Config path. Default `openapi-versions.config.json`.                                                            |
+| `--check-only`   | Run only the oasdiff gate; write nothing. Fails if oasdiff is missing.                                          |
+| `--require-gate` | Fail when oasdiff is missing or too old, instead of skipping the gate. Same as `"gate": "required"`. Use in CI. |
+
+Exit code 1 on: invalid config, missing floor spec, any breaking pair, and (with `--require-gate`, `"gate": "required"` or `--check-only`) a missing or too-old oasdiff (minimum 1.34.0). Environment: `OASDIFF_BIN` overrides the oasdiff binary.
+
+## Package entry points
+
+| Import                         | Content                                                                                                                        |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `openapi-versions`             | Runtime: `createVersionAware(meta)` (core + React), plus the core exports                                                      |
+| `openapi-versions/core`        | Framework-free runtime: `resolveCompat`, `createApi`, `createApiClient`, `fetchBackendVersion`, `createVersionAwareCore(meta)` |
+| `openapi-versions/codegen`     | Programmatic codegen API                                                                                                       |
+| `openapi-versions/schema.json` | JSON Schema of the config                                                                                                      |
+| `npx openapi-versions`         | The CLI                                                                                                                        |
+
+Apps rarely call `createVersionAware` themselves: the generated `client.ts` does, with the app's types. Peers: `openapi-typescript`, `openapi-fetch`, and optionally `openapi-react-query`, `@tanstack/react-query`, `react`.
+
+In this repo: `pnpm codegen`, `pnpm check:breaking`, `pnpm build` (bundles with tsup into `dist/`).
+
+## Programmatic API
+
+```ts
+import { build, loadConfig, mergeAll, computeSince, checkChain, openEnums, BreakingChangeError } from "openapi-versions/codegen";
+
+const report = await build(loadConfig("openapi-versions.config.json"), { checkOnly: false, log: console.log });
+```
+
+| Export                                     | Purpose                                                                              |
+| ------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `build(config, { checkOnly?, log? })`      | Whole pipeline. Throws `BreakingChangeError` (with `.report`) if a pair is breaking. |
+| `loadConfig(path)` / `validateConfig(obj)` | Read and validate config.                                                            |
+| `mergeAll(docs)` / `mergeTolerant(a, b)`   | Tolerant merge of OpenAPI documents.                                                 |
+| `computeSince(docs, floor)`                | `{ ops, gatedOps, gatedFields }`                                                     |
+| `checkChain(files)` / `checkPair(a, b)`    | oasdiff gate.                                                                        |
+| `openEnums`                                | openapi-typescript `transform` hook for `x-extensible-enum`.                         |
+
+## Pipeline, per major
+
+1. Select specs with the same major and version `>=` floor. The floor spec must exist.
+2. `oasdiff breaking <prev> <next> --fail-on ERR` for each consecutive pair.
+3. Tolerant merge (rules below). `info.version` of the merged doc becomes `"<floor> - <newest>"`.
+4. Since maps.
+5. `openapi-typescript` on the merged doc with the `openEnums` transform.
+
+## Merge rules
+
+| Element                                   | Rule                                                      |
+| ----------------------------------------- | --------------------------------------------------------- |
+| paths, operations, properties, parameters | union                                                     |
+| `required` array on a schema              | intersection (required only if every version requires it) |
+| `required` boolean on a parameter or body | AND                                                       |
+| parameter present in only some versions   | never required (path params stay required)                |
+| `enum`, primitive arrays                  | union of values, order kept                               |
+| everything else (descriptions, formats …) | newest wins                                               |
+
+The inputs must be non-breaking relative to each other (step 2); otherwise the union can describe a shape no server ever had.
+
+## Since maps
+
+- `gatedOps`: `"<method> <path>" → first version that has it`, only for versions above the floor.
+- `gatedFields`: `"<Schema>.<property>" → first version`, only for properties added to a schema that already existed in an earlier version (fields born with their schema are covered by the operation that returns it).
+- `ops`: every operation key in the merged contract.
+
+## Generated files
+
+| File                                | Content                                                                                                                                                                           |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<outDir>/v<n>/schema.d.ts`         | openapi-typescript types of the merged contract; extensible enums are open unions                                                                                                 |
+| `<outDir>/v<n>/meta.ts`             | `meta = { major, floor, newest, specs, ops, gatedOps, gatedFields }` plus `Op`, `GatedOp`, `GatedField` types                                                                     |
+| `<outDir>/v<n>/merged.openapi.json` | the merged document (useful to inspect or diff)                                                                                                                                   |
+| `<outDir>/v<n>/client.ts`           | the runtime bound to this major: `ApiVersionProvider`, `useApi`, `useSupports`, `useHasField`, `useSunset`, `Feature`, `createApi`, types `Paths`, `GatedOp`, `GatedField`, `Api` |
+| `<outDir>/index.ts`                 | `majors`, `SupportedMajor`, and `PathsV<n>`, `GatedOpV<n>`, `GatedFieldV<n>` aliases                                                                                              |
+
+## Runtime API
+
+Exported from the generated `client.ts` (bound to your types) and, unbound, from `openapi-versions` / `openapi-versions/core`:
+
+| Symbol                                                                                    | Meaning                                                                                                                                                                                                          |
+| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `resolveCompat(version, majors, { prereleaseAsRelease? })`                                | Returns `{ status: "ok", version, major, backendAhead, supports(op), hasField(field) }` or `{ status: "backend-too-old", floor }`, `{ status: "app-too-old", supportedMajors }`, `{ status: "invalid-version" }` |
+| `createApi({ baseUrl, fetch?, prereleaseAsRelease? })` (unbound: `createApi(meta, opts)`) | Reads `<baseUrl>/version`, returns `Api`; throws if not `ok`                                                                                                                                                     |
+| `Api`                                                                                     | `{ compat, client: { core, gated }, $api, $gated, gate() }`                                                                                                                                                      |
+| `$api`                                                                                    | openapi-react-query client typed **without** gated operations                                                                                                                                                    |
+| `$gated`                                                                                  | `{ queryOptions, useMutation }` typed with everything                                                                                                                                                            |
+| `gate(options)`                                                                           | Replaces `queryFn` with `skipToken` when the backend lacks the operation                                                                                                                                         |
+| `createApiClient({ baseUrl, fetch?, onVersionHeader?, onSunsetHeader? })`                 | The single openapi-fetch client; middleware reads `X-Api-Version` and `Sunset`                                                                                                                                   |
+
+React part:
+
+| Symbol                                                                             | Meaning                                                                                                                                                                         |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<ApiVersionProvider baseUrl fetch? loading? renderBlocked? prereleaseAsRelease?>` | Fetches `/version` (React Query key `["api-version"]`, stale 5 min, refetch on focus), renders `renderBlocked(compat)` when not `ok`, re-evaluates when `X-Api-Version` changes |
+| `useApi()`                                                                         | The `Api` object; throws outside the provider                                                                                                                                   |
+| `useSupports(op)` / `useHasField(field)`                                           | Booleans                                                                                                                                                                        |
+| `<Feature requires fallback?>`                                                     | Renders children only if the operation is supported                                                                                                                             |
+| `useSunset()`                                                                      | `Date                                                                                                                                                                           | undefined`from the`Sunset` header |
+
+## Backend contract
+
+- Additive changes only inside a major (oasdiff gate).
+- Growable enums declared `x-extensible-enum`.
+- Each major under its own prefix; `GET <prefix>/version` → `{ "version": "<semver>" }`; `X-Api-Version` on every response; real semver.
+- `/api/v1/version` reports the version of the v1 **contract**, not of the deployment; after v2 ships, v1 is frozen (patch versions only).
+- A major being retired sends `Sunset: <HTTP-date>` (RFC 8594) on all its responses.
+- Each release publishes its spec as a CI artifact from the release commit.

package/docs/troubleshooting.md

@@ -0,0 +1,21 @@
+# Troubleshooting
+
+| Symptom                                                                                       | Cause                                                                                                                                            | Fix                                                                                                                                                                                                     |
+| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Breaking-change gate cannot run: oasdiff not found` (or `WARN breaking-change gate skipped`) | oasdiff not on `PATH`, or older than 1.34.0                                                                                                      | Install it (`brew install oasdiff`) or set `OASDIFF_BIN=/abs/path/oasdiff`. The error only appears with `"gate": "required"`, `--require-gate` or `--check-only`; otherwise codegen warns and continues |
+| `Floor 1.3.0 has no spec file (oldest found: 1.4.0)`                                          | The floor needs its own `specs/1.3.0.json`                                                                                                       | Add the spec or lower/raise the floor to an existing one                                                                                                                                                |
+| `No spec found for major 1 at or above floor 1.3.0`                                           | Wrong `specsDir`, or files not named `<semver>.json`                                                                                             | Check the directory and file names; non-semver names are ignored                                                                                                                                        |
+| `config: majors.1.floor 2.0.0 is not in major 1`                                              | Floor belongs to another major                                                                                                                   | Fix the floor or the major key                                                                                                                                                                          |
+| `FAIL v1: a -> b`                                                                             | A spec pair is not additive                                                                                                                      | [How-to: breaking-change failure](how-to.md#handle-a-breaking-change-failure)                                                                                                                           |
+| oasdiff reports `response-property-enum-value-added`                                          | A closed `enum` gained a value                                                                                                                   | Declare it `x-extensible-enum` (see how-to) or move it to a new major                                                                                                                                   |
+| Calling a newer operation through `$api` does not compile                                     | By design: it exists only on `$gated`                                                                                                            | Use `$gated` with `gate()` or `<Feature>`                                                                                                                                                               |
+| `useSuspenseQuery(gate(...))` does not compile                                                | A gated query may be skipped                                                                                                                     | Use `useQuery`                                                                                                                                                                                          |
+| Enum type collapses to `string` and loses autocompletion in response data                     | `openapi-fetch`'s `Readable<T>` maps over `string & {}`                                                                                          | Apply the one-line patch in `patches/` to `openapi-typescript-helpers` with `patch-package` (add `"postinstall": "patch-package"` to your app). Until it is fixed upstream                              |
+| App says "app too old" for a date-style version such as `2026.10.1`                           | Valid semver with major 2026                                                                                                                     | The backend must report real `major.minor.patch`                                                                                                                                                        |
+| `GET /version failed: 404`                                                                    | `/version` resolved from the host root                                                                                                           | `baseUrl` must include the major prefix; `/version` is read relative to it (`https://host/api/v1/version`)                                                                                              |
+| Endless refetching after a deploy                                                             | Version header seen again before React re-rendered                                                                                               | The provider records the new version synchronously; do not clone this logic without that                                                                                                                |
+| Staging on `1.6.0-rc.1` hides 1.6 features                                                    | A prerelease sorts before its release                                                                                                            | Pass `prereleaseAsRelease` to `ApiVersionProvider` / `createApi` for staging builds                                                                                                                     |
+| A gated field is `undefined` on a new backend                                                 | Fields added after the floor are typed optional and may be absent                                                                                | Use `hasField()` and handle absence                                                                                                                                                                     |
+| `src/generated` missing, imports fail                                                         | Codegen not run                                                                                                                                  | `pnpm codegen`                                                                                                                                                                                       |
+| `Cannot read properties of undefined (reading 'createKeywordTypeNode')` when generating       | openapi-typescript 7 needs the TypeScript 5 or 6 JS compiler API; TypeScript 7 (native, now `latest` on npm) does not expose it (upstream #2841) | Install `typescript@<7` (5 or 6)                                                                                                                                                                        |
+| `Cannot find module 'openapi-versions'` from a generated `client.ts`                          | Runtime not installed, or `runtimeImport` wrong                                                                                                  | `npm i openapi-versions`, or set `runtimeImport` in the config                                                                                                                                          |