tempest-react-sdk 0.79.0 → 0.80.0

package/bin/lib/openapi/generate.hostile.test.mjs

@@ -84,6 +84,8 @@ function spec(paths, schemas = {}) {
 }
 
 const OK = { 200: { description: "ok" } };
+const schemaRef = (name) => ({ $ref: `#/components/schemas/${name}` });
+const json = (schema) => ({ content: { "application/json": { schema } } });
 
 describe("generate — hostile spec text never becomes code (#434)", () => {
     it("a tag that closes the class doc comment stays inside it", async () => {
@@ -233,12 +235,45 @@ describe("generate — hostile spec text never becomes code (#434)", () => {
         await runGroup(files, "t");
     });
 
+    /**
+     * Rewritten for #516: this used to pass with `spec({}, …)`, two schemas no
+     * route reaches. The check now runs over the schemas a group emits, so the
+     * pair has to be referenced to collide — and still is refused, naming both.
+     */
     it("two schema names that map to the same identifier are refused, naming both", () => {
+        const both = {
+            200: json({ anyOf: [schemaRef("User-Out"), schemaRef("user.Out")] }),
+        };
         expect(() =>
-            generate(spec({}, { "User-Out": { type: "object" }, "user.Out": { type: "object" } })),
+            generate(
+                spec(
+                    { "/a": { get: { tags: ["t"], responses: both } } },
+                    { "User-Out": { type: "object" }, "user.Out": { type: "object" } },
+                ),
+            ),
         ).toThrow(/"User-Out" and "user\.Out" both map to the TypeScript identifier "UserOut"/);
     });
 
+    it("schema names no route reaches are neither emitted nor checked, so an orphan cannot abort the run (#516)", () => {
+        const { files } = generate(
+            spec(
+                {
+                    "/a": {
+                        get: { tags: ["t"], responses: { 200: json(schemaRef("MediaType")) } },
+                    },
+                },
+                {
+                    MediaType: { type: "string", enum: ["image/png"] },
+                    "Media-Type": { type: "string", enum: ["image/png", "image/webp"] },
+                    "***": { type: "object" },
+                },
+            ),
+        );
+        expect(files["t/types.ts"]).toContain("export type MediaType = ");
+        expect(files["t/schemas.ts"]).not.toContain("image/webp");
+        expect(files["t/types.ts"].match(/export type/g)).toHaveLength(1);
+    });
+
     it("a path parameter that maps onto another method argument is refused", () => {
         expect(() =>
             generate(
@@ -258,10 +293,16 @@ describe("generate — hostile spec text never becomes code (#434)", () => {
         ).toThrow(/"user-id" and "userId" both map to the TypeScript identifier "userId"/);
     });
 
+    /** Rewritten for #516 like the collision above: the schema is now referenced. */
     it("a name with nothing to build an identifier from is refused", () => {
-        expect(() => generate(spec({}, { "***": { type: "object" } }))).toThrow(
-            /schema name "\*\*\*" has no letter or digit/,
-        );
+        expect(() =>
+            generate(
+                spec(
+                    { "/a": { get: { tags: ["t"], responses: { 200: json(schemaRef("***")) } } } },
+                    { "***": { type: "object" } },
+                ),
+            ),
+        ).toThrow(/schema name "\*\*\*" has no letter or digit/);
     });
 
     it("a regex pattern with an escaped slash or a line break compiles to the same regex", () => {

package/bin/lib/openapi/generate.mjs

@@ -50,12 +50,88 @@ function methodName(op, method, path) {
 const CLASS_MEMBERS = ["constructor", "api"];
 
 /**
- * Names a generated method body uses besides its path parameters: the `body` and
- * `params` arguments, the `S` schemas import and the `encodeIdSegment` import. A
- * path parameter that maps to one of them becomes `<name>Param` (`{body}` →
- * `bodyParam`), so it neither duplicates an argument nor shadows the import.
+ * Names a generated method body uses besides its path parameters: the `body`,
+ * `params` and `headers` arguments, the `S` schemas import, the `encodeIdSegment`
+ * import and the module-level `headerRecord` helper. A path parameter that maps to
+ * one of them becomes `<name>Param` (`{body}` → `bodyParam`), so it neither
+ * duplicates an argument nor shadows the import.
  */
-const METHOD_LOCALS = new Set(["body", "params", "S", "encodeIdSegment"]);
+const METHOD_LOCALS = new Set([
+    "body",
+    "params",
+    "headers",
+    "S",
+    "encodeIdSegment",
+    "headerRecord",
+]);
+
+/**
+ * Header parameter names OpenAPI 3 says a generator SHALL ignore: the client sets
+ * `Accept` and `Content-Type` from the request it builds and `Authorization` from
+ * its `getToken`, so a spec that also declares them must not open a second way to
+ * send them. Compared case-insensitively, as HTTP header names are.
+ */
+const IGNORED_HEADERS = new Set(["accept", "content-type", "authorization"]);
+
+/**
+ * Module-level helper a `service.ts` declares when one of its methods sends header
+ * parameters. `fetch` turns a header value of `undefined` into the literal text
+ * `"undefined"`, and `RequestOptions.headers` only takes strings, so an optional
+ * header left out is dropped and every other value goes through `String()`.
+ */
+const HEADER_RECORD_HELPER = [
+    "/** Header parameters as strings, without the ones left out (`fetch` would send `undefined` as text). */",
+    "function headerRecord(",
+    "    values: Record<string, string | number | boolean | null | undefined>,",
+    "): Record<string, string> {",
+    "    const out: Record<string, string> = {};",
+    "    for (const [name, value] of Object.entries(values)) {",
+    "        if (value !== undefined && value !== null) out[name] = String(value);",
+    "    }",
+    "    return out;",
+    "}",
+].join("\n");
+
+/**
+ * Follow a `#/components/parameters/...` `$ref` chain to the parameter object.
+ *
+ * @param {object | undefined} param - A parameter object or a reference to one.
+ * @param {Record<string, object>} components - `components.parameters`.
+ * @returns {object | undefined} The parameter object, or `undefined` when the
+ *   chain does not resolve.
+ */
+function resolveParameter(param, components) {
+    let node = param;
+    let guard = 0;
+    while (node && node.$ref && guard++ < 16) node = components[refName(node.$ref)];
+    return node && !node.$ref ? node : undefined;
+}
+
+/**
+ * The parameters that apply to one operation: the path item's `parameters`
+ * merged with the operation's, the operation winning on the same `(name, in)` —
+ * the rule OpenAPI 3 sets for the two levels.
+ *
+ * Before #509 only `operation.parameters` was read, so a `{id}` declared on the
+ * path item reached the URL literally (`"/items/{id}"`, measured), and a path item
+ * declaring one placeholder while the operation declared the other refused to
+ * generate. `$ref`s into `components.parameters` are resolved here too: they were
+ * dropped the same way, because a reference object has no `in`.
+ *
+ * @param {object} item - The path item.
+ * @param {object} op - The operation.
+ * @param {Record<string, object>} components - `components.parameters`.
+ * @returns {object[]} The effective parameter objects, path-item order first.
+ */
+function operationParameters(item, op, components) {
+    const merged = new Map();
+    for (const raw of [...(item.parameters ?? []), ...(op.parameters ?? [])]) {
+        const param = resolveParameter(raw, components);
+        if (!param || typeof param.name !== "string" || typeof param.in !== "string") continue;
+        merged.set(`${param.in}\u0000${param.name}`, param);
+    }
+    return [...merged.values()];
+}
 
 /**
  * Whether a path parameter's schema only ever produces a `string` or a `number` —
@@ -208,16 +284,17 @@ function isQueryScalar(schema, schemas, depth = 0) {
 }
 
 /**
- * TS type for a query-param value. Query params serialize to strings, so the
- * client only accepts `string | number | boolean | null`. Anything richer
- * (objects, arrays) is narrowed to `string` to stay assignable.
+ * TS type for a query- or header-param value. Both serialize to strings, so the
+ * client's `params` and the generated `headerRecord` only accept
+ * `string | number | boolean | null`. Anything richer (objects, arrays) is
+ * narrowed to `string` to stay assignable.
  *
  * @param {object | undefined} schema - The parameter's schema.
  * @param {Record<string, object>} schemas - `components.schemas`.
  * @param {Set<string>} refs - Collects the schemas the type names.
  * @returns {string} The TypeScript type expression.
  */
-function queryParamType(schema, schemas, refs) {
+function scalarParamType(schema, schemas, refs) {
     const node = schema ?? { type: "string" };
     return isQueryScalar(node, schemas) ? tsType(node, refs) : "string";
 }
@@ -343,16 +420,25 @@ function compareNames(a, b) {
  * template's ESLint enforces, so the output passes its lint and `tsc` with
  * `noUnusedLocals` as generated (#504, #505).
  *
+ * A component schema no route reaches is never emitted — FastAPI publishes an
+ * unreferenced enum for every `Enum`-annotated field (`ImageMediaType`, #516),
+ * and it lands in no group. Its name is not checked either: the identifier
+ * collision check runs per group over the schemas that group emits, so an orphan
+ * named `Media-Type` next to a referenced `MediaType` no longer aborts the whole
+ * run for a type nobody would see.
+ *
+ * Parameters are read from the path item and the operation, merged by
+ * `(name, in)` (see {@link operationParameters}); `in: "cookie"` is skipped,
+ * because a browser `fetch` cannot set `Cookie` — the browser sends its own
+ * cookies with `credentials`, which is how a cookie parameter reaches the server.
+ *
  * @param {object} doc - The parsed OpenAPI 3.x spec.
  * @returns {{ files: Record<string, string>, tags: string[] }}
  */
 export function generate(doc) {
     const schemas = doc.components?.schemas ?? {};
-    assertNoCollision(
-        Object.keys(schemas).map((n) => [n, typeName(n)]),
-        "schema names",
-    );
-    const groups = new Map(); // slug → { tag, ops: [...] }
+    const parameterComponents = doc.components?.parameters ?? {};
+    const groups = new Map();
 
     for (const [path, item] of Object.entries(doc.paths ?? {})) {
         for (const method of HTTP_METHODS) {
@@ -361,7 +447,8 @@ export function generate(doc) {
             const tag = op.tags?.[0] ?? "default";
             const slug = tagSlug(tag);
             if (!groups.has(slug)) groups.set(slug, { tag, slug, ops: [] });
-            groups.get(slug).ops.push({ method, path, op });
+            const params = operationParameters(item, op, parameterComponents);
+            groups.get(slug).ops.push({ method, path, op, params });
         }
     }
 
@@ -378,9 +465,9 @@ export function generate(doc) {
         const Class = `${slugIdent(pascal(slug))}Service`;
 
         const usedNames = new Set(CLASS_MEMBERS);
-        const signature = { refs: new Set(), validates: false };
-        const methods = ops.map(({ method, path, op }) =>
-            emitMethod(method, path, op, schemas, usedNames, signature),
+        const signature = { refs: new Set(), validates: false, sendsHeaders: false };
+        const methods = ops.map(({ method, path, op, params }) =>
+            emitMethod(method, path, op, params, schemas, usedNames, signature),
         );
 
         const used = new Set();
@@ -392,6 +479,10 @@ export function generate(doc) {
         }
         for (const name of signature.refs) collectRefs({ $ref: name }, schemas, used);
         const { sorted, cyclic } = topoSort(used, schemas);
+        assertNoCollision(
+            sorted.map((n) => [n, typeName(n)]),
+            "schema names",
+        );
         for (const name of sorted) assertPatterns(schemas[name], name);
 
         const schemaLines = sorted.map((name) => {
@@ -433,6 +524,7 @@ export function generate(doc) {
                 .filter((group) => group.length)
                 .map((group) => group.join("\n"))
                 .join("\n\n") +
+            (signature.sendsHeaders ? `\n\n${HEADER_RECORD_HELPER}` : "") +
             `\n\n/** Generated service for the "${commentText(tag)}" routes. Inject an ApiClient (createApiClient). */\n` +
             `export class ${Class} {\n` +
             `    constructor(private readonly api: ApiClient) {}\n\n` +
@@ -461,16 +553,27 @@ export function generate(doc) {
  * pagination envelope maps to `OffsetPage<T>` / `CursorPage<T>`, and a body typed
  * by a `$ref` is validated with its Zod schema before the call.
  *
+ * Arguments come in a fixed order: path parameters, `body`, `params` (query),
+ * `headers`. Header parameters are typed like query parameters and sent through
+ * the request's `headers`, via `headerRecord`; the `headers` argument defaults to
+ * `{}` when none of them is required, so a spec gaining an optional header does
+ * not break the call sites. `Accept`, `Content-Type` and `Authorization` are left
+ * out ({@link IGNORED_HEADERS}), and so is every `in: "cookie"` parameter: a
+ * browser `fetch` cannot set `Cookie` (forbidden header name), the cookie jar
+ * sends it with `credentials`.
+ *
  * @param {string} method - The HTTP method, lower case.
  * @param {string} path - The OpenAPI path template.
  * @param {object} op - The operation object.
+ * @param {object[]} parameters - The effective parameters, from {@link operationParameters}.
  * @param {Record<string, object>} schemas - `components.schemas`.
  * @param {Set<string>} usedNames - Member names already taken in the class.
- * @param {{ refs: Set<string>, validates: boolean }} signature - Collects the
- *   component schemas the emitted types name, and whether `S` was used.
+ * @param {{ refs: Set<string>, validates: boolean, sendsHeaders: boolean }} signature -
+ *   Collects the component schemas the emitted types name, whether `S` was used
+ *   and whether `headerRecord` was.
  * @returns {string} The method source.
  */
-function emitMethod(method, path, op, schemas, usedNames, signature) {
+function emitMethod(method, path, op, parameters, schemas, usedNames, signature) {
     let name = methodName(op, method, path);
     if (usedNames.has(name)) {
         let n = 2;
@@ -478,7 +581,11 @@ function emitMethod(method, path, op, schemas, usedNames, signature) {
         name = `${name}${n}`;
     }
     usedNames.add(name);
-    const pathParams = (op.parameters ?? []).filter((p) => p.in === "path");
+    const pathParams = parameters.filter((p) => p.in === "path");
+    const queryParams = parameters.filter((p) => p.in === "query");
+    const headerParams = parameters.filter(
+        (p) => p.in === "header" && !IGNORED_HEADERS.has(p.name.toLowerCase()),
+    );
     const where = `${method.toUpperCase()} ${path}`;
     const paramId = (name) => {
         const id = toIdentifier(name, "camel", `path parameter in ${where}`);
@@ -496,13 +603,11 @@ function emitMethod(method, path, op, schemas, usedNames, signature) {
         [
             ...[...paramIds],
             ...(bodySchema(op) ? [["the request body argument", "body"]] : []),
-            ...((op.parameters ?? []).some((p) => p.in === "query")
-                ? [["the query argument", "params"]]
-                : []),
+            ...(queryParams.length ? [["the query argument", "params"]] : []),
+            ...(headerParams.length ? [["the headers argument", "headers"]] : []),
         ],
         `method arguments of ${where}`,
     );
-    const queryParams = (op.parameters ?? []).filter((p) => p.in === "query");
     const body = bodySchema(op);
     const resp = successSchema(op);
     const page = resp ? detectPage(resp, schemas, signature.refs) : null;
@@ -512,6 +617,14 @@ function emitMethod(method, path, op, schemas, usedNames, signature) {
           ? tsType(resp, signature.refs)
           : "void";
 
+    const fields = (list) =>
+        list
+            .map(
+                (p) =>
+                    `${JSON.stringify(p.name)}${p.required ? "" : "?"}: ${scalarParamType(p.schema, schemas, signature.refs)}`,
+            )
+            .join("; ");
+
     const args = [];
     for (const p of pathParams) {
         args.push(
@@ -519,14 +632,11 @@ function emitMethod(method, path, op, schemas, usedNames, signature) {
         );
     }
     if (body) args.push(`body: ${tsType(body, signature.refs)}`);
-    if (queryParams.length) {
-        const q = queryParams
-            .map(
-                (p) =>
-                    `${JSON.stringify(p.name)}${p.required ? "" : "?"}: ${queryParamType(p.schema, schemas, signature.refs)}`,
-            )
-            .join("; ");
-        args.push(`params: { ${q} }`);
+    if (queryParams.length) args.push(`params: { ${fields(queryParams)} }`);
+    if (headerParams.length) {
+        const optional = headerParams.every((p) => !p.required);
+        args.push(`headers: { ${fields(headerParams)} }${optional ? " = {}" : ""}`);
+        signature.sendsHeaders = true;
     }
 
     const url = urlTemplate(path, segmentArgs);
@@ -534,6 +644,7 @@ function emitMethod(method, path, op, schemas, usedNames, signature) {
     const callOpts = [];
     if (body) callOpts.push("body");
     if (queryParams.length) callOpts.push("params");
+    if (headerParams.length) callOpts.push("headers: headerRecord(headers)");
     const optsArg = callOpts.length ? `, { ${callOpts.join(", ")} }` : "";
 
     let validation = "";

package/bin/lib/openapi/generate.test.mjs

@@ -6,6 +6,7 @@ import { ESLint } from "eslint";
 import ts from "typescript";
 import { describe, expect, it } from "vitest";
 
+import { encodeIdSegment } from "../../../src/data";
 import { generate } from "./generate.mjs";
 
 const SPEC = {
@@ -175,7 +176,7 @@ function templateTsc(files) {
     virtual.set(
         join(OUT, "node_modules", "tempest-react-sdk", "index.d.ts"),
         [
-            "type Call = <T = unknown>(url: string, opts?: { body?: unknown; params?: Record<string, string | number | boolean | undefined | null> }) => Promise<T>;",
+            "type Call = <T = unknown>(url: string, opts?: { body?: unknown; params?: Record<string, string | number | boolean | undefined | null>; headers?: Record<string, string> }) => Promise<T>;",
             "export type ApiClient = { get: Call; post: Call; put: Call; patch: Call; delete: Call };",
             "export type OffsetPage<T> = { items: T[]; total: number };",
             "export type CursorPage<T> = { items: T[]; next_cursor: string | null };",
@@ -244,8 +245,8 @@ const json = (schema) => ({ content: { "application/json": { schema } } });
  * | every `types.ts` | `import * as S` used only in `typeof` — `@typescript-eslint/consistent-type-imports` |
  * | every `index.ts` + root barrel | `simple-import-sort/exports` |
  *
- * Header parameters and path-item-level `parameters` are not read by the
- * generator at all, so they cannot produce an import.
+ * The `X-Trace` header parameter was not read at all then; since #509 it is, and
+ * its `Code` type is imported like any other signature type.
  */
 const EVERY_POSITION = {
     openapi: "3.1.0",
@@ -361,7 +362,7 @@ describe("generate — output passes the create-tempest-app template's tsc and E
 
     it("service.ts imports only the types its signatures name, and S only when a body is validated", () => {
         expect(files["items/service.ts"]).toContain(
-            'import type { Item, ItemCreate, Kind, Sort } from "./types";',
+            'import type { Code, Item, ItemCreate, Kind, Sort } from "./types";',
         );
         expect(files["items/service.ts"]).not.toContain('import * as S from "./schemas";');
         expect(files["reports/service.ts"]).not.toContain("./schemas");
@@ -394,3 +395,201 @@ describe("generate — output passes the create-tempest-app template's tsc and E
         expect(await templateLint(out)).toEqual([]);
     });
 });
+
+/**
+ * Transpile a generated `service.ts` and instantiate its class with a recording
+ * `ApiClient`, to read back the URL and options each call actually sends.
+ * `encodeIdSegment` is the SDK's real one.
+ *
+ * @param {string} source - The generated `service.ts`.
+ * @returns {{ service: object, calls: Array<[string, object | undefined]> }}
+ */
+function instantiate(source) {
+    const { outputText } = ts.transpileModule(source, {
+        compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 },
+    });
+    const module = { exports: {} };
+    const requireStub = (id) => {
+        if (id === "tempest-react-sdk") return { encodeIdSegment };
+        throw new Error(`unexpected import ${id}`);
+    };
+    new Function("exports", "require", "module", outputText)(module.exports, requireStub, module);
+    const calls = [];
+    const api = new Proxy(
+        {},
+        {
+            get: () => async (url, opts) => {
+                calls.push([url, opts]);
+            },
+        },
+    );
+    const Class = Object.values(module.exports).find((v) => typeof v === "function");
+    return { service: new Class(api), calls };
+}
+
+/**
+ * Measured on `main` before #509 with minimal specs run through `generate`:
+ *
+ * | Spec | Output before the fix |
+ * | --- | --- |
+ * | `{id}` declared only on the path item | `getItem(): Promise<void>` calling `"/items/{id}"` — placeholder sent literally |
+ * | path item declares `{x}`, operation declares `{y}` | refused: `placeholder "x" is not a declared path parameter` |
+ * | required `in: "header"` | `list()` — no argument, nothing sent |
+ * | `in: "cookie"` | ignored (stays ignored, on purpose: `fetch` cannot set `Cookie`) |
+ * | path-item query + operation override | the path item's `q` lost; the override only looked right because the path item was never read |
+ * | parameter `$ref` into `components.parameters` | dropped like the path-item case: `"/items/{id}"` literal |
+ */
+const PARAMS = {
+    openapi: "3.1.0",
+    components: {
+        schemas: { Region: { type: "string", enum: ["br", "us"] } },
+        parameters: {
+            Version: { name: "v", in: "path", required: true, schema: { type: "integer" } },
+        },
+    },
+    paths: {
+        "/items/{id}": {
+            parameters: [
+                { name: "id", in: "path", required: true, schema: { type: "string" } },
+                { name: "X-Tenant-Id", in: "header", required: true, schema: { type: "string" } },
+                { name: "limit", in: "query", schema: { type: "string" } },
+            ],
+            get: {
+                tags: ["items"],
+                operationId: "get_item",
+                parameters: [
+                    { name: "limit", in: "query", required: true, schema: { type: "integer" } },
+                    { name: "X-Region", in: "header", schema: ref("Region") },
+                    { name: "Retry-Count", in: "header", schema: { type: "integer" } },
+                    { name: "session", in: "cookie", schema: { type: "string" } },
+                    { name: "Authorization", in: "header", schema: { type: "string" } },
+                ],
+                responses: { 200: { description: "ok" } },
+            },
+            delete: {
+                tags: ["items"],
+                operationId: "delete_item",
+                parameters: [
+                    {
+                        name: "X-Tenant-Id",
+                        in: "header",
+                        required: false,
+                        schema: { type: "string" },
+                    },
+                ],
+                responses: { 204: { description: "gone" } },
+            },
+        },
+        "/v{v}/items": {
+            post: {
+                tags: ["items"],
+                operationId: "create_item",
+                parameters: [
+                    { $ref: "#/components/parameters/Version" },
+                    { name: "Idempotency-Key", in: "header", schema: { type: "string" } },
+                ],
+                responses: { 201: { description: "ok" } },
+            },
+        },
+    },
+};
+
+describe("generate — path-item, header and $ref parameters (#509)", () => {
+    const { files } = generate(PARAMS);
+    const svc = files["items/service.ts"];
+
+    it("a path parameter declared only on the path item is an argument and goes through encodeIdSegment", () => {
+        expect(svc).not.toContain('"/items/{id}"');
+        expect(svc).toContain("`/items/${encodeIdSegment(id)}`");
+    });
+
+    it("path-item and operation parameters merge, the operation winning on the same (name, in)", () => {
+        expect(svc).toContain(
+            'async getItem(id: string, params: { "limit": number }, headers: { "X-Tenant-Id": string; "X-Region"?: Region; "Retry-Count"?: number }): Promise<void>',
+        );
+        expect(svc).toContain(
+            'async deleteItem(id: string, params: { "limit"?: string }, headers: { "X-Tenant-Id"?: string } = {}): Promise<void>',
+        );
+    });
+
+    it("a parameter $ref into components.parameters is resolved", () => {
+        expect(svc).toContain("async createItem(v: number, headers: ");
+        expect(svc).toContain("`/v${encodeIdSegment(v)}/items`");
+    });
+
+    it("cookie parameters and the Accept/Content-Type/Authorization headers are not emitted", () => {
+        expect(svc).not.toContain("session");
+        expect(svc).not.toContain("Authorization");
+    });
+
+    it("header values are sent as strings, and an optional header left out is not sent as 'undefined'", async () => {
+        const { service, calls } = instantiate(svc);
+        await service.getItem("a/b", { limit: 5 }, { "X-Tenant-Id": "t1", "Retry-Count": 3 });
+        await service.deleteItem("7", {});
+        await service.createItem(2);
+        expect(calls).toEqual([
+            [
+                "/items/a%2Fb",
+                { params: { limit: 5 }, headers: { "X-Tenant-Id": "t1", "Retry-Count": "3" } },
+            ],
+            ["/items/7", { params: {}, headers: {} }],
+            ["/v2/items", { headers: {} }],
+        ]);
+    });
+
+    it("type-checks and lints clean under the create-tempest-app template", async () => {
+        expect(templateTsc(files)).toEqual([]);
+        expect(await templateLint(files)).toEqual([]);
+    });
+});
+
+/**
+ * FastAPI publishes a component for every `Enum`-annotated field even when the
+ * field's own schema carries a narrower inline enum, so `ImageMediaType` appears
+ * with no `$ref` pointing at it. Measured on `main` before #516: it was already
+ * left out of every group, because a group only emits the schemas its routes
+ * reach. What did break was the name check, which ran over every
+ * `components.schemas` entry — an orphan whose name collided with another
+ * (`ImageMediaType` / `Image-Media-Type`) aborted the whole run.
+ */
+const ORPHAN_ENUM = {
+    openapi: "3.1.0",
+    components: {
+        schemas: {
+            ImageMediaType: { type: "string", enum: ["image/png", "image/jpeg", "image/webp"] },
+            "Image-Media-Type": { type: "string", enum: ["image/gif"] },
+            Kind: { type: "string", enum: ["photo", "avatar"] },
+            Upload: {
+                type: "object",
+                properties: {
+                    kind: ref("Kind"),
+                    media_type: { type: "string", enum: ["image/png", "image/jpeg"] },
+                },
+            },
+        },
+    },
+    paths: {
+        "/uploads": {
+            post: {
+                tags: ["uploads"],
+                operationId: "create_upload",
+                requestBody: json(ref("Upload")),
+                responses: { 201: json(ref("Upload")) },
+            },
+        },
+    },
+};
+
+describe("generate — enum schemas no $ref reaches (#516)", () => {
+    it("keeps an enum reached transitively and drops the orphan, even when the orphan's name collides", async () => {
+        const { files } = generate(ORPHAN_ENUM);
+        expect(files["uploads/types.ts"]).toContain("export type Kind = ");
+        expect(files["uploads/schemas.ts"]).toContain(
+            'export const KindSchema = z.enum(["photo", "avatar"]);',
+        );
+        expect(Object.values(files).join("\n")).not.toContain("ImageMediaType");
+        expect(Object.values(files).join("\n")).not.toContain("image/webp");
+        expect(templateTsc(files)).toEqual([]);
+        expect(await templateLint(files)).toEqual([]);
+    });
+});

package/bin/lib/openapi/schema-to-zod.mjs

@@ -15,9 +15,9 @@ export function refName(ref) {
 /**
  * Names the generated files declare, import or rely on as globals next to the
  * schema types: the SDK types and the `encodeIdSegment` value `service.ts`
- * imports, the `z` and `S` imports, and the `Promise` / `Record` globals the
- * emitted signatures use. A schema with one of these names would collide with
- * the import or shadow the global.
+ * imports, the `headerRecord` helper it declares, the `z` and `S` imports, and
+ * the `Promise` / `Record` globals the emitted signatures use. A schema with one
+ * of these names would collide with the import or shadow the global.
  */
 export const GENERATED_NAMES = new Set([
     "ApiClient",
@@ -27,6 +27,7 @@ export const GENERATED_NAMES = new Set([
     "Record",
     "S",
     "encodeIdSegment",
+    "headerRecord",
     "z",
 ]);
 

package/dist/http/api-client.cjs

@@ -1,2 +1,2 @@
-const e=require("../utils/ids.cjs"),t=require("./build-url.cjs"),n=require("./credential-scope.cjs"),r=require("./csrf.cjs"),i=require("./decode-response.cjs"),a=require("./errors.cjs"),o=require("./retry.cjs"),s=require("./timeout.cjs");var c=new Set([`GET`,`HEAD`,`OPTIONS`]);function l(e,t){return!c.has(t)||!(e instanceof a.TempestApiError)?!1:a.isRetriableStatus(e.status)}function u(e){return e?e===!0?{}:e:null}var d=15e3,f=3e5;function p(e){return typeof FormData<`u`&&e instanceof FormData}function m(e){return Math.round(performance.now()-e)}async function h(e,t){let n;try{n=await e.clone().json()}catch{try{n=await e.text()}catch{n=null}}return new a.TempestApiError(a.buildApiError(e.status,n,e.headers,t))}function g(c){let g=c.fetcher??globalThis.fetch.bind(globalThis);function _(e,t){if(t)return{};let r=c.getToken?.();return r?n.isTrustedCredentialTarget(e,c.baseURL,c.trustedOrigins)?{Authorization:`Bearer ${r}`}:(n.reportSuppressedCredential(e,c.baseURL),{}):{}}async function v(e,n,i,o){let{body:l,params:u,headers:m,signal:h,timeout:v,...y}=n,b=p(l),x=b?c.uploadTimeout:c.timeout,S=v===void 0?x===void 0?b?f:d:x:v,C=t.buildApiUrl(c.baseURL,e,{prefix:c.prefix,params:u}),w=m,T={...b?{}:{"Content-Type":`application/json`},...i?{"X-Request-ID":i}:{},...c.headers,..._(C,o),...r.csrfHeaders({method:y.method??`GET`,url:C,reference:c.baseURL,csrf:c.csrf,trustedOrigins:c.trustedOrigins,headers:{...c.headers,...w}}),...w},E=s.withTimeout(h,S),D={...y,signal:E.signal,headers:T,credentials:c.withCredentials?`include`:y.credentials,body:l==null?void 0:b?l:JSON.stringify(l)};try{return await g(C,D)}catch(e){throw E.timedOut()?new a.TempestApiError({status:0,detail:`A requisição excedeu ${S}ms e foi abandonada.`}):e}finally{E.dispose()}}async function y(e,t,n,r,i){let a=c.logger;if(!a)return v(e,t,n,i);let o=performance.now();try{let s=await v(e,t,n,i),c={requestId:n,status:s.status,ms:m(o)},l=`${r} ${e} → ${s.status}`;return s.status>=400?a.warn(l,c):a.debug(l,c),s}catch(t){throw a.warn(`${r} ${e} → no response`,{requestId:n,ms:m(o),error:t}),t}}async function b(e,t,n){if(c.onUnauthorized){c.logger?.warn(`unauthorized — calling onUnauthorized`,{requestId:t,status:e.status});try{await c.onUnauthorized(e,n)}catch(n){if(n instanceof a.SessionSupersededError)throw n;c.logger?.warn(`onUnauthorized threw — keeping the original response error`,{requestId:t,status:e.status,error:n})}}}function x(e){return{token:e?null:c.getToken?.()??null,epoch:c.getSessionEpoch?.()??null}}async function S(t,n,r){let{skipAuth:i=!1,skipAuthRetry:o=!1,...s}=n,l=c.requestId?c.requestId():e.randomId(),u=(s.method??`GET`).toUpperCase(),d=x(i),f=await y(t,s,l,u,i);if(f.status===401&&!i&&!o){if(c.refresh){let e;try{await c.refresh(d),e=x(i),f=await y(t,s,l,u,i)}catch(e){throw e instanceof a.SessionSupersededError?e:(await b(f,l,d),await h(f,l))}f.status===401&&await b(f,l,e)}else await b(f,l,d)}if(!f.ok)throw await h(f,l);return r(f)}async function C(e,t,n){let{retry:r,...i}=t,a=u(r===void 0?c.retry:r);if(!a)return S(e,i,n);let s=(i.method??`GET`).toUpperCase();return o.retry(()=>S(e,i,n),{...a,shouldRetry:a.shouldRetry??(e=>l(e,s))})}async function w(e,t={}){return C(e,t,i.decodeByContentType)}async function T(e,t,n=`POST`,r){return w(e,{...r,method:n,body:t})}return{request:w,get:(e,t)=>w(e,{...t,method:`GET`}),post:(e,t)=>w(e,{...t,method:`POST`}),put:(e,t)=>w(e,{...t,method:`PUT`}),patch:(e,t)=>w(e,{...t,method:`PATCH`}),delete:(e,t)=>w(e,{...t,method:`DELETE`}),blob:(e,t)=>C(e,{...t},e=>e.blob()),arrayBuffer:(e,t)=>C(e,{...t},e=>e.arrayBuffer()),upload:T}}exports.createApiClient=g;
+const e=require("../utils/ids.cjs"),t=require("./build-url.cjs"),n=require("./credential-scope.cjs"),r=require("./csrf.cjs"),i=require("./decode-response.cjs"),a=require("./errors.cjs"),o=require("./retry.cjs"),s=require("./timeout.cjs");var c=new Set([`GET`,`HEAD`,`OPTIONS`]);function l(e,t){return!c.has(t)||!(e instanceof a.TempestApiError)?!1:a.isRetriableStatus(e.status)}function u(e){return e?e===!0?{}:e:null}var d=15e3,f=3e5;function p(e){return typeof FormData<`u`&&e instanceof FormData}function m(e){return Math.round(performance.now()-e)}async function h(e,t){let n;try{n=await e.clone().json()}catch{try{n=await e.text()}catch{n=null}}return new a.TempestApiError(a.buildApiError(e.status,n,e.headers,t))}function g(c){let g=c.fetcher??globalThis.fetch.bind(globalThis);function _(e,t){if(t)return{};let r=c.getToken?.();return r?n.isTrustedCredentialTarget(e,c.baseURL,c.trustedOrigins)?{Authorization:`Bearer ${r}`}:(n.reportSuppressedCredential(e,c.baseURL),{}):{}}async function v(e,n,i,o){let{body:l,params:u,headers:m,signal:h,timeout:v,...y}=n,b=p(l),x=b?c.uploadTimeout:c.timeout,S=v===void 0?x===void 0?b?f:d:x:v,C=t.buildApiUrl(c.baseURL,e,{prefix:c.prefix,params:u}),w=m,T={...b?{}:{"Content-Type":`application/json`},...i?{"X-Request-ID":i}:{},...c.headers,..._(C,o),...r.csrfHeaders({method:y.method??`GET`,url:C,reference:c.baseURL,csrf:c.csrf,trustedOrigins:c.trustedOrigins,headers:{...c.headers,...w}}),...w},E=s.withTimeout(h,S),D={...y,signal:E.signal,headers:T,credentials:c.withCredentials?`include`:y.credentials,body:l==null?void 0:b?l:JSON.stringify(l)};try{return await g(C,D)}catch(e){throw E.timedOut()?new a.TempestApiError({status:0,detail:`A requisição excedeu ${S}ms e foi abandonada.`}):e}finally{E.dispose()}}async function y(e,t,n,r,i){let a=c.logger;if(!a)return v(e,t,n,i);let o=performance.now();try{let s=await v(e,t,n,i),c={requestId:n,status:s.status,ms:m(o)},l=`${r} ${e} → ${s.status}`;return s.status>=400?a.warn(l,c):a.debug(l,c),s}catch(t){throw a.warn(`${r} ${e} → no response`,{requestId:n,ms:m(o),error:t}),t}}async function b(e,t,n){if(c.onUnauthorized){c.logger?.warn(`unauthorized — calling onUnauthorized`,{requestId:t,status:e.status});try{await c.onUnauthorized(e,n)}catch(n){if(n instanceof a.SessionSupersededError)throw n;c.logger?.warn(`onUnauthorized threw — keeping the original response error`,{requestId:t,status:e.status,error:n})}}}function x(e){return{token:e?null:c.getToken?.()??null,epoch:c.getSessionEpoch?.()??null}}async function S(t,n,r){let{skipAuth:i=!1,skipAuthRetry:o=!1,...s}=n,l=c.requestId?c.requestId():e.randomId(),u=(s.method??`GET`).toUpperCase(),d=x(i),f=await y(t,s,l,u,i);if(f.status===401&&!i&&!o){if(c.refresh){let e;try{await c.refresh(d),e=x(i),f=await y(t,s,l,u,i)}catch(e){throw e instanceof a.SessionSupersededError?e:(await b(f,l,d),await h(f,l))}f.status===401&&await b(f,l,e)}else await b(f,l,d)}if(!f.ok)throw await h(f,l);return r(f)}async function C(e,t,n){let{retry:r,...i}=t,a=u(r===void 0?c.retry:r);if(!a)return S(e,i,n);let s=(i.method??`GET`).toUpperCase();return o.retry(()=>S(e,i,n),{...a,shouldRetry:a.shouldRetry??(e=>l(e,s))})}async function w(e,t={}){return C(e,t,i.decodeByContentType)}async function T(e,t,n=`POST`,r){return w(e,{...r,method:n,body:t})}return{request:w,get:(e,t)=>w(e,{...t,method:`GET`}),post:(e,t)=>w(e,{...t,method:`POST`}),put:(e,t)=>w(e,{...t,method:`PUT`}),patch:(e,t)=>w(e,{...t,method:`PATCH`}),delete:(e,t)=>w(e,{...t,method:`DELETE`}),blob:(e,t)=>C(e,{...t},e=>e.blob()),arrayBuffer:(e,t)=>C(e,{...t},e=>e.arrayBuffer()),upload:T,url:(e,n)=>t.buildApiUrl(c.baseURL,e,{prefix:c.prefix,params:n})}}exports.createApiClient=g;
 //# sourceMappingURL=api-client.cjs.map