openapi-versions 0.0.0-stage → 0.0.0

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../codegen/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * Usage: openapi-versions [--config openapi-versions.config.json] [--check-only] [--require-gate]\n *   --check-only    run only the oasdiff breaking-change gate, write nothing\n *   --require-gate  fail if oasdiff is missing instead of skipping the gate (use in CI)\n */\nimport { build } from \"./build\";\nimport { loadConfig } from \"./config\";\n\nconst args = process.argv.slice(2);\nconst configPath = args.includes(\"--config\") ? args[args.indexOf(\"--config\") + 1] : \"openapi-versions.config.json\";\n\ntry {\n  await build(loadConfig(configPath), {\n    checkOnly: args.includes(\"--check-only\"),\n    gate: args.includes(\"--require-gate\") ? \"required\" : undefined,\n  });\n} catch (e) {\n  console.error(`\\n${(e as Error).message}`);\n  process.exit(1);\n}\n"],"mappings":";;;;;;;AASA,IAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,IAAM,aAAa,KAAK,SAAS,UAAU,IAAI,KAAK,KAAK,QAAQ,UAAU,IAAI,CAAC,IAAI;AAEpF,IAAI;AACF,QAAM,MAAM,WAAW,UAAU,GAAG;AAAA,IAClC,WAAW,KAAK,SAAS,cAAc;AAAA,IACvC,MAAM,KAAK,SAAS,gBAAgB,IAAI,aAAa;AAAA,EACvD,CAAC;AACH,SAAS,GAAG;AACV,UAAQ,MAAM;AAAA,EAAM,EAAY,OAAO,EAAE;AACzC,UAAQ,KAAK,CAAC;AAChB;","names":[]}

package/dist/codegen.d.ts

@@ -0,0 +1,104 @@
+import { OpenAPITSOptions } from 'openapi-typescript';
+
+/** Oldest oasdiff the gate is documented for (tested with 1.34.1). */
+declare const MIN_OASDIFF_VERSION = "1.34.0";
+type OasdiffProbe = {
+    ok: true;
+    bin: string;
+    version: string;
+} | {
+    ok: false;
+    bin: string;
+    reason: string;
+};
+/** Looks for a usable oasdiff: present, and at least MIN_OASDIFF_VERSION. */
+declare function probeOasdiff(): OasdiffProbe;
+interface BreakingResult {
+    from: string;
+    to: string;
+    ok: boolean;
+    report: string;
+}
+declare function checkPair(fromFile: string, toFile: string): Omit<BreakingResult, "from" | "to">;
+declare function checkChain(files: {
+    version: string;
+    file: string;
+}[]): BreakingResult[];
+
+/** auto: run the oasdiff gate when oasdiff is installed, warn and skip otherwise. required: fail if it cannot run. off: never run it. */
+type GateMode = "auto" | "required" | "off";
+interface Config {
+    specsDir: string;
+    outDir: string;
+    majors: Record<string, {
+        floor: string;
+    }>;
+    /** Module the generated client.ts imports the runtime from. Default: the package name. */
+    runtimeImport?: string;
+    /** Breaking-change gate. Default "auto". */
+    gate?: GateMode;
+}
+declare function validateConfig(raw: unknown, source?: string): Config;
+declare function loadConfig(path: string): Config;
+
+/** `gate` overrides config.gate (the CLI's --require-gate). */
+declare function build(config: Config, { checkOnly, log, gate }?: {
+    checkOnly?: boolean;
+    log?: (msg: string) => void;
+    gate?: GateMode;
+}): Promise<{
+    major: number;
+    specs: string[];
+    breaking: ReturnType<typeof checkChain>;
+}[]>;
+declare class BreakingChangeError extends Error {
+    report: Awaited<ReturnType<typeof build>>;
+    constructor(report: Awaited<ReturnType<typeof build>>);
+}
+
+/**
+ * Tolerant merge of several OpenAPI documents of the SAME major version.
+ *
+ * Result describes every input version at once:
+ *  - paths, operations, properties, parameters: UNION
+ *  - `required` arrays (schema objects):        INTERSECTION
+ *  - `required` booleans (params, bodies):      AND (true only if every version says true)
+ *  - enums:                                     UNION of values
+ *  - everything else (descriptions, formats…):  newest wins
+ *
+ * Inputs MUST be non-breaking relative to each other (checked by oasdiff first),
+ * otherwise the union can describe a shape no server ever had.
+ */
+type Json = any;
+declare function mergeTolerant(older: Json, newer: Json): Json;
+declare const mergeAll: (docs: Json[]) => any;
+
+/**
+ * openapi-typescript `transform` hook for EXTENSIBLE enums.
+ *
+ * The backend declares enums that may grow within a major with `x-extensible-enum`
+ * (plain `enum` stays closed: adding a value to it is a breaking change, and oasdiff
+ * flags it). Extensible enums become OPEN unions:
+ *   "active" | "invited" | (string & {})
+ * Autocomplete still lists the known values, a value added by a newer backend
+ * compiles, and `switch` statements need a `default` branch.
+ */
+
+declare const openEnums: NonNullable<OpenAPITSOptions["transform"]>;
+
+interface VersionedDoc {
+    version: string;
+    doc: any;
+}
+declare function computeSince(group: VersionedDoc[], floor: string): {
+    ops: string[];
+    gatedOps: {
+        [k: string]: string;
+    };
+    gatedFields: {
+        [k: string]: string;
+    };
+};
+
+export { BreakingChangeError, MIN_OASDIFF_VERSION, build, checkChain, checkPair, computeSince, loadConfig, mergeAll, mergeTolerant, openEnums, probeOasdiff, validateConfig };
+export type { BreakingResult, Config, GateMode, OasdiffProbe, VersionedDoc };

package/dist/codegen.js

@@ -0,0 +1,29 @@
+import {
+  BreakingChangeError,
+  MIN_OASDIFF_VERSION,
+  build,
+  checkChain,
+  checkPair,
+  computeSince,
+  loadConfig,
+  mergeAll,
+  mergeTolerant,
+  openEnums,
+  probeOasdiff,
+  validateConfig
+} from "./chunk-4O4PFYPM.js";
+export {
+  BreakingChangeError,
+  MIN_OASDIFF_VERSION,
+  build,
+  checkChain,
+  checkPair,
+  computeSince,
+  loadConfig,
+  mergeAll,
+  mergeTolerant,
+  openEnums,
+  probeOasdiff,
+  validateConfig
+};
+//# sourceMappingURL=codegen.js.map

package/dist/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/core.d.ts

@@ -0,0 +1,146 @@
+import { Client, Middleware } from 'openapi-fetch';
+import { HttpMethod } from 'openapi-typescript-helpers';
+import { skipToken } from '@tanstack/react-query';
+import { OpenapiQueryClient } from 'openapi-react-query';
+
+/**
+ * `paths` with the gated operations removed (turned into `method?: never`, exactly how
+ * openapi-typescript marks a method a path does not have). A client typed with this
+ * cannot call an operation newer than the floor: TypeScript rejects it, so every call
+ * to a newer operation has to go through the gated client, next to a capability check.
+ */
+type StripOps<P, Ops extends string> = {
+    [Path in keyof P]: {
+        [K in keyof P[Path] as K extends HttpMethod ? (`${K} ${Path & string}` extends Ops ? never : K) : K]: P[Path][K];
+    } & {
+        [K in HttpMethod as `${K} ${Path & string}` extends Ops ? K : never]?: never;
+    };
+};
+
+/**
+ * One openapi-fetch client, exposed twice:
+ *  - `core`:  typed with gated operations removed (safe on every supported backend)
+ *  - `gated`: full merged types, for operations that need a capability check
+ * Both are the SAME runtime object; only the types differ.
+ *
+ * A middleware reads `X-Api-Version` on every response so the app notices a backend
+ * deploy during a session (web tab left open, mobile app resumed), and `Sunset`
+ * so it can warn before the backend stops serving this major.
+ */
+
+/** `P` = generated `paths`, `G` = union of gated operation keys */
+type CorePaths<P extends {}, G extends string> = StripOps<P, G>;
+interface ApiClient<P extends {}, G extends string> {
+    core: Client<CorePaths<P, G>>;
+    gated: Client<P>;
+}
+interface ApiHeaderHandlers {
+    onVersionHeader?: (version: string) => void;
+    onSunsetHeader?: (sunset: Date) => void;
+}
+/** Reads X-Api-Version (deploys mid-session) and Sunset (major being retired) on every response. */
+declare function apiHeadersMiddleware({ onVersionHeader, onSunsetHeader }: ApiHeaderHandlers): Middleware;
+/**
+ * `baseUrl` includes the major: https://host/api/v1. The backend serves each major
+ * under its own prefix, with its own /version, so one app build talks to one major.
+ */
+declare function createApiClient<P extends {}, G extends string>(opts: {
+    baseUrl: string;
+    fetch?: typeof globalThis.fetch;
+} & ApiHeaderHandlers): ApiClient<P, G>;
+/** GET {baseUrl}/version, e.g. https://host/api/v1/version. Resolved RELATIVE to the base path. */
+declare function fetchBackendVersion(baseUrl: string, fetchImpl?: typeof fetch): Promise<string>;
+
+interface MajorMeta {
+    readonly major: number;
+    readonly floor: string;
+    readonly newest: string;
+    readonly ops: readonly string[];
+    readonly gatedOps: Readonly<Record<string, string>>;
+    readonly gatedFields: Readonly<Record<string, string>>;
+}
+type Compat = {
+    status: "ok";
+    version: string;
+    major: number;
+    /** backend is newer than the newest spec this client was built with (forward compatibility) */
+    backendAhead: boolean;
+    supports(op: string): boolean;
+    hasField(field: string): boolean;
+} | {
+    status: "backend-too-old";
+    version: string;
+    major: number;
+    floor: string;
+} | {
+    status: "app-too-old";
+    version: string;
+    major: number;
+    supportedMajors: number[];
+} | {
+    status: "invalid-version";
+    version: string;
+};
+interface CompatOptions {
+    /**
+     * Treat `1.6.0-rc.1` as `1.6.0` (staging running a release candidate gets the new features).
+     * Default false: an rc of 1.6.0 counts as 1.5.x, which is the safe reading of semver.
+     */
+    prereleaseAsRelease?: boolean;
+}
+declare function resolveCompat(rawVersion: string, majors: Readonly<Record<number, MajorMeta>>, { prereleaseAsRelease }?: CompatOptions): Compat;
+
+/**
+ * The object components and loaders use: resolved compatibility + typed
+ * openapi-react-query clients + gating.
+ *
+ *   $api    operations every supported backend has (floor and older)
+ *   $gated  operations added after the floor: queries go through gate(),
+ *           mutations are rendered inside <Feature>
+ *
+ * Generic over the generated types: `P` = `paths`, `G` = union of gated operation keys.
+ * Apps get it pre-bound from the generated `v<major>/client.ts`.
+ */
+
+type OkCompat = Extract<Compat, {
+    status: "ok";
+}>;
+type QueryOptionsLike = {
+    queryKey: readonly unknown[];
+    queryFn?: unknown;
+};
+type Gated<O extends QueryOptionsLike> = Omit<O, "queryFn"> & {
+    queryFn: O["queryFn"] | typeof skipToken;
+};
+interface Api<P extends {}, G extends string> {
+    compat: OkCompat;
+    client: ApiClient<P, G>;
+    $api: OpenapiQueryClient<StripOps<P, G>>;
+    $gated: Pick<OpenapiQueryClient<P>, "queryOptions" | "useMutation">;
+    /**
+     * Replace queryFn with skipToken when the connected backend lacks the operation.
+     * The operation is read from the key openapi-react-query builds ([method, path, init]),
+     * and the result type includes skipToken, so useSuspenseQuery rejects it.
+     */
+    gate<O extends QueryOptionsLike>(options: O): Gated<O>;
+}
+declare function buildApi<P extends {}, G extends string>(compat: OkCompat, client: ApiClient<P, G>): Api<P, G>;
+type CreateApiOptions = {
+    baseUrl: string;
+    fetch?: typeof fetch;
+} & CompatOptions;
+/** Reads `<baseUrl>/version`, resolves compatibility, throws if the backend is not supported. */
+declare function createApi<P extends {}, G extends string>(meta: MajorMeta, opts: CreateApiOptions): Promise<Api<P, G>>;
+
+/**
+ * Bind the runtime to one generated contract. Normally called by the generated
+ * `v<major>/client.ts`; `P` = paths, `G` = gated operation keys.
+ */
+declare function createVersionAwareCore<P extends {}, G extends string>(meta: MajorMeta): {
+    meta: MajorMeta;
+    createApi: (opts: CreateApiOptions) => Promise<Api<P, G>>;
+    buildApi: (compat: OkCompat, client: ApiClient<P, G>) => Api<P, G>;
+};
+
+export { apiHeadersMiddleware, buildApi, createApi, createApiClient, createVersionAwareCore, fetchBackendVersion, resolveCompat };
+export type { Api, ApiClient, Compat, CompatOptions, CorePaths, CreateApiOptions, Gated, MajorMeta, OkCompat, StripOps };

package/dist/core.js

@@ -0,0 +1,19 @@
+import {
+  apiHeadersMiddleware,
+  buildApi,
+  createApi,
+  createApiClient,
+  createVersionAwareCore,
+  fetchBackendVersion,
+  resolveCompat
+} from "./chunk-QZ47EPTW.js";
+export {
+  apiHeadersMiddleware,
+  buildApi,
+  createApi,
+  createApiClient,
+  createVersionAwareCore,
+  fetchBackendVersion,
+  resolveCompat
+};
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { CompatOptions, Compat, OkCompat, MajorMeta, Api, CreateApiOptions, ApiClient } from './core.js';
+export { CorePaths, Gated, StripOps, apiHeadersMiddleware, buildApi, createApi, createApiClient, createVersionAwareCore, fetchBackendVersion, resolveCompat } from './core.js';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import 'openapi-fetch';
+import 'openapi-typescript-helpers';
+import '@tanstack/react-query';
+import 'openapi-react-query';
+
+declare const API_VERSION_KEY: readonly ["api-version"];
+interface ApiVersionProviderProps extends CompatOptions {
+    baseUrl: string;
+    children: ReactNode;
+    fetch?: typeof globalThis.fetch;
+    /** shown while /version loads */
+    loading?: ReactNode;
+    /** shown when the backend is outside the supported range */
+    renderBlocked?: (compat: Exclude<Compat, OkCompat>) => ReactNode;
+}
+
+/** `P` = generated paths, `G` = gated operation keys, `F` = gated field keys */
+declare function createVersionAware<P extends {}, G extends string, F extends string>(meta: MajorMeta): {
+    ApiVersionProvider: ({ baseUrl, children, fetch: fetchImpl, loading, renderBlocked, ...compatOpts }: ApiVersionProviderProps) => react.JSX.Element;
+    useApi: () => Api<P, G>;
+    useSunset: () => Date | undefined;
+    useSupports: (op: G) => boolean;
+    useHasField: (field: F) => boolean;
+    Feature: ({ requires, children, fallback }: {
+        requires: G;
+        children: react.ReactNode;
+        fallback?: react.ReactNode;
+    }) => react.JSX.Element;
+    meta: MajorMeta;
+    createApi: (opts: CreateApiOptions) => Promise<Api<P, G>>;
+    buildApi: (compat: OkCompat, client: ApiClient<P, G>) => Api<P, G>;
+};
+
+export { API_VERSION_KEY, Api, ApiClient, Compat, CompatOptions, CreateApiOptions, MajorMeta, OkCompat, createVersionAware };
+export type { ApiVersionProviderProps };

package/dist/index.js

@@ -0,0 +1,120 @@
+import {
+  apiHeadersMiddleware,
+  buildApi,
+  createApi,
+  createApiClient,
+  createVersionAwareCore,
+  fetchBackendVersion,
+  resolveCompat
+} from "./chunk-QZ47EPTW.js";
+
+// src/react/ApiVersionProvider.tsx
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { createContext, useContext, useMemo, useRef, useState } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var API_VERSION_KEY = ["api-version"];
+function defaultBlocked(c) {
+  switch (c.status) {
+    case "app-too-old":
+      return /* @__PURE__ */ jsxs("p", { children: [
+        "This app does not support API ",
+        c.version,
+        ". Please update the app."
+      ] });
+    case "backend-too-old":
+      return /* @__PURE__ */ jsxs("p", { children: [
+        "This app needs API ",
+        c.floor,
+        " or newer (connected: ",
+        c.version,
+        ")."
+      ] });
+    case "invalid-version":
+      return /* @__PURE__ */ jsxs("p", { children: [
+        'Unrecognised API version "',
+        c.version,
+        '".'
+      ] });
+  }
+}
+function createReactBindings(meta) {
+  const majors = { [meta.major]: meta };
+  const ApiContext = createContext(null);
+  const SunsetContext = createContext(void 0);
+  function ApiVersionProvider({
+    baseUrl,
+    children,
+    fetch: fetchImpl,
+    loading = null,
+    renderBlocked = defaultBlocked,
+    ...compatOpts
+  }) {
+    const queryClient = useQueryClient();
+    const current = useRef(void 0);
+    const [sunset, setSunset] = useState(void 0);
+    const client = useMemo(
+      () => createApiClient({
+        baseUrl,
+        fetch: fetchImpl,
+        // Backend deployed mid-session: store the new version, refetch everything else.
+        onVersionHeader: (v) => {
+          if (current.current === void 0 || v === current.current) return;
+          current.current = v;
+          queryClient.setQueryData(API_VERSION_KEY, v);
+          queryClient.invalidateQueries({ predicate: (q) => q.queryKey[0] !== API_VERSION_KEY[0] });
+        },
+        // same timestamp -> same state, no re-render
+        onSunsetHeader: (d) => setSunset((prev) => prev?.getTime() === d.getTime() ? prev : d)
+      }),
+      [baseUrl, fetchImpl, queryClient]
+    );
+    const version = useQuery({
+      queryKey: API_VERSION_KEY,
+      queryFn: () => fetchBackendVersion(baseUrl, fetchImpl),
+      staleTime: 5 * 6e4,
+      refetchOnWindowFocus: true
+      // mobile resume / tab refocus re-checks the backend
+    });
+    current.current = version.data;
+    const compat = useMemo(
+      () => version.data ? resolveCompat(version.data, majors, compatOpts) : void 0,
+      [version.data, compatOpts.prereleaseAsRelease]
+    );
+    const api = useMemo(
+      () => compat?.status === "ok" ? buildApi(compat, client) : void 0,
+      [compat, client]
+    );
+    if (!compat) return /* @__PURE__ */ jsx(Fragment, { children: loading });
+    if (compat.status !== "ok") return /* @__PURE__ */ jsx(Fragment, { children: renderBlocked(compat) });
+    return /* @__PURE__ */ jsx(ApiContext.Provider, { value: api, children: /* @__PURE__ */ jsx(SunsetContext.Provider, { value: sunset, children }) });
+  }
+  function useApi() {
+    const ctx = useContext(ApiContext);
+    if (!ctx) throw new Error("useApi must be used inside <ApiVersionProvider>");
+    return ctx;
+  }
+  const useSunset = () => useContext(SunsetContext);
+  const useSupports = (op) => useApi().compat.supports(op);
+  const useHasField = (field) => useApi().compat.hasField(field);
+  function Feature({ requires, children, fallback = null }) {
+    return /* @__PURE__ */ jsx(Fragment, { children: useSupports(requires) ? children : fallback });
+  }
+  return { ApiVersionProvider, useApi, useSunset, useSupports, useHasField, Feature };
+}
+
+// src/index.ts
+function createVersionAware(meta) {
+  return { ...createVersionAwareCore(meta), ...createReactBindings(meta) };
+}
+export {
+  API_VERSION_KEY,
+  apiHeadersMiddleware,
+  buildApi,
+  createApi,
+  createApiClient,
+  createVersionAware,
+  createVersionAwareCore,
+  fetchBackendVersion,
+  resolveCompat
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/ApiVersionProvider.tsx","../src/index.ts"],"sourcesContent":["/**\n * React layer: version detection with React Query, capability gating, and\n * re-evaluation when the backend version changes during a session.\n *\n * `createReactBindings(meta)` returns the provider and hooks bound to one generated\n * contract (`P` = paths, `G` = gated operation keys, `F` = gated field keys).\n */\n\nimport { useQuery, useQueryClient } from \"@tanstack/react-query\";\nimport { createContext, type ReactNode, useContext, useMemo, useRef, useState } from \"react\";\nimport { type Api, buildApi, type OkCompat } from \"../core/api\";\nimport { createApiClient, fetchBackendVersion } from \"../core/client\";\nimport { type Compat, type CompatOptions, type MajorMeta, resolveCompat } from \"../core/compat\";\n\nexport const API_VERSION_KEY = [\"api-version\"] as const;\n\nexport interface ApiVersionProviderProps extends CompatOptions {\n  baseUrl: string;\n  children: ReactNode;\n  fetch?: typeof globalThis.fetch;\n  /** shown while /version loads */\n  loading?: ReactNode;\n  /** shown when the backend is outside the supported range */\n  renderBlocked?: (compat: Exclude<Compat, OkCompat>) => ReactNode;\n}\n\nfunction defaultBlocked(c: Exclude<Compat, OkCompat>): ReactNode {\n  switch (c.status) {\n    case \"app-too-old\":\n      return <p>This app does not support API {c.version}. Please update the app.</p>;\n    case \"backend-too-old\":\n      return (\n        <p>\n          This app needs API {c.floor} or newer (connected: {c.version}).\n        </p>\n      );\n    case \"invalid-version\":\n      return <p>Unrecognised API version \"{c.version}\".</p>;\n  }\n}\n\nexport function createReactBindings<P extends {}, G extends string, F extends string>(meta: MajorMeta) {\n  const majors = { [meta.major]: meta };\n  const ApiContext = createContext<Api<P, G> | null>(null);\n  /** Date after which the backend stops serving this app's major (from the Sunset header) */\n  const SunsetContext = createContext<Date | undefined>(undefined);\n\n  function ApiVersionProvider({\n    baseUrl,\n    children,\n    fetch: fetchImpl,\n    loading = null,\n    renderBlocked = defaultBlocked,\n    ...compatOpts\n  }: ApiVersionProviderProps) {\n    const queryClient = useQueryClient();\n    const current = useRef<string | undefined>(undefined);\n    const [sunset, setSunset] = useState<Date | undefined>(undefined);\n\n    const client = useMemo(\n      () =>\n        createApiClient<P, G>({\n          baseUrl,\n          fetch: fetchImpl,\n          // Backend deployed mid-session: store the new version, refetch everything else.\n          onVersionHeader: (v) => {\n            if (current.current === undefined || v === current.current) return;\n            // update synchronously: the refetches below answer before React re-renders,\n            // and would otherwise each trigger another invalidation (refetch loop)\n            current.current = v;\n            queryClient.setQueryData(API_VERSION_KEY, v);\n            queryClient.invalidateQueries({ predicate: (q) => q.queryKey[0] !== API_VERSION_KEY[0] });\n          },\n          // same timestamp -> same state, no re-render\n          onSunsetHeader: (d) => setSunset((prev) => (prev?.getTime() === d.getTime() ? prev : d)),\n        }),\n      [baseUrl, fetchImpl, queryClient],\n    );\n\n    const version = useQuery({\n      queryKey: API_VERSION_KEY,\n      queryFn: () => fetchBackendVersion(baseUrl, fetchImpl),\n      staleTime: 5 * 60_000,\n      refetchOnWindowFocus: true, // mobile resume / tab refocus re-checks the backend\n    });\n    current.current = version.data;\n\n    // biome-ignore lint/correctness/useExhaustiveDependencies: compatOpts is an inline object; only prereleaseAsRelease is read\n    const compat = useMemo(\n      () => (version.data ? resolveCompat(version.data, majors, compatOpts) : undefined),\n      [version.data, compatOpts.prereleaseAsRelease],\n    );\n    // a new object only when the version changes\n    const api = useMemo<Api<P, G> | undefined>(\n      () => (compat?.status === \"ok\" ? buildApi<P, G>(compat, client) : undefined),\n      [compat, client],\n    );\n\n    if (!compat) return <>{loading}</>;\n    if (compat.status !== \"ok\") return <>{renderBlocked(compat)}</>;\n    return (\n      <ApiContext.Provider value={api!}>\n        <SunsetContext.Provider value={sunset}>{children}</SunsetContext.Provider>\n      </ApiContext.Provider>\n    );\n  }\n\n  /** const { $api, $gated, gate } = useApi() */\n  function useApi(): Api<P, G> {\n    const ctx = useContext(ApiContext);\n    if (!ctx) throw new Error(\"useApi must be used inside <ApiVersionProvider>\");\n    return ctx;\n  }\n\n  /**\n   * Set once a response carries `Sunset`: the backend will stop serving this major.\n   * Show a soft \"update the app before <date>\" banner; the hard block comes when the\n   * major is gone (another major answers /version, or the prefix is removed).\n   */\n  const useSunset = () => useContext(SunsetContext);\n\n  /** Feature-flag style check: is this operation available on the connected backend? */\n  const useSupports = (op: G) => useApi().compat.supports(op);\n  const useHasField = (field: F) => useApi().compat.hasField(field);\n\n  function Feature({ requires, children, fallback = null }: { requires: G; children: ReactNode; fallback?: ReactNode }) {\n    return <>{useSupports(requires) ? children : fallback}</>;\n  }\n\n  return { ApiVersionProvider, useApi, useSunset, useSupports, useHasField, Feature };\n}\n","/**\n * Runtime of the version-aware client: core + React bindings.\n * Apps do not call this directly; the generated `v<major>/client.ts` does, with its own types.\n */\n\nimport { createVersionAwareCore } from \"./core\";\nimport type { MajorMeta } from \"./core/compat\";\nimport { createReactBindings } from \"./react/ApiVersionProvider\";\n\nexport * from \"./core\";\nexport { API_VERSION_KEY, type ApiVersionProviderProps } from \"./react/ApiVersionProvider\";\n\n/** `P` = generated paths, `G` = gated operation keys, `F` = gated field keys */\nexport function createVersionAware<P extends {}, G extends string, F extends string>(meta: MajorMeta) {\n  return { ...createVersionAwareCore<P, G>(meta), ...createReactBindings<P, G, F>(meta) };\n}\n"],"mappings":"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","names":[]}

package/docs/README.md

@@ -0,0 +1,22 @@
+# Version-aware API client: docs
+
+A codegen extension for the [openapi-ts](https://openapi-ts.dev/) ecosystem ([openapi-typescript](https://openapi-ts.dev/), [openapi-fetch](https://openapi-ts.dev/openapi-fetch/), [openapi-react-query](https://openapi-ts.dev/openapi-react-query/)) that lets **one client build work against a range of minor versions of one API major**. It merges every supported minor spec into one tolerant contract, records which version introduced each operation and field, and exposes a small runtime that hides features the connected backend does not have yet.
+
+| Read this                                | When                                                                                         |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------- |
+| [concepts.md](concepts.md)               | You need the mental model: majors, minors, floor, gating, tolerant reading                   |
+| [getting-started.md](getting-started.md) | First setup in an app                                                                        |
+| [how-to.md](how-to.md)                   | A task: add a spec, gate a feature, raise a floor, add an enum, move to a new major, wire CI |
+| [reference.md](reference.md)             | Exact config, CLI, programmatic API, merge rules, generated files, runtime API               |
+| [ecosystem.md](ecosystem.md)             | How this fits next to openapi-ts, what to upstream                                           |
+| [troubleshooting.md](troubleshooting.md) | An error message or surprising behaviour                                                     |
+| [adr/](adr/README.md)                    | Why a design decision was made                                                               |
+
+LLM agents: the same tasks are packaged as skills in [`../skills`](../skills) (`openapi-versions-setup`, `openapi-versions-add-spec`, `openapi-versions-gate-feature`) and summarised in [`../AGENTS.md`](../AGENTS.md).
+
+## The idea in four lines
+
+1. The backend only makes **additive** changes inside a major (checked by [oasdiff](https://github.com/oasdiff/oasdiff)). Breaking changes mean a new major under a new URL prefix.
+2. Codegen merges the specs from the app's **floor** (oldest supported minor) up to the newest spec, even an unreleased one.
+3. At runtime the app reads `GET <base>/version` and decides what is available. Operations newer than the backend are off, like feature flags.
+4. Anything newer than the app (new fields, new enum values) is ignored or typed open, so old apps keep working on new backends.

package/docs/adr/0001-separate-package-not-upstream.md

@@ -0,0 +1,16 @@
+# 0001. Ship as a separate package, upstream only small fixes
+
+- Status: accepted
+- Date: 2026-10-25
+
+## Context
+
+The package builds on openapi-typescript, openapi-fetch and openapi-react-query. Upstreaming it would put multi-spec merge, an oasdiff gate, runtime gating, a React layer and a CLI into a monorepo whose maintainers have no stated process for features of that size.
+
+## Decision
+
+Keep `openapi-versions` as its own package. Upstream only narrow fixes (the `Readable`/`Writable` primitive guard, openapi-ts/openapi-typescript#2766) and rely on upstream features where they exist (loose enums, #2415).
+
+## Consequences
+
+Own release cadence and no sign-off needed, but we track upstream 0.x breaking changes ourselves (Renovate groups the openapi-ts packages) and discoverability is lower. Revisit if upstream adopts a plugin or transform hook that covers codegen.

package/docs/adr/0002-extensible-enums-via-x-extensible-enum.md

@@ -0,0 +1,16 @@
+# 0002. Open enums are declared with `x-extensible-enum`
+
+- Status: accepted
+- Date: 2026-10-25
+
+## Context
+
+Within a major a backend may add enum values, so an older client must tolerate unknown ones, while closed enums must stay closed so removing a value is still breaking.
+
+## Decision
+
+An enum is open only when the spec marks it `x-extensible-enum`. Codegen emits it as `"a" | "b" | (string & {})`. Consumers must give a `switch` over such an enum a `default` branch. Hand-editing a spec to pass the breaking gate is not allowed (see 0004).
+
+## Consequences
+
+The open/closed intent lives in the backend spec. openapi-fetch's `Readable<T>` collapses `string & {}` to an object type without the fix in 0005. openapi-typescript 7.14 will emit loose unions for `additionalProperties: true` string enums (#2415); evaluate whether it can replace our `transform` hook.

package/docs/adr/0003-gating-model.md

@@ -0,0 +1,16 @@
+# 0003. Newer operations go through `$gated` + `gate()` or `<Feature>`
+
+- Status: accepted
+- Date: 2026-10-25
+
+## Context
+
+One build runs against backends from the floor up to the newest spec. Calling an operation the backend lacks fails at runtime.
+
+## Decision
+
+Operations introduced after the floor are absent from the plain `$api` type. Queries use `$gated` with `gate()`, mutations use `<Feature>`. Components never compare version numbers; they ask `useSupports` / `useHasField`. The floor needs its own spec file.
+
+## Consequences
+
+Missing-feature handling is a compile-time concern. Raising the floor turns gated operations into ordinary ones, and dead gates become type errors to clean up.

package/docs/adr/0004-oasdiff-breaking-gate.md

@@ -0,0 +1,16 @@
+# 0004. oasdiff gates every consecutive spec pair
+
+- Status: accepted
+- Date: 2026-10-25
+
+## Context
+
+The whole model assumes minors within a major are additive. A silent breaking change would make the merged contract wrong.
+
+## Decision
+
+Codegen runs `oasdiff breaking --fail-on ERR` on each consecutive pair of specs within a major and fails on a breaking pair. The fix is in the backend, an `x-extensible-enum`, or a new major, never an edit to a spec. oasdiff is pinned in `mise.toml` and CI; `MIN_OASDIFF_VERSION` guards other environments.
+
+## Consequences
+
+An external binary is a hard dependency of codegen. Renovate does not automerge oasdiff bumps.

package/docs/adr/0005-patch-openapi-typescript-helpers.md

@@ -0,0 +1,16 @@
+# 0005. Patch `openapi-typescript-helpers` until upstream ships the fix
+
+- Status: accepted
+- Date: 2026-10-25
+
+## Context
+
+`Readable<T>` and `Writable<T>` map over `string & {}`, collapsing open enums. The fix is open upstream as openapi-ts/openapi-typescript#2766, unreleased.
+
+## Decision
+
+Carry the one-line fix as a pnpm patch (`patchedDependencies`, `patches/openapi-typescript-helpers@0.1.0.patch`), which replaced patch-package. Do not post a duplicate upstream PR.
+
+## Consequences
+
+A patch is not applied inside a consumer's `node_modules`, so consumers must patch themselves (documented in troubleshooting). Delete the patch, `patches/` and rule 7 of AGENTS.md once a helpers release contains #2766. Tracked by an issue labelled `blocked-upstream`.

package/docs/adr/0006-tooling-mise-pnpm-biome.md

@@ -0,0 +1,16 @@
+# 0006. mise, pnpm, Biome, Vitest, Changesets, Renovate; no turbo yet
+
+- Status: accepted
+- Date: 2026-10-25
+
+## Context
+
+The repo had no pinned toolchain, lint, CI or release flow. Upstream uses pnpm and turbo.
+
+## Decision
+
+mise pins node, pnpm and oasdiff. pnpm is the package manager (`packageManager` pinned). Biome does lint and format. Vitest runs tests. Changesets drive versions and changelogs, released from GitHub Actions. Renovate updates dependencies with a minimum release age. Turbo is deferred: it is a single package with a short task chain.
+
+## Consequences
+
+Revisit turbo if the repo splits into a workspace (core, codegen, playground).

package/docs/adr/0007-mit-license.md

@@ -0,0 +1,16 @@
+# 0007. MIT license
+
+- Status: accepted
+- Date: 2026-10-25
+
+## Context
+
+`package.json` said `UNLICENSED` while the repo is public, and a license is required before the first npm release. The package builds on openapi-typescript, openapi-fetch and openapi-react-query, which are MIT, and [ADR 0001](0001-separate-package-not-upstream.md) keeps the door open to upstreaming small fixes.
+
+## Decision
+
+License the package under MIT. `LICENSE` holds the text, `package.json` sets `"license": "MIT"`.
+
+## Consequences
+
+Matches the openapi-ts ecosystem and lets fixes move upstream without relicensing. Offers no explicit patent grant; revisit (Apache-2.0) only if that becomes a requirement.

package/docs/adr/README.md

@@ -0,0 +1,13 @@
+# Architecture decision records
+
+One file per decision, `NNNN-title.md`, [MADR](https://adr.github.io/madr/) style. Accepted ADRs are immutable: to change a decision, add a new ADR that supersedes it and set the old one's status to `superseded by NNNN`. Copy `template.md`.
+
+| ADR | Decision | Status |
+| --- | --- | --- |
+| [0001](0001-separate-package-not-upstream.md) | Ship as a separate package, upstream only small fixes | accepted |
+| [0002](0002-extensible-enums-via-x-extensible-enum.md) | Open enums are declared with `x-extensible-enum` | accepted |
+| [0003](0003-gating-model.md) | Newer operations go through `$gated` + `gate()` or `<Feature>` | accepted |
+| [0004](0004-oasdiff-breaking-gate.md) | oasdiff gates every consecutive spec pair | accepted |
+| [0005](0005-patch-openapi-typescript-helpers.md) | Patch `openapi-typescript-helpers` until upstream ships the fix | accepted |
+| [0006](0006-tooling-mise-pnpm-biome.md) | mise, pnpm, Biome, Vitest, Changesets, Renovate; no turbo yet | accepted |
+| [0007](0007-mit-license.md) | MIT license | accepted |