swaggie 2.0.0 → 2.1.0-alpha.4

package/README.md

@@ -91,9 +91,12 @@ swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore
     --servicePrefix            Prefix for service names — useful when generating multiple APIs
     --allowDots                Use dot notation to serialize nested object query params
     --arrayFormat              How arrays are serialized: "indices", "repeat", or "brackets"
--C, --useClient                Prepend 'use client'; directive (Next.js App Router + SWR/TSQ)
+-C, --useClient                Prepend 'use client'; to the hooks file (with --hooksOut) or the main file (single-file mode)
+    --hooksOut <filePath>      Output path for the generated hooks file (L2 templates only). Splits hooks into a separate server-safe file
     --mocks <path>             Output path for a generated mock/stub file (requires --testingFramework and --out)
 -T, --testingFramework <name>  Framework for generated mocks: "vitest" or "jest" (requires --mocks and --out)
+    --clientSetup <path>       Output path for the write-once client setup file. Generated on first run; never overwritten unless --forceSetup is set. For the ky template, the generated api.ts imports from this file. For other templates, it is a standalone scaffold. Requires --out
+    --forceSetup               Overwrite the setup file even if it already exists (requires --clientSetup)
 -h, --help                     Show help
 ```
 
@@ -158,6 +161,7 @@ These are standalone and cover the most common client libraries:
 | `axios`  | Default. Recommended for React, Vue, and most Node.js projects |
 | `fetch`  | Native browser/Node 18+ Fetch API — zero runtime dependencies |
 | `xior`   | Lightweight Axios-compatible alternative ([xior](https://github.com/suhaotian/xior#intro)) |
+| `ky`     | Modern fetch-based HTTP client with hooks ([ky](https://github.com/sindresorhus/ky)) |
 | `ng1`    | Angular 1 client |
 | `ng2`    | Angular 2+ client (uses `HttpClient` and `InjectionToken`) |
 
@@ -170,7 +174,7 @@ These add a reactive data-fetching layer (SWR or TanStack Query hooks) on top of
 | `swr`    | [SWR](https://swr.vercel.app) hooks for queries and mutations |
 | `tsq`    | [TanStack Query](https://tanstack.com/query) hooks for queries and mutations |
 
-Compatible http client templates: `axios`, `fetch`, `xior`. Angular clients are not compatible with reactive layers.
+Compatible http client templates: `axios`, `fetch`, `xior`, `ky`. Angular clients are not compatible with reactive layers.
 
 ### Usage examples
 
@@ -412,6 +416,52 @@ Either tool needs to be installed separately and configured for your project.
 
 ---
 
+## Next.js App Router — Split-file Mode
+
+SWR and TanStack Query hooks can only run in React Client Components. In Next.js App Router projects you may want:
+
+- The HTTP clients and types available on **both** the server and client sides
+- The reactive hooks restricted to **Client Components only** (with `'use client';`)
+
+Use `--hooksOut` to generate two separate files:
+
+```bash
+swaggie -s ./openapi.yaml \
+  -o ./src/api/client.ts \
+  --hooksOut ./src/api/hooks.ts \
+  -t swr,axios \
+  --useClient
+```
+
+Or in a config file:
+
+```json
+{
+  "src": "./openapi.yaml",
+  "out": "./src/api/client.ts",
+  "hooksOut": "./src/api/hooks.ts",
+  "template": ["swr", "axios"],
+  "useClient": true
+}
+```
+
+This produces:
+
+- `client.ts` — HTTP client objects + TypeScript types. No `'use client'` directive. Safe to import in Server Components and API routes.
+- `hooks.ts` — Reactive hook namespaces. Has `'use client';` at the top. Imports the main file as `import * as API from './client'`.
+
+In your components:
+
+```ts
+// Server Component or API route — no 'use client' needed
+import { petClient } from './api/client';
+
+// Client Component only
+import { pet } from './api/hooks';
+```
+
+---
+
 ## Generating Mocks
 
 Swaggie can generate a companion mock file alongside your client — a set of typed spy stubs for every method and hook, ready to drop into your tests.

package/dist/cli.js

@@ -101,11 +101,29 @@ program
   .addOption(dateFormatOption)
   .addOption(nullableStrategyOption)
   .addOption(queryParamsAsObjectOption)
+  .option(
+    '--hooksOut <filePath>',
+    'Output path for the generated hooks file (L2 templates only). ' +
+      'When set, reactive hooks are written to this file and the main --out file contains only HTTP clients and types. ' +
+      'The hooks file imports the main file as `import * as API from \'./api\'`. ' +
+      'Use together with --useClient for Next.js App Router.'
+  )
   .option(
     '--mocks <path>',
     'Output path for the generated mock/stub file (requires --testingFramework and --out)'
   )
-  .addOption(testingFrameworkOption);
+  .addOption(testingFrameworkOption)
+  .option(
+    '--clientSetup <path>',
+    'Output path for the write-once client setup file. ' +
+      'Generated on the first run; never overwritten on subsequent runs (use --forceSetup to override). ' +
+      'For the ky template, the generated api.ts imports from this file. ' +
+      'For other templates, it is a standalone scaffold. Requires --out.'
+  )
+  .option(
+    '--forceSetup',
+    'Overwrite the client setup file even if it already exists (requires --clientSetup)'
+  );
 
 program.parse(process.argv);
 

package/dist/gen/genMocks.js

@@ -31,14 +31,18 @@ const MOCK_FILE_HEADER = `\
  *   helpers (`mockSWR`, `mockQuery`, etc.) — L2 templates only (swr/tsq)
  * - `ApiHookMocks` type alias — L2 templates only
  *
- * @param spec              The OpenAPI document
- * @param options           Generator options (must have `testingFramework` set)
- * @param relativeApiImport Relative import path from the mock file to the real client file
+ * @param spec                 The OpenAPI document
+ * @param options              Generator options (must have `testingFramework` set)
+ * @param relativeApiImport    Relative import path from the mock file to the main client file
+ * @param relativeHooksImport  Relative import path from the mock file to the hooks file
+ *                             (only provided when --hooksOut is set). When present, hook mocks
+ *                             reference the hooks file instead of the main file.
  */
  function generateMocks(
   spec,
   options,
-  relativeApiImport
+  relativeApiImport,
+  relativeHooksImport
 ) {
   const fw = options.testingFramework;
   const template = options.template;
@@ -91,8 +95,14 @@ const MOCK_FILE_HEADER = `\
 
   // ── Standard path (axios / fetch / xior / swr / tsq) ───────────────────────
 
-  // Real client import — needed for spyOn targets
+  // Real client import — needed for spyOn targets on *Client methods
   result += `import * as realApi from '${relativeApiImport}';\n`;
+
+  // When hooks live in a separate file (--hooksOut), import that file too for hook spies
+  const hooksAlias = relativeHooksImport ? 'realHooks' : 'realApi';
+  if (relativeHooksImport && l2) {
+    result += `import * as realHooks from '${relativeHooksImport}';\n`;
+  }
   result += '\n';
 
   // SWR/TSQ helper functions and default return values (L2 only)
@@ -116,12 +126,12 @@ const MOCK_FILE_HEADER = `\
   // ── createApiHookMocks (L2 only) ────────────────────────────────────────────
   if (l2 === 'swr') {
     result += '\n';
-    result += buildCreateSwrHookMocks(preparedGroups, fw);
+    result += buildCreateSwrHookMocks(preparedGroups, fw, hooksAlias);
     result += '\n';
     result += 'export type ApiHookMocks = ReturnType<typeof createApiHookMocks>;\n';
   } else if (l2 === 'tsq') {
     result += '\n';
-    result += buildCreateTsqHookMocks(preparedGroups, fw);
+    result += buildCreateTsqHookMocks(preparedGroups, fw, hooksAlias);
     result += '\n';
     result += 'export type ApiHookMocks = ReturnType<typeof createApiHookMocks>;\n';
   }
@@ -187,7 +197,7 @@ function buildNg2CreateClientMocks(
 
 function buildFrameworkImport(fw) {
   return fw === 'vitest'
-    ? "import { vi } from 'vitest';\n"
+    ? "import { type MockInstance, vi } from 'vitest';\n"
     : "import { jest } from '@jest/globals';\n";
 }
 
@@ -302,14 +312,22 @@ const defaultMutationReturn = {
 }
 
 function buildTsqHelpers(fw) {
-  const ref = fwRef(fw);
   return `\
 // ─── TanStack Query mock helpers ─────────────────────────────────────────────
 
+interface MockQueryReturn {
+  /** The data to return from the mock */
+  data: unknown;
+  /** Whether to return a loading state (default: false) */
+  isLoading?: boolean;
+  /** Whether to return an error (default: undefined) */
+  error?: Error | null;
+}
+
 /** Augments a spy with a \`mockQuery\` shorthand for useQuery hooks. */
-function withMockQuery<T extends ReturnType<typeof ${ref}.spyOn>>(spy: T) {
+function withMockQuery<T extends MockInstance>(spy: T) {
   return Object.assign(spy, {
-    mockQuery({ data, isLoading, error }: { data?: unknown; isLoading?: boolean; error?: Error }) {
+    mockQuery({ data, isLoading, error }: MockQueryReturn) {
       const pending = isLoading ?? false;
       spy.mockReturnValue({
         ...defaultQueryReturn,
@@ -324,10 +342,19 @@ function withMockQuery<T extends ReturnType<typeof ${ref}.spyOn>>(spy: T) {
   });
 }
 
+interface MockMutationReturn {
+  /** The data to return from the mock */
+  data: unknown;
+  /** Whether to return a mutating state (default: false) */
+  isPending?: boolean;
+  /** Whether to return an error (default: undefined) */
+  error?: Error | null;
+}
+
 /** Augments a spy with a \`mockMutation\` shorthand for useMutation hooks. */
-function withMockMutation<T extends ReturnType<typeof ${ref}.spyOn>>(spy: T) {
+function withMockMutation<T extends MockInstance>(spy: T) {
   return Object.assign(spy, {
-    mockMutation({ data, isPending, error }: { data?: unknown; isPending?: boolean; error?: Error }) {
+    mockMutation({ data, isPending, error }: MockMutationReturn) {
       spy.mockReturnValue({
         ...defaultMutationReturn,
         mutate: ${fn(fw)},
@@ -366,7 +393,8 @@ function buildCreateClientMocks(
 
 function buildCreateSwrHookMocks(
   groups,
-  fw
+  fw,
+  hooksAlias
 ) {
   const spy = spyFn(fw);
   const lines = ['export function createApiHookMocks() {', '  return {'];
@@ -380,7 +408,7 @@ function buildCreateSwrHookMocks(
     for (const op of getOps) {
       const hookName = toHookName(op.name, 'use');
       lines.push(
-        `        ${hookName}: withMockSWR(${spy}(realApi.${camelName}.queries, '${hookName}').mockReturnValue(defaultSWRReturn)),`
+        `        ${hookName}: withMockSWR(${spy}(${hooksAlias}.${camelName}.queries, '${hookName}').mockReturnValue(defaultSWRReturn)),`
       );
     }
     lines.push('      },');
@@ -388,7 +416,7 @@ function buildCreateSwrHookMocks(
     for (const op of mutOps) {
       const hookName = 'use' + _case.pascal.call(void 0, op.name);
       lines.push(
-        `        ${hookName}: withMockSWRMutation(${spy}(realApi.${camelName}.mutations, '${hookName}').mockReturnValue(defaultSWRMutationReturn as any)),`
+        `        ${hookName}: withMockSWRMutation(${spy}(${hooksAlias}.${camelName}.mutations, '${hookName}').mockReturnValue(defaultSWRMutationReturn as any)),`
       );
     }
     lines.push('      },');
@@ -402,7 +430,8 @@ function buildCreateSwrHookMocks(
 
 function buildCreateTsqHookMocks(
   groups,
-  fw
+  fw,
+  hooksAlias
 ) {
   const spy = spyFn(fw);
   const lines = ['export function createApiHookMocks() {', '  return {'];
@@ -416,7 +445,7 @@ function buildCreateTsqHookMocks(
     for (const op of getOps) {
       const hookName = toHookName(op.name, 'use');
       lines.push(
-        `        ${hookName}: withMockQuery(${spy}(realApi.${camelName}.queries, '${hookName}').mockReturnValue(defaultQueryReturn)),`
+        `        ${hookName}: withMockQuery(${spy}(${hooksAlias}.${camelName}.queries, '${hookName}').mockReturnValue(defaultQueryReturn as any)),`
       );
     }
     lines.push('      },');
@@ -424,7 +453,7 @@ function buildCreateTsqHookMocks(
     for (const op of mutOps) {
       const hookName = 'use' + _case.pascal.call(void 0, op.name);
       lines.push(
-        `        ${hookName}: withMockMutation(${spy}(realApi.${camelName}.mutations, '${hookName}').mockReturnValue(defaultMutationReturn)),`
+        `        ${hookName}: withMockMutation(${spy}(${hooksAlias}.${camelName}.mutations, '${hookName}').mockReturnValue(defaultMutationReturn as any)),`
       );
     }
     lines.push('      },');

package/dist/gen/genOperations.js

@@ -25,30 +25,48 @@ var _jsDocs = require('./jsDocs');
 
 /**
  * Function that will analyze paths in the spec and generate the code for all the operations.
+ *
+ * @param relativeSetupImport - When `--clientSetup` is active for the ky template, the relative
+ *   import path from the generated `api.ts` to the setup file (e.g. `'./api.setup'`).
+ *   Used to embed the import in `baseClientWithSetup.ejs` and passed to each operation
+ *   as `httpAccessor` (`'getKyHttp()'` vs the default `'http'`).
  */
  async function generateOperations(
   spec,
-  options
+  options,
+  relativeSetupImport
 ) {
   const operations = _swagger.getOperations.call(void 0, spec);
   const groups = _utils.groupOperationsByGroupName.call(void 0, operations);
   const servicePrefix = options.servicePrefix;
+  const isKyWithSetup = _templateValidator.getL1Template.call(void 0, options.template) === 'ky' && !!options.clientSetup;
+
   const baseClientData = {
     servicePrefix,
     baseUrl: options.baseUrl,
     ...options.queryParamsSerialization,
+    // For the ky+setup variant, embed the relative import to the setup file
+    ...(isKyWithSetup && relativeSetupImport ? { relativeSetupImport } : {}),
   };
 
   // When a composite [L2, L1] template is used, the L2 base client contains
   // reactive library imports (e.g. useSWR, useQuery). These are placed first
   // so all imports appear at the top of the file before the HTTP client setup.
+  // When hooksOut is set, the L2 base client goes into the hooks file instead.
   let baseClients = '';
-  if (_templateEngine.hasTemplateFile.call(void 0, 'baseClientL2.ejs')) {
+  if (_templateEngine.hasTemplateFile.call(void 0, 'baseClientL2.ejs') && !options.hooksOut) {
     baseClients += _templateEngine.renderFile.call(void 0, 'baseClientL2.ejs', baseClientData);
   }
-  baseClients += _templateEngine.renderFile.call(void 0, 'baseClient.ejs', baseClientData);
-
-  const clientDirective = options.useClient ? "'use client';\n" : '';
+  // For ky with --clientSetup, use the lazy initKyHttp/getKyHttp pattern.
+  // We rely on the template being present (always bundled for ky), so no
+  // hasTemplateFile guard — hasTemplateFile returns false for directory templates.
+  const baseClientTemplate =
+    isKyWithSetup ? 'baseClientWithSetup.ejs' : 'baseClient.ejs';
+  baseClients += _templateEngine.renderFile.call(void 0, baseClientTemplate, baseClientData);
+
+  // When hooksOut is set, the 'use client' directive belongs in the hooks file only.
+  // In single-file mode (no hooksOut), keep prepending it to the main file.
+  const clientDirective = options.useClient && !options.hooksOut ? "'use client';\n" : '';
   let result = clientDirective + _header.FILE_HEADER + baseClients;
 
   for (const name in groups) {
@@ -63,6 +81,16 @@ var _jsDocs = require('./jsDocs');
       ...clientData,
       servicePrefix,
       httpConfigType: _templateValidator.getHttpConfigType.call(void 0, options.template),
+      responseMapper: _templateValidator.getResponseMapper.call(void 0, options.template),
+      // For the ky+setup variant, operations call getKyHttp() instead of the
+      // module-level `http` singleton.
+      httpAccessor: isKyWithSetup ? 'getKyHttp()' : 'http',
+      // In split-file mode, the hooks namespace is generated in a separate file.
+      // Pass splitMode=true so the client.ejs template skips the hooks block.
+      splitMode: !!options.hooksOut,
+      // Template helper functions — defined once here, used in all L2 templates.
+      toOpName,
+      safeOperation,
     });
 
     result += renderedFile;
@@ -73,6 +101,109 @@ var _jsDocs = require('./jsDocs');
   return result;
 } exports.default = generateOperations;
 
+/**
+ * Generates the content of the write-once client setup scaffold file.
+ *
+ * For the `ky` template, renders `baseClientSetup.ejs` which exports a
+ * `createKyConfig()` function imported by the generated `api.ts`.
+ * For other templates (`axios`, `xior`, `fetch`), renders a standalone
+ * interceptor scaffold that is NOT imported by `api.ts`.
+ *
+ * @param relativeApiImport - Relative import path from the setup file back to api.ts
+ * @param relativeSetupImport - Relative import path from api.ts to the setup file
+ *   (only used in the ky scaffold comment to show the correct usage example)
+ */
+ function generateClientSetup(
+  options,
+  relativeApiImport,
+  relativeSetupImport
+) {
+  const setupData = {
+    baseUrl: options.baseUrl,
+    relativeApiImport,
+    relativeSetupImport,
+  };
+
+  try {
+    return _templateEngine.renderFile.call(void 0, 'baseClientSetup.ejs', setupData);
+  } catch (e) {
+    // Template not available for this L1 (e.g. ng1/ng2 don't have a setup template)
+    return '';
+  }
+} exports.generateClientSetup = generateClientSetup;
+
+/**
+ * Generates the reactive hooks file content (for use with --hooksOut).
+ *
+ * The hooks file contains:
+ * - An optional `'use client';` directive (when useClient is set)
+ * - The L2 reactive library imports (useSWR / useQuery etc.)
+ * - A namespace import of the main file: `import * as API from '<relativeMainImport>'`
+ * - One `export const <name> = { queries, mutations, queryKeys }` per tag group,
+ *   referencing HTTP client methods via `API.<name>Client.*`
+ *
+ * This function requires the template engine to already be initialized with the
+ * L2 template files (i.e. `loadAllTemplateFiles` must have been called first).
+ */
+ async function generateHooks(
+  spec,
+  options,
+  relativeMainImport
+) {
+  const operations = _swagger.getOperations.call(void 0, spec);
+  const groups = _utils.groupOperationsByGroupName.call(void 0, operations);
+  const servicePrefix = options.servicePrefix;
+  const baseClientData = {
+    servicePrefix,
+    baseUrl: options.baseUrl,
+    ...options.queryParamsSerialization,
+  };
+
+  // L2 base client contains the reactive library imports (useSWR, useQuery, etc.)
+  let header = '';
+  if (_templateEngine.hasTemplateFile.call(void 0, 'baseClientL2.ejs')) {
+    header += _templateEngine.renderFile.call(void 0, 'baseClientL2.ejs', baseClientData);
+  }
+
+  const clientDirective = options.useClient ? "'use client';\n" : '';
+  let result = clientDirective + _header.FILE_HEADER + header;
+
+  // Import the L1 $httpConfig type directly from its source package so it is
+  // available in the hooks file without having to prefix it with API.
+  const l1HttpTypeImport = getL1HttpTypeImport(options.template);
+  if (l1HttpTypeImport) {
+    result += l1HttpTypeImport + '\n';
+  }
+
+  // Import the main file as a namespace so we can reference API.*Client, API.encodeParams,
+  // and API.DomainTypes (used in hook generics via prefixApiType in the templates).
+  result += `import * as API from '${relativeMainImport}';\n\n`;
+
+  for (const name in groups) {
+    const group = groups[name];
+    const clientData = prepareClient(servicePrefix + name, group, spec.components, options);
+
+    if (!clientData) {
+      continue;
+    }
+
+    const renderedFile = _templateEngine.renderFile.call(void 0, 'hooksClient.ejs', {
+      ...clientData,
+      servicePrefix,
+      httpConfigType: _templateValidator.getHttpConfigType.call(void 0, options.template),
+      responseMapper: _templateValidator.getResponseMapper.call(void 0, options.template),
+      // Template helper functions — defined once here, used in all L2 templates.
+      toOpName,
+      safeOperation,
+      prefixApiType,
+    });
+
+    result += renderedFile;
+  }
+
+  return result;
+} exports.generateHooks = generateHooks;
+
 function prepareClient(
   name,
   operations,
@@ -429,6 +560,96 @@ function getRequestBody(
   return null;
 }
 
+/**
+ * Returns a TypeScript import statement for the L1 HTTP config type so that it
+ * is available in the hooks file by its bare name (e.g. `AxiosRequestConfig`)
+ * without needing an `API.` prefix.
+ *
+ * Returns `null` for `fetch` (uses the built-in `RequestInit` — no import needed)
+ * and for custom/unknown L1 templates.
+ */
+// ─── Template helper functions ─────────────────────────────────────────────
+// Defined here in TypeScript and passed into template data so the EJS files
+// have no local function definitions and no duplication across templates.
+
+/**
+ * Converts an operation name to the PascalCase suffix used in hook/query key
+ * names: strips a leading "get" prefix (case-insensitive), then capitalises.
+ *
+ * @example toOpName('getPetById')      → 'PetById'
+ * @example toOpName('findPetsByStatus') → 'FindPetsByStatus'
+ */
+ function toOpName(name) {
+  const n = name.toLowerCase().startsWith('get') ? name.slice(3) : name;
+  return n.charAt(0).toUpperCase() + n.slice(1);
+} exports.toOpName = toOpName;
+
+/**
+ * Returns a copy of `operation` where any parameter whose name matches
+ * `clientName` is renamed to `_<name>` to avoid TypeScript variable shadowing
+ * inside the hook object literal.
+ */
+ function safeOperation(
+  operation,
+  clientName
+) {
+  const safeParams = operation.parameters.map((p) =>
+    p.name === clientName ? { ...p, name: `_${p.name}` } : p
+  );
+  return { ...operation, parameters: safeParams };
+} exports.safeOperation = safeOperation;
+
+// `API` is included here because it is the namespace we emit ourselves — it
+// must never be prefixed with a second `API.` in the output.
+const PRIMITIVES =
+  /^(API|unknown|string|number|boolean|void|null|undefined|any|never|Date|object|Record|Array|Pick|Omit|Required|Partial|Readonly|NonNullable|ReturnType|InstanceType|Parameters|ConstructorParameters)$/;
+
+/**
+ * Prefixes named (non-primitive) TypeScript type names in a type string with
+ * the `API.` namespace so they resolve to types exported from the main file
+ * when the hooks are in a separate file (split-file / --hooksOut mode).
+ *
+ * Works on any type string structure — bare names, arrays, unions, intersections,
+ * and inline object types (including PascalCase names used as property value types
+ * inside `{ key: SomeType }` shapes).
+ *
+ * @example prefixApiType('Pet')                          → 'API.Pet'
+ * @example prefixApiType('Pet[]')                        → 'API.Pet[]'
+ * @example prefixApiType('Pet | null')                   → 'API.Pet | null'
+ * @example prefixApiType('unknown')                      → 'unknown'
+ * @example prefixApiType('{ id: number }')               → '{ id: number }'
+ * @example prefixApiType('{ profile: MyEnum; }')         → '{ profile: API.MyEnum; }'
+ * @example prefixApiType('API.Pet')                      → 'API.Pet' (API itself is in the exclude list)
+ */
+ function prefixApiType(typeStr) {
+  if (!typeStr) {
+    return typeStr;
+  }
+  // The negative lookbehind `(?<!\.)` skips identifiers that are already part
+  // of a namespace reference (e.g. `API.Pet` — when the regex reaches `Pet` it
+  // is preceded by `.`, so we leave it alone).
+  return typeStr.replace(/(?<!\.)\b([A-Z][A-Za-z0-9_]*)\b/g, (match) =>
+    PRIMITIVES.test(match) ? match : `API.${match}`
+  );
+} exports.prefixApiType = prefixApiType;
+
+function getL1HttpTypeImport(template) {
+  const l1 = _templateValidator.getL1Template.call(void 0, template);
+  switch (l1) {
+    case 'axios':
+      return "import type { AxiosRequestConfig } from 'axios';";
+    case 'xior':
+      return "import type { XiorRequestConfig } from 'xior';";
+    case 'fetch':
+      // RequestInit is a global built-in — no import needed
+      return null;
+    case 'ky':
+      return "import type { Options as KyOptions } from 'ky';";
+    default:
+      return null;
+  }
+}
+
 function upsertFixedHeader(headers, headerName, value) {
   const headerIndex = headers.findIndex(
     (header) => header.originalName.toLowerCase() === headerName.toLowerCase()

package/dist/gen/index.js

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _createNamedExportFrom(obj, localName, importedName) { Object.defineProperty(exports, localName, {enumerable: true, configurable: true, get: () => obj[importedName]}); }
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _createNamedExportFrom(obj, localName, importedName) { Object.defineProperty(exports, localName, {enumerable: true, configurable: true, get: () => obj[importedName]}); } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
 
 var _genOperations = require('./genOperations'); var _genOperations2 = _interopRequireDefault(_genOperations);
 var _genMocks = require('./genMocks'); var _genMocks2 = _interopRequireDefault(_genMocks);
@@ -15,10 +15,28 @@ var _utils = require('../utils');
 ) {
   let fileContents = '';
 
+  // Pre-compute setup file paths so they can be embedded in the generated api.ts
+  // (ky with --clientSetup imports from the setup file at build time).
+  let resolvedSetupPath = null;
+  let relativeSetupImportForMain = null;
+
+  if (options.clientSetup && options.out) {
+    resolvedSetupPath = _utils.prepareOutputFilename.call(void 0, options.clientSetup);
+    const resolvedOutPath = _utils.prepareOutputFilename.call(void 0, options.out);
+    if (resolvedSetupPath && resolvedOutPath) {
+      // From api.ts → setup file (used inside baseClientWithSetup.ejs import)
+      relativeSetupImportForMain = _utils.deriveRelativeImport.call(void 0, resolvedOutPath, resolvedSetupPath);
+    }
+  }
+
   if (options.generationMode === 'schemas') {
     fileContents = _header.FILE_HEADER + _genTypes2.default.call(void 0, spec, options, false);
   } else {
-    fileContents = await _genOperations2.default.call(void 0, spec, options);
+    fileContents = await _genOperations2.default.call(void 0, 
+      spec,
+      options,
+      _nullishCoalesce(relativeSetupImportForMain, () => ( undefined))
+    );
     fileContents += _genTypes2.default.call(void 0, spec, options);
   }
 
@@ -29,12 +47,52 @@ var _utils = require('../utils');
     }
   }
 
+  // Generate the write-once setup scaffold when --clientSetup is set
+  if (options.clientSetup && options.out && resolvedSetupPath) {
+    const resolvedOutPath = _utils.prepareOutputFilename.call(void 0, options.out);
+    if (resolvedOutPath) {
+      // From setup file → api.ts (used inside the scaffold's import of `http`)
+      const relativeApiImport = _utils.deriveRelativeImport.call(void 0, resolvedSetupPath, resolvedOutPath);
+      const setupContents = _genOperations.generateClientSetup.call(void 0, 
+        options,
+        relativeApiImport,
+        _nullishCoalesce(relativeSetupImportForMain, () => ( './api'))
+      );
+      if (setupContents) {
+        const result = await _utils.saveFileIfMissing.call(void 0, 
+          resolvedSetupPath,
+          setupContents,
+          _nullishCoalesce(options.forceSetup, () => ( false))
+        );
+        // result === 'skipped' when the file already exists and --forceSetup was not set
+        void result;
+      }
+    }
+  }
+
+  // Generate the hooks file when --hooksOut is set (L2 templates only)
+  if (options.hooksOut && options.out) {
+    const resolvedHooksPath = _utils.prepareOutputFilename.call(void 0, options.hooksOut);
+    const resolvedOutPath = _utils.prepareOutputFilename.call(void 0, options.out);
+    if (resolvedHooksPath && resolvedOutPath) {
+      const relativeMainImport = _utils.deriveRelativeImport.call(void 0, resolvedHooksPath, resolvedOutPath);
+      const hooksContents = await _genOperations.generateHooks.call(void 0, spec, options, relativeMainImport);
+      await _utils.saveFile.call(void 0, resolvedHooksPath, hooksContents);
+    }
+  }
+
   if (options.mocks && options.testingFramework && options.out) {
     const resolvedMocksPath = _utils.prepareOutputFilename.call(void 0, options.mocks);
     const resolvedOutPath = _utils.prepareOutputFilename.call(void 0, options.out);
+    const resolvedHooksPath = options.hooksOut
+      ? _utils.prepareOutputFilename.call(void 0, options.hooksOut)
+      : null;
     if (resolvedMocksPath && resolvedOutPath) {
       const relativeApiImport = _utils.deriveRelativeImport.call(void 0, resolvedMocksPath, resolvedOutPath);
-      const mockContents = _genMocks2.default.call(void 0, spec, options, relativeApiImport);
+      const relativeHooksImport = resolvedHooksPath
+        ? _utils.deriveRelativeImport.call(void 0, resolvedMocksPath, resolvedHooksPath)
+        : undefined;
+      const mockContents = _genMocks2.default.call(void 0, spec, options, relativeApiImport, relativeHooksImport);
       await _utils.saveFile.call(void 0, resolvedMocksPath, mockContents);
     }
   }