tempest-react-sdk 0.78.0 → 0.80.0

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` —
@@ -128,13 +204,30 @@ function collectRefs(node, schemas, acc = new Set(), seen = new Set()) {
     return acc;
 }
 
-/** TS type expression for a schema node (uses generated type names for $refs). */
-function tsType(schema) {
+/**
+ * TS type expression for a schema node (uses generated type names for $refs).
+ *
+ * Every component schema the expression names is added to `refs`, so the caller
+ * imports exactly the types its signatures mention: a path parameter typed by a
+ * `$ref` used to print `kind: Kind` without importing `Kind` (#504), and a page
+ * envelope or a nested schema used to be imported without being mentioned, which
+ * the template's `unused-imports/no-unused-imports` and `noUnusedLocals` reject
+ * (#505).
+ *
+ * @param {object | undefined} schema - The schema node.
+ * @param {Set<string>} [refs] - Collects the spec names of the referenced schemas.
+ * @returns {string} The TypeScript type expression.
+ */
+function tsType(schema, refs = new Set()) {
     if (!schema || typeof schema !== "object") return "unknown";
-    if (schema.$ref) return typeName(refName(schema.$ref));
-    if (schema.allOf) return schema.allOf.map(tsType).join(" & ");
+    if (schema.$ref) {
+        const name = refName(schema.$ref);
+        refs.add(name);
+        return typeName(name);
+    }
+    if (schema.allOf) return schema.allOf.map((s) => tsType(s, refs)).join(" & ");
     if (schema.anyOf || schema.oneOf) {
-        const parts = (schema.anyOf ?? schema.oneOf).map(tsType);
+        const parts = (schema.anyOf ?? schema.oneOf).map((s) => tsType(s, refs));
         return [...new Set(parts)].join(" | ");
     }
     const t = Array.isArray(schema.type) ? schema.type.find((x) => x !== "null") : schema.type;
@@ -156,7 +249,7 @@ function tsType(schema) {
         case "null":
             return "null";
         case "array":
-            base = `${tsType(schema.items)}[]`;
+            base = `${tsType(schema.items, refs)}[]`;
             break;
         case "object":
         default:
@@ -165,16 +258,45 @@ function tsType(schema) {
     return nul ? `${base} | null` : base;
 }
 
+/** JSON Schema types whose TypeScript type the client's `params` values accept. */
+const QUERY_SCALARS = new Set(["string", "integer", "number", "boolean", "null"]);
+
+/**
+ * Whether a query parameter's schema only ever produces a value the client's
+ * `params` accepts (`string | number | boolean | null`).
+ *
+ * `$ref` chains are followed, so an enum declared in `components/schemas` keeps
+ * its name in the signature instead of being narrowed to `string`; unions qualify
+ * when every branch does.
+ *
+ * @param {object | undefined} schema - The parameter's schema.
+ * @param {Record<string, object>} schemas - `components.schemas`.
+ * @param {number} [depth] - Recursion guard for self-referencing unions.
+ * @returns {boolean} `true` when the TypeScript type is assignable to the client's `params` values.
+ */
+function isQueryScalar(schema, schemas, depth = 0) {
+    const node = resolveSchema(schema, schemas);
+    if (!node || typeof node !== "object" || depth > 16) return false;
+    const branches = node.anyOf ?? node.oneOf ?? (node.allOf?.length === 1 ? node.allOf : null);
+    if (branches) return branches.every((b) => isQueryScalar(b, schemas, depth + 1));
+    const types = Array.isArray(node.type) ? node.type : [node.type];
+    return types.every((t) => QUERY_SCALARS.has(t));
+}
+
 /**
- * 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 of objects) 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) {
-    const t = tsType(schema ?? { type: "string" });
-    const allowed = new Set(["string", "number", "boolean", "null"]);
-    const ok = t.split("|").every((part) => allowed.has(part.trim()));
-    return ok ? t : "string";
+function scalarParamType(schema, schemas, refs) {
+    const node = schema ?? { type: "string" };
+    return isQueryScalar(node, schemas) ? tsType(node, refs) : "string";
 }
 
 /** Turn a tag slug into a JS-safe identifier ("chat-messages" → "chatMessages"). */
@@ -221,22 +343,23 @@ function resolveSchema(schema, schemas) {
  *   items + total + pages + (size | page_size).
  * Cursor (`CursorPaginationSchema`): items + next_cursor + has_more.
  *
+ * @param {object} schema - The success response schema.
+ * @param {Record<string, object>} schemas - `components.schemas`.
+ * @param {Set<string>} [refs] - Collects the schemas the item type names.
  * @returns {{ kind: "offset"|"cursor", itemType: string }|null}
  */
-function detectPage(schema, schemas) {
+function detectPage(schema, schemas, refs = new Set()) {
     const node = resolveSchema(schema, schemas);
     const props = node?.properties;
     if (!props || !props.items || resolveSchema(props.items, schemas)?.type !== "array") {
         return null;
     }
-    const itemType = tsType(resolveSchema(props.items, schemas).items);
-    if ("total" in props && "pages" in props && ("size" in props || "page_size" in props)) {
-        return { kind: "offset", itemType };
-    }
-    if ("next_cursor" in props && "has_more" in props) {
-        return { kind: "cursor", itemType };
-    }
-    return null;
+    const offset =
+        "total" in props && "pages" in props && ("size" in props || "page_size" in props);
+    const cursor = "next_cursor" in props && "has_more" in props;
+    if (!offset && !cursor) return null;
+    const itemType = tsType(resolveSchema(props.items, schemas).items, refs);
+    return { kind: offset ? "offset" : "cursor", itemType };
 }
 
 /** Extract the success ($2xx) JSON response schema of an operation. */
@@ -254,19 +377,68 @@ function bodySchema(op) {
     return op.requestBody?.content?.["application/json"]?.schema ?? null;
 }
 
+/**
+ * Contents of a `schemas.ts` / `types.ts` for a group whose routes reference no
+ * component schema. The file still exists so every group has the same layout and
+ * `index.ts` re-exports it unconditionally, but it imports nothing: an unused `z`
+ * or `S` fails the template's lint and `noUnusedLocals` (#505).
+ */
+const EMPTY_MODULE = "export {};\n";
+
+/**
+ * Collator `eslint-plugin-simple-import-sort` orders import sources and
+ * specifiers with. Ported from eslint-plugin-simple-import-sort's `compare`
+ * (`shared.js`, v14).
+ */
+const IMPORT_COLLATOR = new Intl.Collator("en", { sensitivity: "base", numeric: true });
+
+/**
+ * Order two import sources or specifiers the way the template's
+ * `simple-import-sort` rules do, so the generated imports and barrels pass them
+ * without an autofix. Ported from eslint-plugin-simple-import-sort's `compare`
+ * (`shared.js`, v14): case-insensitive and numeric-aware, with a code-unit
+ * tie-break.
+ *
+ * @param {string} a - First name.
+ * @param {string} b - Second name.
+ * @returns {number} Negative when `a` sorts first, positive when `b` does.
+ */
+function compareNames(a, b) {
+    return IMPORT_COLLATOR.compare(a, b) || (a < b ? -1 : a > b ? 1 : 0);
+}
+
 /**
  * Generate the per-tag files from a parsed OpenAPI document.
  *
+ * Each group gets `schemas.ts` (Zod, for every component schema its bodies,
+ * responses and parameters reach transitively), `types.ts`, `service.ts` and an
+ * `index.ts`; the root barrel re-exports each group as a namespace so a schema
+ * name shared by two groups does not collide. `service.ts` imports only what its
+ * signatures and bodies use — the types they name, `S` when a body is validated,
+ * the pagination envelopes and `encodeIdSegment` when they appear — and every
+ * import and re-export is emitted in the order the `create-tempest-app`
+ * 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) {
@@ -275,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 });
         }
     }
 
@@ -291,7 +464,12 @@ export function generate(doc) {
         tags.push(tag);
         const Class = `${slugIdent(pascal(slug))}Service`;
 
-        // 1. Which component schemas does this group touch (transitively)?
+        const usedNames = new Set(CLASS_MEMBERS);
+        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();
         for (const { op } of ops) {
             const b = bodySchema(op);
@@ -299,10 +477,14 @@ export function generate(doc) {
             if (b) collectRefs(b, schemas, used);
             if (r) collectRefs(r, schemas, used);
         }
+        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);
 
-        // 2. schemas.ts
         const schemaLines = sorted.map((name) => {
             const expr = schemaToZod(schemas[name], (ref) => {
                 const n = refName(ref);
@@ -310,71 +492,100 @@ export function generate(doc) {
             });
             return `export const ${zodName(name)} = ${expr};`;
         });
-        files[`${slug}/schemas.ts`] = `import { z } from "zod";\n\n${schemaLines.join("\n\n")}\n`;
+        files[`${slug}/schemas.ts`] = sorted.length
+            ? `import { z } from "zod";\n\n${schemaLines.join("\n\n")}\n`
+            : EMPTY_MODULE;
 
-        // 3. types.ts
         const typeLines = sorted.map(
             (name) => `export type ${typeName(name)} = z.infer<typeof S.${zodName(name)}>;`,
         );
-        files[`${slug}/types.ts`] =
-            `import type { z } from "zod";\n\nimport * as S from "./schemas";\n\n${typeLines.join("\n")}\n`;
+        files[`${slug}/types.ts`] = sorted.length
+            ? `import type { z } from "zod";\n\nimport type * as S from "./schemas";\n\n${typeLines.join("\n")}\n`
+            : EMPTY_MODULE;
 
-        // 4. service.ts
-        const usedNames = new Set(CLASS_MEMBERS);
-        const methods = ops.map(({ method, path, op }) =>
-            emitMethod(method, path, op, schemas, usedNames),
-        );
-        const usedTypeNames = [...used].map(typeName).sort();
-        const typeImport = usedTypeNames.length
-            ? `import type { ${usedTypeNames.join(", ")} } from "./types";\n`
-            : "";
-        const schemaImport = usedTypeNames.length ? `import * as S from "./schemas";\n` : "";
         const body = methods.join("\n\n");
-        // Pagination envelopes are re-exported from the SDK; import what we used.
         const sdkTypes = ["ApiClient"];
         if (body.includes("OffsetPage<")) sdkTypes.push("OffsetPage");
         if (body.includes("CursorPage<")) sdkTypes.push("CursorPage");
-        const sdkValues = body.includes("encodeIdSegment(")
-            ? `import { encodeIdSegment } from "tempest-react-sdk";\n`
-            : "";
+        const packageImports = [
+            `import type { ${sdkTypes.sort(compareNames).join(", ")} } from "tempest-react-sdk";`,
+        ];
+        if (body.includes("encodeIdSegment(")) {
+            packageImports.push(`import { encodeIdSegment } from "tempest-react-sdk";`);
+        }
+        const localImports = [];
+        if (signature.validates) localImports.push(`import * as S from "./schemas";`);
+        const signatureTypes = [...signature.refs].map(typeName).sort(compareNames);
+        if (signatureTypes.length) {
+            localImports.push(`import type { ${signatureTypes.join(", ")} } from "./types";`);
+        }
         files[`${slug}/service.ts`] =
-            `import type { ${sdkTypes.join(", ")} } from "tempest-react-sdk";\n` +
-            sdkValues +
-            "\n" +
-            schemaImport +
-            typeImport +
-            `\n/** Generated service for the "${commentText(tag)}" routes. Inject an ApiClient (createApiClient). */\n` +
+            [packageImports, localImports]
+                .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` +
             body +
             `\n}\n`;
 
-        // 5. index.ts (re-export)
         files[`${slug}/index.ts`] =
-            `export * from "./schemas";\nexport * from "./types";\nexport { ${Class} } from "./service";\n`;
+            `export * from "./schemas";\nexport { ${Class} } from "./service";\nexport * from "./types";\n`;
     }
 
-    // Root barrel — namespaced per group so schema/type names shared across
-    // groups (e.g. UserResponseSchema in both `admin` and `auth`) don't collide.
     files["index.ts"] =
         [...groups.values()]
-            .map(({ slug }) => `export * as ${slugIdent(slug)} from "./${slug}";`)
+            .map(({ slug }) => slug)
+            .sort((a, b) => compareNames(`./${a}`, `./${b}`))
+            .map((slug) => `export * as ${slugIdent(slug)} from "./${slug}";`)
             .join("\n") + "\n";
 
     return { files, tags };
 }
 
-/** Emit a single class method for one operation. */
-function emitMethod(method, path, op, schemas, usedNames = new Set()) {
+/**
+ * Emit a single class method for one operation.
+ *
+ * A method name already taken in the group is deduplicated with a numeric suffix
+ * (operationIds `home__get` / `home_get` → `homeGet`, `homeGet2`). A Tempest
+ * 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, 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, parameters, schemas, usedNames, signature) {
     let name = methodName(op, method, path);
-    // Dedupe collisions within a group (e.g. operationIds "home__get" / "home_get").
     if (usedNames.has(name)) {
         let n = 2;
         while (usedNames.has(`${name}${n}`)) n += 1;
         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}`);
@@ -392,36 +603,40 @@ function emitMethod(method, path, op, schemas, usedNames = new Set()) {
         [
             ...[...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);
-    // Map a Tempest pagination envelope to OffsetPage<T>/CursorPage<T>.
-    const page = resp ? detectPage(resp, schemas) : null;
+    const page = resp ? detectPage(resp, schemas, signature.refs) : null;
     const retType = page
         ? `${page.kind === "offset" ? "OffsetPage" : "CursorPage"}<${page.itemType}>`
         : resp
-          ? tsType(resp)
+          ? tsType(resp, signature.refs)
           : "void";
 
-    const args = [];
-    for (const p of pathParams) {
-        args.push(`${paramIds.get(p.name)}: ${tsType(p.schema ?? { type: "string" })}`);
-    }
-    if (body) args.push(`body: ${tsType(body)}`);
-    if (queryParams.length) {
-        const q = queryParams
+    const fields = (list) =>
+        list
             .map(
                 (p) =>
-                    `${JSON.stringify(p.name)}${p.required ? "" : "?"}: ${queryParamType(p.schema)}`,
+                    `${JSON.stringify(p.name)}${p.required ? "" : "?"}: ${scalarParamType(p.schema, schemas, signature.refs)}`,
             )
             .join("; ");
-        args.push(`params: { ${q} }`);
+
+    const args = [];
+    for (const p of pathParams) {
+        args.push(
+            `${paramIds.get(p.name)}: ${tsType(p.schema ?? { type: "string" }, signature.refs)}`,
+        );
+    }
+    if (body) args.push(`body: ${tsType(body, signature.refs)}`);
+    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);
@@ -429,13 +644,13 @@ function emitMethod(method, path, op, schemas, usedNames = new Set()) {
     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(", ")} }` : "";
 
-    // Zod input validation: validate the body when it references a known schema.
     let validation = "";
     if (body && body.$ref) {
-        const schemaConst = `S.${zodName(refName(body.$ref))}`;
-        validation = `        ${schemaConst}.parse(body);\n`;
+        signature.validates = true;
+        validation = `        S.${zodName(refName(body.$ref))}.parse(body);\n`;
     }
 
     const ret = retType === "void" ? "Promise<void>" : `Promise<${retType}>`;

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

@@ -78,9 +78,10 @@ describe("generate — pagination envelopes", () => {
         expect(svc).toMatch(/async feedPosts\(\): Promise<CursorPage<Post>>/);
     });
 
-    it("imports the page types from the SDK", () => {
+    it("imports the page types from the SDK, in the order simple-import-sort enforces (#505)", () => {
         expect(svc).toContain(
-            'import type { ApiClient, OffsetPage, CursorPage } from "tempest-react-sdk";',
+            'import type { ApiClient, CursorPage, OffsetPage } from "tempest-react-sdk";',
         );
+        expect(svc).not.toContain("ApiClient, OffsetPage, CursorPage");
     });
 });