openapi-versions 0.0.0-stage → 0.0.0

package/docs/upstream-drafts.md

@@ -0,0 +1,166 @@
+# Upstream drafts (NOT posted)
+
+> **Status 2026-10-25 — draft 1 is superseded.** [openapi-ts/openapi-typescript#2766](https://github.com/openapi-ts/openapi-typescript/pull/2766) (open, review required) contains the same fix (primitive guard before `T extends object` in `Readable`/`Writable`). Do not post a duplicate; add the repro below as a comment there. Related: [#2415](https://github.com/openapi-ts/openapi-typescript/pull/2415) (merged, unreleased, queued for openapi-typescript 7.14.0 in release PR #2616) makes openapi-typescript itself emit `(literals) | (string & {})` for `additionalProperties: true` string enums, which hits this bug in every openapi-fetch consumer once released. Both are reasons to drop `patches/` once they ship.
+
+Two drafts for the openapi-ts repository (`openapi-ts/openapi-typescript`). Nothing here has been sent. Before posting: search existing issues for duplicates, re-run the repro on the latest versions, and fill in the placeholders in `<angle brackets>`.
+
+Versions used for the repro: `openapi-fetch@0.17.0`, `openapi-typescript-helpers@0.1.0`, `openapi-typescript@7.13`, `typescript@5.9`.
+
+---
+
+## 1. Bug + PR: `Readable<T>` / `Writable<T>` turn `string & {}` into an object type
+
+**Package:** `openapi-typescript-helpers`
+
+### Title
+
+`Readable<T>` and `Writable<T>` map over `string & {}`, so open string unions lose their open member
+
+### Description
+
+Open string unions such as `"a" | "b" | (string & {})` are a common way to say "these values are known, others may appear" while keeping editor completion. `Readable<T>` and `Writable<T>` do not preserve them: `string & {}` matches the `T extends object` branch, and the mapped type then produces an object with all of `String`'s members instead of a string.
+
+`openapi-fetch` wraps every response in `Readable<…>` (and every request body in `Writable<…>`), so the problem shows up in `data` and `error` of every call whose schema contains such a type, for instance a schema generated with a `transform` hook that emits open enums.
+
+### Reproduction
+
+`schema.d.ts` (the shape openapi-typescript emits with a transform that makes a string enum open):
+
+```ts
+export interface paths {
+  "/users/{id}": {
+    parameters: { query?: never; header?: never; path?: never; cookie?: never };
+    get: {
+      parameters: { query?: never; header?: never; path: { id: string }; cookie?: never };
+      requestBody?: never;
+      responses: {
+        200: {
+          headers: { [name: string]: unknown };
+          content: { "application/json": { id: string; status: "active" | "invited" | "archived" | (string & {}) } };
+        };
+      };
+    };
+  };
+}
+```
+
+```ts
+import createClient from "openapi-fetch";
+import type { paths } from "./schema";
+
+const client = createClient<paths>({ baseUrl: "http://x" });
+const { data } = await client.GET("/users/{id}", { params: { path: { id: "1" } } });
+
+export const asString: string = data!.status; // error
+export function label(s: NonNullable<typeof data>["status"]) {
+  switch (s) {
+    case "active":
+      return "A";
+    default:
+      return s.toUpperCase();
+  } // error
+}
+```
+
+### Actual
+
+```
+error TS2322: Type '"active" | "invited" | "archived" | { readonly [x: number]: string; toString: {}; charAt: {}; charCodeAt: {}; concat: {}; indexOf: {}; ... }' is not assignable to type 'string'.
+error TS2349: This expression is not callable. Not all constituents of type '(() => string) | {}' are callable.
+```
+
+The open member became `{ readonly [x: number]: string; toString: {}; charAt: {}; … }`.
+
+### Expected
+
+`Readable<"a" | (string & {})>` is `"a" | (string & {})`: primitives are returned unchanged, only objects and arrays are mapped.
+
+### Cause
+
+In `Readable<T>` (and `Writable<T>`) the last branches are:
+
+```ts
+… : T extends (infer E)[] ? Readable<E>[]
+  : T extends object ? { [K in keyof T as …]: Readable<T[K]> }
+  : T;
+```
+
+`string & {}` is assignable to `object`'s mapped path, so the mapped type iterates the keys of `String`.
+
+### Proposed fix
+
+Return primitives before the object branch, in both helpers:
+
+```diff
+-type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? Readable<U> : T extends (infer E)[] ? Readable<E>[] : T extends object ? { … } : T;
++type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? Readable<U> : T extends (infer E)[] ? Readable<E>[] : T extends string | number | boolean | bigint | symbol ? T : T extends object ? { … } : T;
+```
+
+and the same line in `Writable<T>`. A drop-in diff against 0.1.0 is in this repo: `patches/openapi-typescript-helpers@0.1.0.patch` (pnpm format).
+
+With the patch applied, the repro above compiles; `"zzz"` is accepted where a newer backend sends an unknown value and `switch` still narrows the known cases.
+
+### PR checklist (when posting)
+
+- [ ] Add a type test next to the existing helper tests: `Readable<"a" | (string & {})>` equals `"a" | (string & {})`, and the same for `Writable`.
+- [ ] Add a changeset for `openapi-typescript-helpers` (patch).
+- [ ] Confirm other primitives are unaffected (`number`, `boolean`, `null`, template literal types).
+- [ ] Mention that it also fixes `branded` primitives such as `string & { __brand: "x" }` (verify before claiming).
+
+---
+
+## 2. Discussion / proposal: multi-version input ("one client, a range of server versions")
+
+**Where:** GitHub Discussion (Ideas) first, not an issue. This is a feature request that may belong outside the core.
+
+### Title
+
+Supporting a range of API minor versions from one generated client: merge + since-map + capability gating
+
+### Problem
+
+A client often has to work against more than one version of the same API at once: mobile builds stay installed for months, the web app deploys continuously while the backend deploys on its own cycle, staging and on-prem differ from production. Today `openapi-typescript` takes one document and `openapi-fetch` / `openapi-react-query` assume the server matches it. That breaks in both directions: a client ahead of the server calls operations that 404, a client behind the server meets values and fields it has never seen.
+
+I did not find an existing tool for this. Hey API's multi-input merges different APIs and prefixes colliding paths; oasdiff detects breaking changes but produces no client.
+
+### What I built (works today, outside the core)
+
+A wrapper around the Node API of `openapi-typescript`, no fork, published as `<package>`:
+1. **Inputs:** one spec per released version of one major, plus a _floor_ (oldest supported minor).
+2. **Gate:** `oasdiff breaking` on each consecutive pair; the build fails on any break. Inside a major, changes must be additive.
+3. **Tolerant merge:** paths, operations and properties are the union; `required` is the intersection; enums are the union; the rest is newest-wins.
+4. **Since maps:** for operations and schema fields introduced after the floor, the first version that has them.
+5. **Generation:** `openapiTS(mergedDocument, { transform })`. The `transform` hook turns `x-extensible-enum` into open unions (`"a" | "b" | (string & {})`).
+6. **Runtime (separate, thin):** reads `GET <base>/version` and `X-Api-Version`, and exposes `supports(op)` / `hasField(field)`. A second `openapi-react-query` client is typed with gated operations removed, so calling a newer operation without a capability check is a compile error.
+
+Evidence: a prototype with 34 tests runs one client build against seven backend versions plus two majors side by side, and never sends a request to an operation the connected backend lacks. A packed install into a fresh app generates and type-checks.
+
+### What I am asking
+
+Which of these would you like, if any?
+- **A. Nothing in core.** The wrapper stays a separate package. Could the docs list it under ecosystem / recipes?
+- **B. Documented recipe** for multi-spec input using the existing `transform` hook and Node API (no code in core).
+- **C. Small core hooks** that would make the wrapper simpler: (i) built-in open enums from an extension keyword (today: custom `transform`), (ii) a way to pass several documents and receive the merged one, (iii) exposing the operation list (`"<method> <path>"` keys) with the schema.
+
+Separately, I will open the `Readable` / `Writable` fix as its own PR (see above); it is independent of this proposal.
+
+### Open design questions I would like feedback on
+
+- Is `x-extensible-enum` the right keyword, or should open enums use another convention?
+- Should "closed vs open enum" be a first-class concept in openapi-typescript?
+- The merge is only sound if the inputs are non-breaking relative to each other. Is it better to run the oasdiff gate inside the tool or leave it to CI?
+- Fields added after the floor become optional in the merged types. Is there a better representation (for example a branded "since" type)?
+
+### Links
+
+- Repo: `<repo url>`
+- Concepts and how-tos: `<docs url>`
+- Example app (control panel that "deploys" backend versions while the app is open): `<url or gif>`
+
+---
+
+## Posting order I would suggest
+
+1. Open the `Readable` / `Writable` PR first: small, self-contained, needs no discussion.
+2. Post the discussion after the PR, linking it as evidence that the open-enum use case is real.
+3. Only after maintainers respond, decide between options A, B and C.

package/openapi-versions.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/schemas/openapi-versions.schema.json",
+  "title": "openapi-versions.config.json",
+  "description": "Configuration of the version-aware codegen: which OpenAPI specs to merge, per API major, and from which minor (the floor) the app supports.",
+  "type": "object",
+  "required": ["specsDir", "outDir", "majors"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Path or URL of this schema, for editor autocompletion."
+    },
+    "specsDir": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Directory holding one spec per released version, named <semver>.json (e.g. specs/1.4.0.json). Files whose name is not valid semver are ignored."
+    },
+    "outDir": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Directory the generated code is written to: <outDir>/v<major>/{schema.d.ts, meta.ts, merged.openapi.json} and <outDir>/index.ts. Safe to delete and regenerate."
+    },
+    "majors": {
+      "type": "object",
+      "description": "API majors this app build supports, keyed by major number. One app release normally lists exactly one.",
+      "minProperties": 1,
+      "propertyNames": {
+        "pattern": "^(0|[1-9][0-9]*)$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["floor"],
+        "additionalProperties": false,
+        "properties": {
+          "floor": {
+            "type": "string",
+            "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$",
+            "description": "Oldest minor of this major the app still supports, as a plain semver (e.g. 1.3.0). A spec file named <floor>.json must exist. Operations and fields introduced after the floor are gated at runtime; everything at the floor is assumed on every supported backend."
+          }
+        }
+      }
+    },
+    "gate": {
+      "type": "string",
+      "enum": ["auto", "required", "off"],
+      "default": "auto",
+      "description": "Breaking-change gate (oasdiff) between consecutive specs. auto: run it when oasdiff is installed, warn and skip otherwise. required: fail when oasdiff is missing or too old (use in CI, or pass --require-gate). off: never run it."
+    },
+    "runtimeImport": {
+      "type": "string",
+      "minLength": 1,
+      "default": "openapi-versions",
+      "description": "Module specifier the generated v<major>/client.ts imports the runtime from. Leave unset when the runtime is installed as the `openapi-versions` package; set a relative path when developing the runtime in the same repo."
+    }
+  }
+}

package/package.json

@@ -1,6 +1,116 @@
 {
   "name": "openapi-versions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Multi-version OpenAPI client for the openapi-ts ecosystem: merges the minor specs of one API major, generates tolerant types with openapi-typescript, and gates features at runtime.",
+  "scripts": {
+    "codegen:playground": "rm -rf playground/generated && tsx codegen/cli.ts --config playground/openapi-versions.config.json",
+    "codegen:test": "rm -rf test/fixtures/generated && tsx codegen/cli.ts --config test/fixtures/openapi-versions.config.json",
+    "codegen": "npm run codegen:playground && npm run codegen:test",
+    "check:breaking": "tsx codegen/cli.ts --check-only --config playground/openapi-versions.config.json",
+    "typecheck": "npm run codegen:test && npm run codegen:playground && tsc --noEmit",
+    "test": "npm run codegen:test && vitest run",
+    "playground": "npm run codegen:playground && vite --config playground/app/vite.config.ts",
+    "playground:api": "npm run codegen:playground && tsx playground/api/run.ts",
+    "build:playground": "npm run codegen:playground && vite build --config playground/app/vite.config.ts",
+    "build": "tsup",
+    "prepack": "npm run build",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "changeset": "changeset",
+    "release": "pnpm build && changeset publish"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NoZiL/openapi-versions.git"
+  },
+  "homepage": "https://github.com/NoZiL/openapi-versions#readme",
+  "bugs": {
+    "url": "https://github.com/NoZiL/openapi-versions/issues"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/semver": "^7.8.0",
+    "jsdom": "^30.1.3",
+    "tsup": "^9.0.0",
+    "tsx": "^4.23.15",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
+    "openapi-fetch": "^0.17.0",
+    "openapi-react-query": "^0.5.4",
+    "openapi-typescript": "^7.13.0",
+    "openapi-typescript-helpers": "^0.1.0",
+    "@tanstack/react-query": "^5.104.5",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "@biomejs/biome": "^2.6.2",
+    "@changesets/cli": "^3.0.3"
+  },
+  "dependencies": {
+    "semver": "^7.8.5",
+    "typescript": "^5.9.3"
+  },
+  "type": "module",
+  "bin": {
+    "openapi-versions": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./codegen": {
+      "types": "./dist/codegen.d.ts",
+      "import": "./dist/codegen.js"
+    },
+    "./schema.json": "./openapi-versions.schema.json"
+  },
+  "files": [
+    "dist",
+    "openapi-versions.schema.json",
+    "docs",
+    "skills",
+    "patches"
+  ],
+  "keywords": [
+    "openapi",
+    "openapi-typescript",
+    "openapi-fetch",
+    "openapi-react-query",
+    "api-versioning",
+    "semver",
+    "codegen"
+  ],
+  "peerDependencies": {
+    "openapi-typescript": "^7.13.0",
+    "openapi-fetch": "^0.17.0",
+    "openapi-react-query": "^0.5.4",
+    "openapi-typescript-helpers": "^0.1.0",
+    "@tanstack/react-query": "^5.104.5",
+    "react": "^19.3.1"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "openapi-react-query": {
+      "optional": true
+    }
+  },
+  "packageManager": "pnpm@12.3.4",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/patches/openapi-typescript-helpers@0.1.0.patch

@@ -0,0 +1,51 @@
+diff --git a/dist/index.d.cts b/dist/index.d.cts
+index 077c7b86d92878fe71b70d379f29027ae7bb2940..90b5181d898c69b0ac95643733407d633f807558 100644
+--- a/dist/index.d.cts
++++ b/dist/index.d.cts
+@@ -155,10 +155,10 @@ type $Read<T> = {
+ type $Write<T> = {
+     readonly $write: T;
+ };
+-type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? Readable<U> : T extends (infer E)[] ? Readable<E>[] : T extends object ? {
++type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? Readable<U> : T extends (infer E)[] ? Readable<E>[] : T extends string | number | boolean | bigint | symbol ? T : T extends object ? {
+     [K in keyof T as NonNullable<T[K]> extends $Write<any> ? never : K]: Readable<T[K]>;
+ } : T;
+-type Writable<T> = T extends $Read<any> ? never : T extends $Write<infer U> ? Writable<U> : T extends (infer E)[] ? Writable<E>[] : T extends object ? {
++type Writable<T> = T extends $Read<any> ? never : T extends $Write<infer U> ? Writable<U> : T extends (infer E)[] ? Writable<E>[] : T extends string | number | boolean | bigint | symbol ? T : T extends object ? {
+     [K in keyof T as NonNullable<T[K]> extends $Read<any> ? never : K]: Writable<T[K]>;
+ } & {
+     [K in keyof T as NonNullable<T[K]> extends $Read<any> ? K : never]?: never;
+diff --git a/dist/index.d.mts b/dist/index.d.mts
+index 077c7b86d92878fe71b70d379f29027ae7bb2940..90b5181d898c69b0ac95643733407d633f807558 100644
+--- a/dist/index.d.mts
++++ b/dist/index.d.mts
+@@ -155,10 +155,10 @@ type $Read<T> = {
+ type $Write<T> = {
+     readonly $write: T;
+ };
+-type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? Readable<U> : T extends (infer E)[] ? Readable<E>[] : T extends object ? {
++type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? Readable<U> : T extends (infer E)[] ? Readable<E>[] : T extends string | number | boolean | bigint | symbol ? T : T extends object ? {
+     [K in keyof T as NonNullable<T[K]> extends $Write<any> ? never : K]: Readable<T[K]>;
+ } : T;
+-type Writable<T> = T extends $Read<any> ? never : T extends $Write<infer U> ? Writable<U> : T extends (infer E)[] ? Writable<E>[] : T extends object ? {
++type Writable<T> = T extends $Read<any> ? never : T extends $Write<infer U> ? Writable<U> : T extends (infer E)[] ? Writable<E>[] : T extends string | number | boolean | bigint | symbol ? T : T extends object ? {
+     [K in keyof T as NonNullable<T[K]> extends $Read<any> ? never : K]: Writable<T[K]>;
+ } & {
+     [K in keyof T as NonNullable<T[K]> extends $Read<any> ? K : never]?: never;
+diff --git a/dist/index.d.ts b/dist/index.d.ts
+index 077c7b86d92878fe71b70d379f29027ae7bb2940..90b5181d898c69b0ac95643733407d633f807558 100644
+--- a/dist/index.d.ts
++++ b/dist/index.d.ts
+@@ -155,10 +155,10 @@ type $Read<T> = {
+ type $Write<T> = {
+     readonly $write: T;
+ };
+-type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? Readable<U> : T extends (infer E)[] ? Readable<E>[] : T extends object ? {
++type Readable<T> = T extends $Write<any> ? never : T extends $Read<infer U> ? Readable<U> : T extends (infer E)[] ? Readable<E>[] : T extends string | number | boolean | bigint | symbol ? T : T extends object ? {
+     [K in keyof T as NonNullable<T[K]> extends $Write<any> ? never : K]: Readable<T[K]>;
+ } : T;
+-type Writable<T> = T extends $Read<any> ? never : T extends $Write<infer U> ? Writable<U> : T extends (infer E)[] ? Writable<E>[] : T extends object ? {
++type Writable<T> = T extends $Read<any> ? never : T extends $Write<infer U> ? Writable<U> : T extends (infer E)[] ? Writable<E>[] : T extends string | number | boolean | bigint | symbol ? T : T extends object ? {
+     [K in keyof T as NonNullable<T[K]> extends $Read<any> ? never : K]: Writable<T[K]>;
+ } & {
+     [K in keyof T as NonNullable<T[K]> extends $Read<any> ? K : never]?: never;

package/skills/openapi-versions-add-spec/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: openapi-versions-add-spec
+description: Add a new backend release spec, raise the floor, fix a breaking-change failure, or move the app to the next API major in the version-aware client. Use when the backend ships a new minor, when `pnpm codegen` fails with `FAIL v1: a -> b` or an oasdiff report, or when a version leaves the support window.
+---
+
+# Add a spec, raise the floor, handle breaks
+
+Details and rationale: `docs/how-to.md`.
+
+## A new backend release (minor)
+
+1. Save the release's spec as `specs/<exact semver>.json` (from the backend CI artifact, not a branch tip). It may be unreleased: its features stay hidden until the backend reports that version.
+2. `pnpm codegen`.
+3. `git diff src/generated/v1/meta.ts`: new keys in `gatedOps` / `gatedFields` are what the app can now gate. Report them to the user.
+4. If the spec changed again before release, overwrite the file and re-run.
+
+## Codegen fails with `FAIL v1: X -> Y`
+
+The pair is not additive (removed/renamed/retyped, new required request field, or value added to a closed `enum`). In order:
+1. Tell the user the backend change must be made additive. Quote the oasdiff report.
+2. If the report is `response-property-enum-value-added` and the enum is meant to grow: the backend declares it `x-extensible-enum`.
+3. If the break is intended: it needs a new major (below).
+NEVER edit a spec to silence the gate, never delete the offending spec, never bypass `checkChain`.
+
+## Raise the floor
+
+1. Set `majors.<n>.floor` in `openapi-versions.config.json` (a spec file with that exact version must exist).
+2. `pnpm codegen`, then `pnpm typecheck`.
+3. Operations now at-or-below the floor are ungated: remove `useSupports`/`<Feature requires>`/`gate()` that the compiler flags or that guard operations no longer in `gatedOps`.
+
+## Next major
+
+Backend serves `/api/vN+1` side by side with the frozen `/api/vN` (with `Sunset`). In the app: set `majors` to `{ "<N+1>": { "floor": "<N+1>.0.0" } }`, add the new specs, change imports from `…/v<N>/client` to `…/v<N+1>/client`, point `baseUrl` at `/api/v<N+1>`, run codegen, fix compile errors. This is a new app release; the app never switches majors at runtime.
+
+## Verify
+
+`pnpm codegen && pnpm typecheck && npm test`. Report what changed in `meta.ts`.

package/skills/openapi-versions-gate-feature/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: openapi-versions-gate-feature
+description: Use an API operation or field that only exists on newer backend versions, in an app built with the version-aware client. Use when writing UI or data code against operations in `gatedOps`/`gatedFields`, when TypeScript says an operation does not exist on `$api`, or when handling an extensible enum.
+---
+
+# Gate a feature in app code
+
+Source of truth for what is gated: `src/generated/v<n>/meta.ts` (`gatedOps`, `gatedFields`: key → version that introduced it). Anything not listed exists on every supported backend and is used normally through `$api`.
+
+## Pick the pattern
+
+| Need | Code |
+|---|---|
+| Always-available operation | `const { $api } = useApi(); $api.useQuery("get", "/users/{id}", init)` |
+| Gated **query** | `const { $gated, gate } = useApi(); useQuery(gate($gated.queryOptions("get", "/users/{id}/activity", init)))` |
+| Gated **mutation** | `const m = $gated.useMutation("post", "/users/{id}/archive");` and render the trigger inside `<Feature requires="post /users/{id}/archive" fallback={…}>` |
+| Boolean check | `useSupports("get /users/{id}/activity")`; outside React `api.compat.supports(op)` |
+| Gated **field** | `useHasField("User.avatarUrl")`; the field is typed optional |
+| Loader / outside React | `const api = await createApi({ baseUrl }); api.$api.queryOptions(...)` |
+
+Operation keys: lower-case method + space + path template. Field keys: `Schema.property`.
+
+## Rules
+
+- A gated operation is NOT on `$api` (compile error is intended). Do not cast around it; use `$gated`.
+- `gate()` results cannot go to `useSuspenseQuery` (may be skipped). Use `useQuery`.
+- Never read or compare the backend version in a component. Ask `supports` / `hasField`.
+- Provide a sensible UI when the feature is off (`fallback`, or render nothing). No error state: an unsupported operation is never called.
+- Extensible enums are open unions: always a `default` branch in `switch`, showing the raw value. Do not narrow with `as`.
+- Newer backends may send fields the app does not know: ignore them, never validate strictly against the generated shape.
+
+## Check
+
+`pnpm typecheck`. For behaviour, test with `createMockBackend(version)` from `playground/api/mock-backend.ts` against a version below, at, and above the feature (see `test/react.test.tsx`): assert the control is absent below, present at/above, and that `backend.calls` contains no request to the gated path below.

package/skills/openapi-versions-setup/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: openapi-versions-setup
+description: Set up the version-aware API client (multi-minor OpenAPI codegen on top of openapi-typescript) in an app, or verify an existing setup. Use when the user wants one client to work against a range of backend minor versions, mentions openapi-versions.config.json, specs/<semver>.json, floor, gating, or X-Api-Version.
+---
+
+# Set up the version-aware client
+
+Read `docs/concepts.md` once if the vocabulary (major, minor, floor, gated) is unclear. Reference: `docs/reference.md`.
+
+## Checklist
+
+1. **oasdiff**: `command -v oasdiff` (else `brew install oasdiff` or set `OASDIFF_BIN`). Without it codegen warns and skips the gate; set `"gate": "required"` (or pass `--require-gate`) in CI.
+2. **Specs**: `specs/<semver>.json`, one per released version of ONE major, from the backend release artifacts. Ask the user where to get them if absent; never invent specs.
+3. **Config** `openapi-versions.config.json`:
+   ```json
+   { "$schema": "./openapi-versions.schema.json", "specsDir": "specs", "outDir": "src/generated", "majors": { "1": { "floor": "1.3.0" } } }
+   ```
+   The floor is the oldest minor the app supports and must have its own spec file. Ask the user for the floor if unknown (default suggestion: the oldest minor running in any environment: prod, staging, on-prem).
+4. **Generate**: `npx openapi-versions` (or an npm script). Expect `ok v1: a -> b` lines then `gen v1: …`.
+5. **Install**: `npm i openapi-versions openapi-fetch openapi-react-query @tanstack/react-query` and `npm i -D openapi-typescript "typescript@<7"`; apply the `openapi-typescript-helpers` patch from `patches/` (patch-package).
+   Import everything from the generated `<outDir>/v<n>/client.ts` (`ApiVersionProvider`, `useApi`, `Feature`, `createApi`, `Paths`); the major appears only in that import path.
+6. **Provider**: wrap the app in `QueryClientProvider` then `<ApiVersionProvider baseUrl="https://host/api/v<n>">`. The base URL must include the major prefix; `/version` is read relative to it.
+7. **Verify**: `pnpm typecheck && npm test`; for a visual check `pnpm playground`.
+
+## Backend prerequisites (confirm, do not assume)
+
+`GET <prefix>/version` → `{"version":"<real semver>"}`; `X-Api-Version` on every response; additive changes only within a major; growable enums marked `x-extensible-enum`.
+
+## Do not
+
+- Edit `src/generated/**`.
+- Add a version comparison in a component.
+- Point one app build at two majors.
+
+If codegen fails, read `docs/troubleshooting.md` for the exact message before changing anything.