swaggie 2.0.0 → 2.1.0-alpha.4

package/dist/generated/bundledTemplates.js

@@ -3,17 +3,27 @@
 
  const BUNDLED_TEMPLATES = {
   "axios": {
-    "barrel.ejs": "\n/**\n * Serializes a params object into a query string that is compatible with different REST APIs.\n * Implementation from: https://github.com/suhaotian/xior/blob/main/src/utils.ts\n * Kudos to @suhaotian for the original implementation\n */\nfunction encodeParams<T = any>(\n  params: T,\n  parentKey: string | null = null,\n  options?: {\n    allowDots?: boolean;\n    serializeDate?: (value: Date) => string;\n    arrayFormat?: 'indices' | 'repeat' | 'brackets';\n  }\n): string {\n  if (params === undefined || params === null) return '';\n  const encodedParams: string[] = [];\n  const paramsIsArray = Array.isArray(params);\n  const { arrayFormat, allowDots, serializeDate } = options || {};\n\n  const getKey = (key: string) => {\n    if (allowDots && !paramsIsArray) return `.${key}`;\n    if (paramsIsArray) {\n      if (arrayFormat === 'brackets') {\n        return '[]';\n      }\n      if (arrayFormat === 'repeat') {\n        return '';\n      }\n    }\n    return `[${key}]`;\n  };\n\n  for (const key in params) {\n    if (Object.prototype.hasOwnProperty.call(params, key)) {\n      let value = (params as any)[key];\n      if (value !== undefined) {\n        const encodedKey = parentKey ? `${parentKey}${getKey(key)}` : (key as string);\n\n        // biome-ignore lint/suspicious/noGlobalIsNan: <explanation>\n        if (!isNaN(value) && value instanceof Date) {\n          value = serializeDate ? serializeDate(value) : value.toISOString();\n        }\n        if (typeof value === 'object') {\n          // If the value is an object or array, recursively encode its contents\n          const result = encodeParams(value, encodedKey, options);\n          if (result !== '') encodedParams.push(result);\n        } else {\n          // Otherwise, encode the key-value pair\n          encodedParams.push(`${encodeURIComponent(encodedKey)}=${encodeURIComponent(value)}`);\n        }\n      }\n    }\n  }\n\n  return encodedParams.join('&');\n}\n\n",
+    "barrel.ejs": "\n/**\n * Serializes a params object into a query string that is compatible with different REST APIs.\n * Implementation from: https://github.com/suhaotian/xior/blob/main/src/utils.ts\n * Kudos to @suhaotian for the original implementation\n */\nexport function encodeParams<T = any>(\n  params: T,\n  parentKey: string | null = null,\n  options?: {\n    allowDots?: boolean;\n    serializeDate?: (value: Date) => string;\n    arrayFormat?: 'indices' | 'repeat' | 'brackets';\n  }\n): string {\n  if (params === undefined || params === null) return '';\n  const encodedParams: string[] = [];\n  const paramsIsArray = Array.isArray(params);\n  const { arrayFormat, allowDots, serializeDate } = options || {};\n\n  const getKey = (key: string) => {\n    if (allowDots && !paramsIsArray) return `.${key}`;\n    if (paramsIsArray) {\n      if (arrayFormat === 'brackets') {\n        return '[]';\n      }\n      if (arrayFormat === 'repeat') {\n        return '';\n      }\n    }\n    return `[${key}]`;\n  };\n\n  for (const key in params) {\n    if (Object.prototype.hasOwnProperty.call(params, key)) {\n      let value = (params as any)[key];\n      if (value !== undefined) {\n        const encodedKey = parentKey ? `${parentKey}${getKey(key)}` : (key as string);\n\n        // biome-ignore lint/suspicious/noGlobalIsNan: <explanation>\n        if (!isNaN(value) && value instanceof Date) {\n          value = serializeDate ? serializeDate(value) : value.toISOString();\n        }\n        if (typeof value === 'object') {\n          // If the value is an object or array, recursively encode its contents\n          const result = encodeParams(value, encodedKey, options);\n          if (result !== '') encodedParams.push(result);\n        } else {\n          // Otherwise, encode the key-value pair\n          encodedParams.push(`${encodeURIComponent(encodedKey)}=${encodeURIComponent(value)}`);\n        }\n      }\n    }\n  }\n\n  return encodedParams.join('&');\n}\n\n",
     "baseClient.ejs": "import Axios, { type AxiosPromise, type AxiosRequestConfig } from \"axios\";\n\nexport const axios = Axios.create({\n  baseURL: '<%= it.baseUrl || '' %>',\n  paramsSerializer: (params: any) =>\n    encodeParams(params, null, {\n      allowDots: <%= it.allowDots %>,\n      arrayFormat: '<%= it.arrayFormat %>',\n    }),\n});\n\n",
+    "baseClientSetup.ejs": "/**\n * Axios client setup — GENERATED ONCE, will NOT be overwritten on subsequent runs.\n * Re-generate intentionally with: swaggie ... --clientSetup <path> --forceSetup\n *\n * This file is a write-once scaffold for configuring the Axios instance exported\n * from the generated API client. It is NOT imported by api.ts — call\n * `setupApiClient()` once at your application startup.\n *\n * Usage in your app:\n *   import { setupApiClient } from '<%= it.relativeSetupImport %>';\n *   setupApiClient(); // call once before any API requests\n *\n * The setup function can accept any parameters your app needs (e.g. an auth ref):\n *   export function setupApiClient(authRef: AuthRef): () => void { ... }\n */\nimport { axios } from '<%= it.relativeApiImport %>';\n\n/**\n * Configures the shared Axios instance with request/response interceptors.\n * Returns a cleanup function that ejects the interceptors — useful for\n * React effects or other lifecycle-managed contexts.\n */\nexport function setupApiClient(): () => void {\n  const requestInterceptor = axios.interceptors.request.use(\n    (config) => {\n      // TODO: Add request interceptors, e.g. attach an Authorization header:\n      // config.headers.Authorization = `Bearer ${getToken()}`;\n      return config;\n    },\n    (error) => Promise.reject(error)\n  );\n\n  const responseInterceptor = axios.interceptors.response.use(\n    (response) => response,\n    (error) => {\n      // TODO: Add response error handling, e.g. redirect on 401:\n      // if (error.response?.status === 401) { loginWithRedirect(); }\n      return Promise.reject(error);\n    }\n  );\n\n  return () => {\n    axios.interceptors.request.eject(requestInterceptor);\n    axios.interceptors.response.eject(responseInterceptor);\n  };\n}\n",
     "client.ejs": "export const <%= it.camelCaseName %>Client = {\n  <% it.operations.forEach((operation) => { %>\n<%~ include('operation.ejs', operation); %>\n\n<% }); %>\n};\n\n",
     "operation.ejs": "<%~ it.jsDocs %>\n\n  <%= it.name %>(<% it.parameters.forEach((parameter) => { %>\n<%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,\n    <% }); %>\n$config?: AxiosRequestConfig\n  ): AxiosPromise<<%~ it.returnType %>> {\n    const url = `<%= it.url %>`;\n\n    return axios.request<<%~ it.returnType %>>({\n      url: url,\n      method: '<%= it.method %>',\n<% if(it.body) { -%>\n<% if(it.body.contentType === 'urlencoded') { -%>\n      data: new URLSearchParams(<%= it.body.name %> as any),\n<% } else { -%>\n      data: <%= it.body.name %>,\n<% } -%>\n<% } -%>\n<% if(it.query && it.query.length > 0) { -%>\n      params: {\n<% it.query.forEach((parameter) => { -%>\n<% if (it.queryParamObject) { -%>\n        '<%= parameter.originalName %>': <%= it.queryParamObject.name %>?.<%= parameter.name %>,\n<% } else { -%>\n        '<%= parameter.originalName %>': <%= parameter.name %>,\n<% } -%>\n<% }); -%>\n      },\n<% } -%>\n<% if(it.headers && it.headers.length > 0) { -%>\n      headers: {\n<% it.headers.forEach((parameter) => { -%>\n<% if (parameter.value) { -%>\n        '<%= parameter.originalName %>': '<%= parameter.value %>',\n<% } else { -%>\n        '<%= parameter.originalName %>': <%= parameter.name %>,\n<% } -%>\n<% }); -%>\n      },\n<% } -%>\n      ...$config,\n    });\n  },\n"
   },
   "fetch": {
-    "barrel.ejs": "\n/**\n * Serializes a params object into a query string that is compatible with different REST APIs.\n * Implementation from: https://github.com/suhaotian/xior/blob/main/src/utils.ts\n * Kudos to @suhaotian for the original implementation\n */\nfunction encodeParams<T = any>(\n  params: T,\n  parentKey: string | null = null,\n  options?: {\n    allowDots?: boolean;\n    serializeDate?: (value: Date) => string;\n    arrayFormat?: 'indices' | 'repeat' | 'brackets';\n  }\n): string {\n  if (params === undefined || params === null) return '';\n  const encodedParams: string[] = [];\n  const paramsIsArray = Array.isArray(params);\n  const { arrayFormat, allowDots, serializeDate } = options || {};\n\n  const getKey = (key: string) => {\n    if (allowDots && !paramsIsArray) return `.${key}`;\n    if (paramsIsArray) {\n      if (arrayFormat === 'brackets') {\n        return '[]';\n      }\n      if (arrayFormat === 'repeat') {\n        return '';\n      }\n    }\n    return `[${key}]`;\n  };\n\n  for (const key in params) {\n    if (Object.prototype.hasOwnProperty.call(params, key)) {\n      let value = (params as any)[key];\n      if (value !== undefined) {\n        const encodedKey = parentKey ? `${parentKey}${getKey(key)}` : (key as string);\n\n        // biome-ignore lint/suspicious/noGlobalIsNan: <explanation>\n        if (!isNaN(value) && value instanceof Date) {\n          value = serializeDate ? serializeDate(value) : value.toISOString();\n        }\n        if (typeof value === 'object') {\n          // If the value is an object or array, recursively encode its contents\n          const result = encodeParams(value, encodedKey, options);\n          if (result !== '') encodedParams.push(result);\n        } else {\n          // Otherwise, encode the key-value pair\n          encodedParams.push(`${encodeURIComponent(encodedKey)}=${encodeURIComponent(value)}`);\n        }\n      }\n    }\n  }\n\n  return encodedParams.join('&');\n}\n\n",
+    "barrel.ejs": "\n/**\n * Serializes a params object into a query string that is compatible with different REST APIs.\n * Implementation from: https://github.com/suhaotian/xior/blob/main/src/utils.ts\n * Kudos to @suhaotian for the original implementation\n */\nexport function encodeParams<T = any>(\n  params: T,\n  parentKey: string | null = null,\n  options?: {\n    allowDots?: boolean;\n    serializeDate?: (value: Date) => string;\n    arrayFormat?: 'indices' | 'repeat' | 'brackets';\n  }\n): string {\n  if (params === undefined || params === null) return '';\n  const encodedParams: string[] = [];\n  const paramsIsArray = Array.isArray(params);\n  const { arrayFormat, allowDots, serializeDate } = options || {};\n\n  const getKey = (key: string) => {\n    if (allowDots && !paramsIsArray) return `.${key}`;\n    if (paramsIsArray) {\n      if (arrayFormat === 'brackets') {\n        return '[]';\n      }\n      if (arrayFormat === 'repeat') {\n        return '';\n      }\n    }\n    return `[${key}]`;\n  };\n\n  for (const key in params) {\n    if (Object.prototype.hasOwnProperty.call(params, key)) {\n      let value = (params as any)[key];\n      if (value !== undefined) {\n        const encodedKey = parentKey ? `${parentKey}${getKey(key)}` : (key as string);\n\n        // biome-ignore lint/suspicious/noGlobalIsNan: <explanation>\n        if (!isNaN(value) && value instanceof Date) {\n          value = serializeDate ? serializeDate(value) : value.toISOString();\n        }\n        if (typeof value === 'object') {\n          // If the value is an object or array, recursively encode its contents\n          const result = encodeParams(value, encodedKey, options);\n          if (result !== '') encodedParams.push(result);\n        } else {\n          // Otherwise, encode the key-value pair\n          encodedParams.push(`${encodeURIComponent(encodedKey)}=${encodeURIComponent(value)}`);\n        }\n      }\n    }\n  }\n\n  return encodedParams.join('&');\n}\n\n",
     "baseClient.ejs": "export const defaults = {\n  baseUrl: '<%= it.baseUrl || '' %>',\n  paramsSerializer: (params: any) =>\n    encodeParams(params, null, {\n      allowDots: <%= it.allowDots %>,\n      arrayFormat: '<%= it.arrayFormat %>',\n    }),\n};\n\n",
+    "baseClientSetup.ejs": "/**\n * Fetch client setup — GENERATED ONCE, will NOT be overwritten on subsequent runs.\n * Re-generate intentionally with: swaggie ... --clientSetup <path> --forceSetup\n *\n * This file is a write-once scaffold for configuring the fetch-based client\n * exported from the generated API client. It is NOT imported by api.ts — call\n * `setupApiClient()` once at your application startup.\n *\n * Usage in your app:\n *   import { setupApiClient } from '<%= it.relativeSetupImport %>';\n *   setupApiClient(); // call once before any API requests\n *\n * The setup function can accept any parameters your app needs (e.g. an auth ref):\n *   export function setupApiClient(authRef: AuthRef): void { ... }\n */\nimport { defaults } from '<%= it.relativeApiImport %>';\n\n/**\n * Configures the shared fetch client defaults.\n * Override `defaults.fetch` to wrap the native fetch with custom behaviour\n * (auth headers, error handling, logging, etc.).\n */\nexport function setupApiClient(): void {\n  const originalFetch = defaults.fetch ?? globalThis.fetch;\n\n  defaults.fetch = async (input, init) => {\n    // TODO: Add pre-request logic, e.g. attach an Authorization header:\n    // const token = await getToken();\n    // init = { ...init, headers: { ...init?.headers, Authorization: `Bearer ${token}` } };\n\n    const response = await originalFetch(input, init);\n\n    // TODO: Add post-response logic, e.g. handle 401 Unauthorized:\n    // if (response.status === 401) { loginWithRedirect(); }\n\n    return response;\n  };\n}\n",
     "client.ejs": "export const <%= it.camelCaseName %>Client = {\n  <% it.operations.forEach((operation) => { %>\n<%~ include('operation.ejs', operation); %>\n\n<% }); %>\n};\n",
     "operation.ejs": "<%~ it.jsDocs %>\n\n  <%= it.name %>(<% it.parameters.forEach((parameter) => { %>\n<%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,\n    <% }); %>\n$config?: RequestInit\n  ): Promise<<%~ it.returnType %>> {\n    const url = `${defaults.baseUrl}<%= it.url %>?<%\n    if(it.query && it.query.length > 0) { %>${defaults.paramsSerializer({<%\n      it.query.forEach((parameter) => { %>\n<% if (it.queryParamObject) { %>\n'<%= parameter.originalName %>': <%= it.queryParamObject.name %>?.<%= parameter.name %>,\n<% } else { %>\n'<%= parameter.originalName %>': <%= parameter.name %>,\n<% } %>\n      <% }); %>})}<% } %>`;\n\n<% if(it.headers && it.headers.length > 0) { %>\n    const { headers: $configHeaders, ...$configRest } = $config ?? {};\n    const headers = new Headers({\n<% it.headers.forEach((parameter) => { %>\n<% if (parameter.value) { %>\n      '<%= parameter.originalName %>': '<%= parameter.value %>',\n<% } else { %>\n      '<%= parameter.originalName %>': <%= parameter.name %> ?? '',\n<% } %>\n<% }); %>\n    });\n    if ($configHeaders) {\n      new Headers($configHeaders).forEach((value, key) => headers.set(key, value));\n    }\n\n    return fetch(url, {\n      method: '<%= it.method %>',\n<% if(it.body) { %>\n<% if(it.body.contentType === 'json') { %>\n      body: JSON.stringify(<%= it.body.name %>),\n<% } else if(it.body.contentType === 'urlencoded') { %>\n      body: new URLSearchParams(<%= it.body.name %> as any),\n<% } else { %>\n      body: <%= it.body.name %>,\n<% } %>\n<% } %>\n      headers,\n      ...$configRest,\n    })\n<% } else { %>\n    return fetch(url, {\n      method: '<%= it.method %>',\n<% if(it.body) { %>\n<% if(it.body.contentType === 'json') { %>\n      body: JSON.stringify(<%= it.body.name %>),\n<% } else if(it.body.contentType === 'urlencoded') { %>\n      body: new URLSearchParams(<%= it.body.name %> as any),\n<% } else { %>\n      body: <%= it.body.name %>,\n<% } %>\n<% } %>\n      ...$config,\n    })\n<% } %>\n<% if(it.responseContentType === 'binary') { %>\n    .then((response) => response.blob() as Promise<<%~ it.returnType %>>);\n<% } else if(it.responseContentType === 'text') { %>\n    .then((response) => response.text() as Promise<<%~ it.returnType %>>);\n<% } else { %>\n    .then((response) => response.json() as Promise<<%~ it.returnType %>>);\n<% } %>\n  },\n"
   },
+  "ky": {
+    "barrel.ejs": "\n/**\n * Serializes a params object into a query string that is compatible with different REST APIs.\n * Implementation from: https://github.com/suhaotian/xior/blob/main/src/utils.ts\n * Kudos to @suhaotian for the original implementation\n */\nexport function encodeParams<T = any>(\n  params: T,\n  parentKey: string | null = null,\n  options?: {\n    allowDots?: boolean;\n    serializeDate?: (value: Date) => string;\n    arrayFormat?: 'indices' | 'repeat' | 'brackets';\n  }\n): string {\n  if (params === undefined || params === null) return '';\n  const encodedParams: string[] = [];\n  const paramsIsArray = Array.isArray(params);\n  const { arrayFormat, allowDots, serializeDate } = options || {};\n\n  const getKey = (key: string) => {\n    if (allowDots && !paramsIsArray) return `.${key}`;\n    if (paramsIsArray) {\n      if (arrayFormat === 'brackets') {\n        return '[]';\n      }\n      if (arrayFormat === 'repeat') {\n        return '';\n      }\n    }\n    return `[${key}]`;\n  };\n\n  for (const key in params) {\n    if (Object.prototype.hasOwnProperty.call(params, key)) {\n      let value = (params as any)[key];\n      if (value !== undefined) {\n        const encodedKey = parentKey ? `${parentKey}${getKey(key)}` : (key as string);\n\n        // biome-ignore lint/suspicious/noGlobalIsNan: <explanation>\n        if (!isNaN(value) && value instanceof Date) {\n          value = serializeDate ? serializeDate(value) : value.toISOString();\n        }\n        if (typeof value === 'object') {\n          // If the value is an object or array, recursively encode its contents\n          const result = encodeParams(value, encodedKey, options);\n          if (result !== '') encodedParams.push(result);\n        } else {\n          // Otherwise, encode the key-value pair\n          encodedParams.push(`${encodeURIComponent(encodedKey)}=${encodeURIComponent(value)}`);\n        }\n      }\n    }\n  }\n\n  return encodedParams.join('&');\n}\n",
+    "baseClient.ejs": "import ky, { type Options as KyOptions } from 'ky';\n\nexport const http = ky.create({\n  prefix: '<%= it.baseUrl || '' %>',\n});\n",
+    "baseClientSetup.ejs": "/**\n * Ky client setup — GENERATED ONCE, will NOT be overwritten on subsequent runs.\n * Re-generate intentionally with: swaggie ... --clientSetup <path> --forceSetup\n *\n * This file configures the ky HTTP client used by the generated API client.\n * Because ky requires hooks to be provided at creation time, this file exports\n * a `createKyConfig()` function that is called by `initKyHttp()` in api.ts.\n *\n * Usage in your app:\n *   import { initKyHttp } from '<%= it.relativeApiImport %>';\n *   initKyHttp(); // call once at startup, e.g. in a React provider or main.ts\n *\n * If you need to pass runtime values into hooks (e.g. an auth token getter),\n * store them in module-level variables and expose a configuration function:\n *\n *   let _getToken: () => Promise<string> = () => Promise.resolve('');\n *\n *   export function configureKyClient(opts: { getToken: () => Promise<string> }) {\n *     _getToken = opts.getToken;\n *   }\n *\n * Then call configureKyClient(...) before initKyHttp() at startup.\n */\nimport type { Options as KyOptions } from 'ky';\n\nexport type KySetupConfig = Pick<KyOptions, 'hooks' | 'prefix' | 'retry' | 'timeout'>;\n\n/**\n * Returns the ky configuration used to create the HTTP client instance.\n * Called once by `initKyHttp()` in the generated api.ts.\n *\n * Add your hooks here — beforeRequest for auth/headers, afterResponse for\n * error handling and monitoring, beforeError for error enrichment.\n */\nexport function createKyConfig(): KySetupConfig {\n  return {\n    prefix: '<%= it.baseUrl || '' %>',\n    hooks: {\n      beforeRequest: [\n        // TODO: Add request hooks, e.g. attach an Authorization header:\n        // async ({ request }) => {\n        //   const token = await _getToken();\n        //   if (token) request.headers.set('Authorization', `Bearer ${token}`);\n        // },\n      ],\n      afterResponse: [\n        // TODO: Add response hooks, e.g. handle 401 Unauthorized:\n        // async ({ response }) => {\n        //   if (response.status === 401) {\n        //     await loginWithRedirect({ returnTo: window.location.toString() });\n        //   }\n        // },\n      ],\n      beforeError: [\n        // TODO: Add error hooks, e.g. enrich errors with request context:\n        // ({ error }) => error,\n      ],\n    },\n  };\n}\n",
+    "baseClientWithSetup.ejs": "import ky, { type KyInstance, type Options as KyOptions } from 'ky';\nimport { createKyConfig } from '<%= it.relativeSetupImport %>';\n\nlet _http: KyInstance | null = null;\n\n/**\n * Initialises the ky HTTP client using the configuration returned by\n * `createKyConfig()` from your setup file.\n *\n * Call this once at application startup — for example inside a React provider\n * or your app's entry point — before any API calls are made.\n *\n * Re-calling this function replaces the existing instance. ky instances are\n * immutable, so hook changes require re-initialisation.\n */\nexport function initKyHttp(): void {\n  _http = ky.create(createKyConfig());\n}\n\n/**\n * Returns the initialised ky instance. Throws if called before `initKyHttp()`.\n *\n * This guard prevents accidental use of the client before it has been\n * configured with hooks (auth, error handling, etc.).\n */\nexport function getKyHttp(): KyInstance {\n  if (!_http) {\n    throw new Error(\n      '[Swaggie] ky client is not initialised. ' +\n        'Call initKyHttp() at application startup before making any API requests.'\n    );\n  }\n  return _http;\n}\n",
+    "client.ejs": "export const <%= it.camelCaseName %>Client = {\n  <% it.operations.forEach((operation) => { %>\n<%~ include('operation.ejs', Object.assign({ httpAccessor: it.httpAccessor }, operation)); %>\n\n<% }); %>\n};\n",
+    "operation.ejs": "<%~ it.jsDocs %>\n\n  <%= it.name %>(<% it.parameters.forEach((parameter) => { %>\n<%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,\n    <% }); %>\n$config?: KyOptions\n  ): Promise<<%~ it.returnType %>> {\n    const url = `<%= it.url.replace(/^\\//, '') %>`;\n\n    return <%= it.httpAccessor %>.<%= it.method.toLowerCase() %>(url, {\n<% if(it.body) { -%>\n<% if(it.body.contentType === 'json') { -%>\n      json: <%= it.body.name %>,\n<% } else if(it.body.contentType === 'urlencoded') { -%>\n      body: new URLSearchParams(<%= it.body.name %> as any),\n<% } else { -%>\n      body: <%= it.body.name %>,\n<% } -%>\n<% } -%>\n<% if(it.query && it.query.length > 0) { -%>\n      searchParams: {\n<% it.query.forEach((parameter) => { -%>\n<% if (it.queryParamObject) { -%>\n        '<%= parameter.originalName %>': <%= it.queryParamObject.name %>?.<%= parameter.name %> as any,\n<% } else { -%>\n        '<%= parameter.originalName %>': <%= parameter.name %> as any,\n<% } -%>\n<% }); -%>\n      },\n<% } -%>\n<% if(it.headers && it.headers.length > 0) { -%>\n      headers: {\n<% it.headers.forEach((parameter) => { -%>\n<% if (parameter.value) { -%>\n        '<%= parameter.originalName %>': '<%= parameter.value %>',\n<% } else { -%>\n        '<%= parameter.originalName %>': <%= parameter.name %>,\n<% } -%>\n<% }); -%>\n      },\n<% } -%>\n      ...$config,\n<% if(it.responseContentType === 'binary') { -%>\n    }).blob() as Promise<<%~ it.returnType %>>;\n<% } else if(it.responseContentType === 'text') { -%>\n    }).text() as Promise<<%~ it.returnType %>>;\n<% } else { -%>\n    }).json<<%~ it.returnType %>>();\n<% } -%>\n  },\n"
+  },
   "ng1": {
     "barrel.ejs": "export class ApiServices {\n  public static bootstrap(moduleName: string, baseUrl: string) {\n    angular\n      .module(moduleName)\n      .constant('Api<%= it.servicePrefix -%>BaseUrl', baseUrl)\n<% it.clients.forEach((client) => { %>\n      .service('<%= client.fileName %>Service', <%= client.fileName %>Service)\n<% }); %>;\n  }\n}\n\nfunction serializeQueryParam(obj: any, property: string): string {\n  if (obj === null || obj === undefined || obj === '') {\n    return '';\n  } else if (obj instanceof Date) {\n    return property + '=' + encodeURIComponent(obj.toJSON());\n  } else if (Array.isArray(obj)) {\n    return Object.values(obj)\n      .map(value => `${property}[]=${value}`)\n      .join('&');\n  } else if (typeof obj !== 'object') {\n    return property + '=' + encodeURIComponent(obj);\n  } else if (typeof obj === 'object') {\n    return Object.keys(obj)\n      .filter(key => !!serializeQueryParam(obj[key], property + '.' + key))\n      .reduce(\n        (a: any, b) =>\n          a.push(serializeQueryParam(obj[b], property + '.' + b)) && a,\n        []\n      )\n      .join('&');\n  } else {\n    return '';\n  }\n}\n",
     "baseClient.ejs": "import type { IHttpService, IRequestShortcutConfig, IPromise } from 'angular';\n\nabstract class BaseService {\n  constructor(protected readonly $http: IHttpService, public baseUrl: string) { }\n\n  protected $get<T>(\n    url: string,\n    config?: IRequestShortcutConfig\n  ): IPromise<T> {\n    return this.$http.get(this.baseUrl + url, config).then((response: any) => {\n      return this.processSingle<T>(response);\n    });\n  }\n\n  protected $getAll<T>(\n    url: string,\n    config?: IRequestShortcutConfig\n  ): IPromise<T[]> {\n    return this.$http.get(this.baseUrl + url, config).then((response: any) => {\n      return this.processMany<T>(response);\n    });\n  }\n\n  protected $delete<T>(\n    url: string,\n    config?: IRequestShortcutConfig\n  ): IPromise<any> {\n    return this.$http\n      .delete(this.baseUrl + url, config)\n      .then((response: any) => {\n        return this.processSingle<T>(response);\n      });\n  }\n\n  protected $head<T>(\n    url: string,\n    config?: IRequestShortcutConfig\n  ): IPromise<any> {\n    return this.$http.head(this.baseUrl + url, config).then((response: any) => {\n      return this.processSingle<T>(response);\n    });\n  }\n\n  protected $jsonp<T>(\n    url: string,\n    config?: IRequestShortcutConfig\n  ): IPromise<any> {\n    return this.$http\n      .jsonp(this.baseUrl + url, config)\n      .then((response: any) => {\n        return this.processSingle<T>(response);\n      });\n  }\n\n  protected $post<T>(\n    url: string,\n    data: any,\n    config?: IRequestShortcutConfig\n  ): IPromise<any> {\n    return this.$http\n      .post(this.baseUrl + url, data, config)\n      .then((response: any) => {\n        return this.processSingle<T>(response);\n      });\n  }\n\n  protected $put<T>(\n    url: string,\n    data: any,\n    config?: IRequestShortcutConfig\n  ): IPromise<any> {\n    return this.$http\n      .put(this.baseUrl + url, data, config)\n      .then((response: any) => {\n        return this.processSingle<T>(response);\n      });\n  }\n\n  protected $patch<T>(\n    url: string,\n    data: any,\n    config?: IRequestShortcutConfig\n  ): IPromise<any> {\n    return this.$http\n      .patch(this.baseUrl + url, data, config)\n      .then((response: any) => {\n        return this.processSingle<T>(response);\n      });\n  }\n\n  protected processSingle<T>(response: any): T {\n    var data = response.data;\n    var status = response.status;\n\n    if (status >= 200 && status <= 299) {\n      return data;\n    } else {\n      throw 'error_no_callback_for_the_received_http_status';\n    }\n  }\n\n  protected processMany<T>(response: any): T[] {\n    var data = response.data;\n    var status = response.status;\n\n    if (status >= 200 && status <= 299) {\n      return data;\n    } else {\n      throw 'error_no_callback_for_the_received_http_status';\n    }\n  }\n}\n\n",
@@ -21,26 +31,29 @@
     "operation.ejs": "<%~ it.jsDocs %>\n\n  <%= it.name %>(<% it.parameters.forEach((parameter) => { %>\n<%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,\n    <% }); %>\n    config?: IRequestShortcutConfig\n  ): IPromise<<%~ it.returnType %>> {\n    let url = `<%= it.url %>?`;\n<% if(it.query && it.query.length > 0) { %>\n  <% it.query.forEach((parameter) => { %>\n  if (<%= it.queryParamObject ? `${it.queryParamObject.name}?.${parameter.name}` : parameter.name %> !== undefined) {\n  <% if(!!parameter.original && parameter.original.type === 'array') { %>\n    <%= it.queryParamObject ? `${it.queryParamObject.name}.${parameter.name}` : parameter.name %>.forEach(item => { url += serializeQueryParam(item, '<%= parameter.originalName %>') + \"&\"; });\n  <% } else {%>\n    url += serializeQueryParam(<%= it.queryParamObject ? `${it.queryParamObject.name}.${parameter.name}` : parameter.name %>, '<%= parameter.originalName %>') + \"&\";\n  <% } %>\n  }\n  <% }); %>\n<% } %>\n\n<% if(it.headers && it.headers.length > 0) { it.headers.forEach((parameter) => { %>\n<% if (parameter.value) { %>\n    config = { ...config, headers: { ...config?.headers, '<%= parameter.originalName %>': '<%= parameter.value %>' } };\n<% } else { %>\n    if (<%= parameter.name %>) {\n      config = { ...config, headers: { ...config?.headers, '<%= parameter.originalName %>': <%= parameter.name %> } };\n    }\n<% } %><% }); } %>\n    return this.$<%= it.method.toLowerCase() %>(\n      url,\n<% if(['POST', 'PUT', 'PATCH'].includes(it.method)) { %>\n  <% if(it.body) { %>\n    <%= it.body.contentType === 'urlencoded' ? 'new URLSearchParams(' + it.body.name + ' as any)' : it.body.name %>,\n  <% } else { %>\n    null,\n  <% } %>\n<% } %>\n    config\n    );\n  }\n"
   },
   "ng2": {
-    "barrel.ejs": "\n/**\n * Serializes a params object into a query string that is compatible with different REST APIs.\n * Implementation from: https://github.com/suhaotian/xior/blob/main/src/utils.ts\n * Kudos to @suhaotian for the original implementation\n */\nfunction encodeParams<T = any>(\n  params: T,\n  parentKey: string | null = null,\n  options?: {\n    allowDots?: boolean;\n    serializeDate?: (value: Date) => string;\n    arrayFormat?: 'indices' | 'repeat' | 'brackets';\n  }\n): string {\n  if (params === undefined || params === null) return '';\n  const encodedParams: string[] = [];\n  const paramsIsArray = Array.isArray(params);\n  const { arrayFormat, allowDots, serializeDate } = options || {};\n\n  const getKey = (key: string) => {\n    if (allowDots && !paramsIsArray) return `.${key}`;\n    if (paramsIsArray) {\n      if (arrayFormat === 'brackets') {\n        return '[]';\n      }\n      if (arrayFormat === 'repeat') {\n        return '';\n      }\n    }\n    return `[${key}]`;\n  };\n\n  for (const key in params) {\n    if (Object.prototype.hasOwnProperty.call(params, key)) {\n      let value = (params as any)[key];\n      if (value !== undefined) {\n        const encodedKey = parentKey ? `${parentKey}${getKey(key)}` : (key as string);\n\n        // biome-ignore lint/suspicious/noGlobalIsNan: <explanation>\n        if (!isNaN(value) && value instanceof Date) {\n          value = serializeDate ? serializeDate(value) : value.toISOString();\n        }\n        if (typeof value === 'object') {\n          // If the value is an object or array, recursively encode its contents\n          const result = encodeParams(value, encodedKey, options);\n          if (result !== '') encodedParams.push(result);\n        } else {\n          // Otherwise, encode the key-value pair\n          encodedParams.push(`${encodeURIComponent(encodedKey)}=${encodeURIComponent(value)}`);\n        }\n      }\n    }\n  }\n\n  return encodedParams.join('&');\n}\n\n",
+    "barrel.ejs": "\n/**\n * Serializes a params object into a query string that is compatible with different REST APIs.\n * Implementation from: https://github.com/suhaotian/xior/blob/main/src/utils.ts\n * Kudos to @suhaotian for the original implementation\n */\nexport function encodeParams<T = any>(\n  params: T,\n  parentKey: string | null = null,\n  options?: {\n    allowDots?: boolean;\n    serializeDate?: (value: Date) => string;\n    arrayFormat?: 'indices' | 'repeat' | 'brackets';\n  }\n): string {\n  if (params === undefined || params === null) return '';\n  const encodedParams: string[] = [];\n  const paramsIsArray = Array.isArray(params);\n  const { arrayFormat, allowDots, serializeDate } = options || {};\n\n  const getKey = (key: string) => {\n    if (allowDots && !paramsIsArray) return `.${key}`;\n    if (paramsIsArray) {\n      if (arrayFormat === 'brackets') {\n        return '[]';\n      }\n      if (arrayFormat === 'repeat') {\n        return '';\n      }\n    }\n    return `[${key}]`;\n  };\n\n  for (const key in params) {\n    if (Object.prototype.hasOwnProperty.call(params, key)) {\n      let value = (params as any)[key];\n      if (value !== undefined) {\n        const encodedKey = parentKey ? `${parentKey}${getKey(key)}` : (key as string);\n\n        // biome-ignore lint/suspicious/noGlobalIsNan: <explanation>\n        if (!isNaN(value) && value instanceof Date) {\n          value = serializeDate ? serializeDate(value) : value.toISOString();\n        }\n        if (typeof value === 'object') {\n          // If the value is an object or array, recursively encode its contents\n          const result = encodeParams(value, encodedKey, options);\n          if (result !== '') encodedParams.push(result);\n        } else {\n          // Otherwise, encode the key-value pair\n          encodedParams.push(`${encodeURIComponent(encodedKey)}=${encodeURIComponent(value)}`);\n        }\n      }\n    }\n  }\n\n  return encodedParams.join('&');\n}\n\n",
     "baseClient.ejs": "import type { Observable } from \"rxjs\";\nimport { Injectable, InjectionToken, inject } from \"@angular/core\";\nimport { HttpClient, type HttpContext, type HttpHeaders, type HttpParams } from \"@angular/common/http\";\n\nexport const <%= (it.servicePrefix || 'API').toUpperCase() -%>_BASE_URL = new InjectionToken<string>(\"<%= (it.servicePrefix || 'API').toUpperCase() -%>_BASE_URL\");\n\nexport interface HttpConfig {\n  headers?: HttpHeaders | Record<string, string | string[]>;\n  context?: HttpContext;\n  params?: HttpParams | Record<string, string | number | boolean | (string | number | boolean)[]>;\n  reportProgress?: boolean;\n  withCredentials?: boolean;\n  transferCache?: boolean | { includeHeaders?: string[] };\n}\n\nfunction paramsSerializer(params: any) {\n  return encodeParams(params, null, {\n    allowDots: <%= it.allowDots %>,\n    arrayFormat: '<%= it.arrayFormat %>',\n  });\n}\n\n",
     "client.ejs": "@Injectable({\n  providedIn: 'root'\n})\nexport class <%= it.clientName.charAt(0).toUpperCase() + it.clientName.slice(1) -%>Service {\n  private http = inject(HttpClient);\n  private baseUrl = inject(<%= (it.servicePrefix || 'API').toUpperCase() -%>_BASE_URL, { optional: true }) ?? '';\n\n  <% it.operations.forEach((operation) => { %>\n<%~ include('operation.ejs', operation); %>\n\n<% }); %>\n}\n\n",
     "operation.ejs": "<%~ it.jsDocs %>\n\n  <%= it.name %>(\n    <% it.parameters.forEach((parameter) => { %>\n<%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,\n    <% }); %>\nconfig?: HttpConfig\n  ): Observable<<%~ it.returnType %>> {\n<% if(it.query && it.query.length > 0) { -%>\n    const params = paramsSerializer({\n<% it.query.forEach((parameter) => { -%>\n<% if (it.queryParamObject) { -%>\n      '<%= parameter.originalName %>': <%= it.queryParamObject.name %>?.<%= parameter.name %>,\n<% } else { -%>\n      '<%= parameter.originalName %>': <%= parameter.name %>,\n<% } -%>\n<% }); -%>\n    });\n    const url = `<%= it.url %>${params ? '?' + params : ''}`;\n<% } else { -%>\n    const url = `<%= it.url %>`;\n<% } -%>\n<% if(it.headers && it.headers.length > 0) { it.headers.forEach((parameter) => { -%>\n<% if (parameter.value) { -%>\n    config = { ...config, headers: { ...config?.headers, '<%= parameter.originalName %>': '<%= parameter.value %>' } };\n<% } else { -%>\n    if (<%= parameter.name %>) {\n      config = { ...config, headers: { ...config?.headers, '<%= parameter.originalName %>': <%= parameter.name %> } };\n    }\n<% } -%>\n<% }); } -%>\n<% if(it.method === 'GET') { -%>\n    return this.http.get<<%~ it.returnType %>>(this.baseUrl + url, config);\n<% } else if(it.method === 'DELETE') { -%>\n    return this.http.delete<<%~ it.returnType %>>(this.baseUrl + url, config);\n<% } else if(['POST', 'PUT', 'PATCH'].includes(it.method)) {\n  const bodyArg = it.body\n    ? (it.body.contentType === 'urlencoded' ? 'new URLSearchParams(' + it.body.name + ' as any)' : it.body.name)\n    : 'null';\n-%>\n    return this.http.<%= it.method.toLowerCase() %><%~ '<' + it.returnType + '>' %>(this.baseUrl + url, <%~ bodyArg %>, config);\n<% } %>\n  }\n"
   },
   "swr": {
     "baseClient.ejs": "import useSWR, { type SWRConfiguration, type Key } from 'swr';\nimport useSWRMutation, { type SWRMutationConfiguration } from 'swr/mutation';\n\ninterface SwrConfig extends SWRConfiguration {\n  /* Custom key for SWR. You don't have to worry about this as by default it's the URL. You can use standard SWR Key here if you need more flexibility. */\n  key?: Key;\n}\n",
-    "client.ejs": "export const <%= it.camelCaseName -%>Client = {\n  <% it.operations.forEach((operation) => { %>\n<%~ include('operation.ejs', operation); %>\n\n  <% }); %>\n};\n\n<%\nvar getOperations = it.operations.filter((o) => o.method === 'GET');\nvar mutationOperations = it.operations.filter((o) => o.method !== 'GET');\n\nfunction toOpName(name) {\n  var n = name.toLowerCase().startsWith('get') ? name.substring(3) : name;\n  return n.charAt(0).toUpperCase() + n.slice(1);\n}\n\nfunction safeOperation(operation, clientName) {\n  var safeParams = operation.parameters.map(function(p) {\n    return p.name === clientName ? Object.assign({}, p, { name: '_' + p.name }) : p;\n  });\n  return Object.assign({}, operation, { parameters: safeParams });\n}\n%>\n\nexport const <%= it.camelCaseName %> = {\n  queries: {\n<% getOperations.forEach((operation) => {\n  var opName = toOpName(operation.name);\n  var swrOperation = Object.assign({\n    swrOpName: 'use' + opName,\n    clientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n  }, safeOperation(operation, it.camelCaseName));\n%>\n<%~ include('swrOperation.ejs', swrOperation); %>\n\n<% }); %>\n  },\n\n  mutations: {\n<% mutationOperations.forEach((operation) => {\n  var opName = operation.name.charAt(0).toUpperCase() + operation.name.slice(1);\n  var swrMutationOperation = Object.assign({\n    mutOpName: 'use' + opName,\n    clientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n  }, safeOperation(operation, it.camelCaseName));\n%>\n<%~ include('swrMutationOperation.ejs', swrMutationOperation); %>\n\n<% }); %>\n  },\n\n  queryKeys: {\n<% getOperations.forEach((operation) => {\n  var opName = toOpName(operation.name);\n  var keyName = opName.charAt(0).toLowerCase() + opName.slice(1);\n  var safeOp = safeOperation(operation, it.camelCaseName);\n%>\n    <%= keyName %>: (<% safeOp.parameters.forEach((parameter) => { %><%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>, <% }); %>) => `<%= operation.url %><% if(safeOp.query && safeOp.query.length > 0) { %>?${encodeParams({<% safeOp.query.forEach((parameter) => { %>'<%= parameter.originalName %>': <%= safeOp.queryParamObject ? `${safeOp.queryParamObject.name}?.${parameter.name}` : parameter.name %>, <% }); %>})}<% } %>`,\n<% }); %>\n  },\n};\n",
-    "swrMutationOperation.ejs": "<%\nvar hasParams = it.parameters.length > 0;\n\nvar variablesType;\nif (!hasParams) {\n  variablesType = 'void';\n} else {\n  var parts = it.parameters.map(function(p) {\n    return p.name + (p.skippable ? '?' : '') + ': ' + p.type + (p.optional ? ' | null' : '');\n  });\n  variablesType = '{ ' + parts.join('; ') + ' }';\n}\n\nvar callArgs = it.parameters.map(function(p) { return 'arg.' + p.name; });\n\n// Stable SWR key: replace all ${...} path expressions with *\nvar swrKey = it.url.replace(/\\$\\{(?:[^{}]|\\{[^{}]*\\})*\\}/g, '*');\n\nvar docs = it.jsDocs ? it.jsDocs.replace(/^/gm, '  ') + '\\n' : '';\n%>\n<%~ docs %>\n    <%= it.mutOpName %>(\n      $config?: SWRMutationConfiguration<<%~ it.returnType %>, Error, string, <%~ variablesType %>>,\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      return useSWRMutation<<%~ it.returnType %>, Error, string, <%~ variablesType %>>(\n        '<%= swrKey %>',\n        (_key: string, { arg }<%= hasParams ? ': { arg: ' + variablesType + ' }' : '' %>) =>\n          <%= it.clientName %>Client.<%= it.name %>(<%= callArgs.join(', ') %><%= callArgs.length > 0 ? ', ' : '' %>$httpConfig).then((resp) => resp.data),\n        $config\n      );\n    },\n",
-    "swrOperation.ejs": "<% var docs = it.jsDocs ? it.jsDocs.replace(/^/gm, '  ') + '\\n' : ''; %>\n<%~ docs %>\n    <%= it.swrOpName %>(\n<% it.parameters.forEach((parameter) => { %>      <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>,\n<% }); %>      $config?: Omit<SwrConfig, 'key'> & { key?: Key },\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      const { key, ...config } = $config || {};\n      const cacheUrl = key ?? <%= it.clientName %>.queryKeys.<%= it.swrOpName.charAt(3).toLowerCase() + it.swrOpName.slice(4) %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>);\n\n      const { data, error, isLoading, mutate } = useSWR<<%~ it.returnType %>>(\n        cacheUrl,\n        () => <%= it.clientName %>Client.<%= it.name %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>$httpConfig).then((resp) => resp.data),\n        config\n      );\n\n      return { data, isLoading, error, mutate };\n    },\n"
+    "client.ejs": "export const <%= it.camelCaseName -%>Client = {\n  <% it.operations.forEach((operation) => { %>\n<%~ include('operation.ejs', operation); %>\n\n  <% }); %>\n};\n\n<% if (!it.splitMode) { %>\n<%\nvar getOperations = it.operations.filter((o) => o.method === 'GET');\nvar mutationOperations = it.operations.filter((o) => o.method !== 'GET');\n%>\n\nexport const <%= it.camelCaseName %> = {\n  queries: {\n<% getOperations.forEach((operation) => {\n  var opName = it.toOpName(operation.name);\n  var swrOperation = Object.assign({\n    swrOpName: 'use' + opName,\n    clientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n  }, it.safeOperation(operation, it.camelCaseName));\n%>\n<%~ include('swrOperation.ejs', swrOperation); %>\n\n<% }); %>\n  },\n\n  mutations: {\n<% mutationOperations.forEach((operation) => {\n  var opName = operation.name.charAt(0).toUpperCase() + operation.name.slice(1);\n  var swrMutationOperation = Object.assign({\n    mutOpName: 'use' + opName,\n    clientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n  }, it.safeOperation(operation, it.camelCaseName));\n%>\n<%~ include('swrMutationOperation.ejs', swrMutationOperation); %>\n\n<% }); %>\n  },\n\n  queryKeys: {\n<% getOperations.forEach((operation) => {\n  var opName = it.toOpName(operation.name);\n  var keyName = opName.charAt(0).toLowerCase() + opName.slice(1);\n  var safeOp = it.safeOperation(operation, it.camelCaseName);\n%>\n    <%= keyName %>: (<% safeOp.parameters.forEach((parameter) => { %><%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>, <% }); %>) => `<%= operation.url %><% if(safeOp.query && safeOp.query.length > 0) { %>?${encodeParams({<% safeOp.query.forEach((parameter) => { %>'<%= parameter.originalName %>': <%= safeOp.queryParamObject ? `${safeOp.queryParamObject.name}?.${parameter.name}` : parameter.name %>, <% }); %>})}<% } %>`,\n<% }); %>\n  },\n};\n<% } /* end !splitMode */ %>\n",
+    "hooksClient.ejs": "<%\nvar getOperations = it.operations.filter((o) => o.method === 'GET');\nvar mutationOperations = it.operations.filter((o) => o.method !== 'GET');\nvar httpClientPrefix = 'API.' + it.camelCaseName;\n%>\n\nexport const <%= it.camelCaseName %> = {\n  queries: {\n<% getOperations.forEach((operation) => {\n  var opName = it.toOpName(operation.name);\n  var safe = it.safeOperation(operation, it.camelCaseName);\n  var swrOperation = Object.assign({}, safe, {\n    swrOpName: 'use' + opName,\n    clientName: it.camelCaseName,\n    httpClientName: httpClientPrefix,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    returnType: it.prefixApiType(safe.returnType),\n    parameters: safe.parameters.map(function(p) {\n      return Object.assign({}, p, { type: it.prefixApiType(p.type) });\n    }),\n  });\n%>\n<%~ include('swrOperation.ejs', swrOperation); %>\n\n<% }); %>\n  },\n\n  mutations: {\n<% mutationOperations.forEach((operation) => {\n  var opName = operation.name.charAt(0).toUpperCase() + operation.name.slice(1);\n  var safe = it.safeOperation(operation, it.camelCaseName);\n  var swrMutationOperation = Object.assign({}, safe, {\n    mutOpName: 'use' + opName,\n    clientName: it.camelCaseName,\n    httpClientName: httpClientPrefix,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    returnType: it.prefixApiType(safe.returnType),\n    parameters: safe.parameters.map(function(p) {\n      return Object.assign({}, p, { type: it.prefixApiType(p.type) });\n    }),\n  });\n%>\n<%~ include('swrMutationOperation.ejs', swrMutationOperation); %>\n\n<% }); %>\n  },\n\n  queryKeys: {\n<% getOperations.forEach((operation) => {\n  var opName = it.toOpName(operation.name);\n  var keyName = opName.charAt(0).toLowerCase() + opName.slice(1);\n  var safeOp = it.safeOperation(operation, it.camelCaseName);\n  var prefixedParams = safeOp.parameters.map(function(p) {\n    return Object.assign({}, p, { type: it.prefixApiType(p.type) });\n  });\n%>\n    <%= keyName %>: (<% prefixedParams.forEach((parameter) => { %><%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>, <% }); %>) => `<%= operation.url %><% if(safeOp.query && safeOp.query.length > 0) { %>?${API.encodeParams({<% safeOp.query.forEach((parameter) => { %>'<%= parameter.originalName %>': <%= safeOp.queryParamObject ? `${safeOp.queryParamObject.name}?.${parameter.name}` : parameter.name %>, <% }); %>})}<% } %>`,\n<% }); %>\n  },\n};\n",
+    "swrMutationOperation.ejs": "<%\nvar hasParams = it.parameters.length > 0;\n\nvar variablesType;\nif (!hasParams) {\n  variablesType = 'void';\n} else {\n  var parts = it.parameters.map(function(p) {\n    return p.name + (p.skippable ? '?' : '') + ': ' + p.type + (p.optional ? ' | null' : '');\n  });\n  variablesType = '{ ' + parts.join('; ') + ' }';\n}\n\nvar callArgs = it.parameters.map(function(p) { return 'arg.' + p.name; });\n\n// Stable SWR key: replace all ${...} path expressions with *\nvar swrKey = it.url.replace(/\\$\\{(?:[^{}]|\\{[^{}]*\\})*\\}/g, '*');\n\nvar docs = it.jsDocs ? it.jsDocs.replace(/^/gm, '  ') + '\\n' : '';\nvar httpClientName = it.httpClientName || it.clientName;\n%>\n<%~ docs %>\n    <%= it.mutOpName %>(\n      $config?: SWRMutationConfiguration<<%~ it.returnType %>, Error, string, <%~ variablesType %>>,\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      return useSWRMutation<<%~ it.returnType %>, Error, string, <%~ variablesType %>>(\n        '<%= swrKey %>',\n        (_key: string, { arg }<%= hasParams ? ': { arg: ' + variablesType + ' }' : '' %>) =>\n          <%= httpClientName %>Client.<%= it.name %>(<%= callArgs.join(', ') %><%= callArgs.length > 0 ? ', ' : '' %>$httpConfig)<%= it.responseMapper %>,\n        $config\n      );\n    },\n",
+    "swrOperation.ejs": "<% var docs = it.jsDocs ? it.jsDocs.replace(/^/gm, '  ') + '\\n' : ''; %>\n<% var httpClientName = it.httpClientName || it.clientName; %>\n<%~ docs %>\n    <%= it.swrOpName %>(\n<% it.parameters.forEach((parameter) => { %>      <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>,\n<% }); %>      $config?: Omit<SwrConfig, 'key'> & { key?: Key },\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      const { key, ...config } = $config || {};\n      const cacheUrl = key ?? <%= it.clientName %>.queryKeys.<%= it.swrOpName.charAt(3).toLowerCase() + it.swrOpName.slice(4) %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>);\n\n      const { data, error, isLoading, mutate } = useSWR<<%~ it.returnType %>>(\n        cacheUrl,\n        () => <%= httpClientName %>Client.<%= it.name %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>$httpConfig)<%= it.responseMapper %>,\n        config\n      );\n\n      return { data, isLoading, error, mutate };\n    },\n"
   },
   "tsq": {
     "baseClient.ejs": "import { type UseQueryOptions, type UseMutationOptions, useQuery, useMutation } from '@tanstack/react-query';\n",
-    "client.ejs": "export const <%= it.camelCaseName %>Client = {\n  <% it.operations.forEach((operation) => { %>\n<%~ include('operation.ejs', operation); %>\n\n<% }); %>\n};\n\n<%\nvar getOperations = it.operations.filter((o) => o.method === 'GET');\nvar mutationOperations = it.operations.filter((o) => o.method !== 'GET');\n\n// Helper: strip leading \"get\" and capitalise\nfunction toOpName(name) {\n  var n = name.toLowerCase().startsWith('get') ? name.substring(3) : name;\n  return n.charAt(0).toUpperCase() + n.slice(1);\n}\n\n// Returns a deep copy of operation with any parameter whose name collides with\n// the group object name (clientName) renamed to _<name> to avoid TS shadowing.\nfunction safeOperation(operation, clientName) {\n  var safeParams = operation.parameters.map(function(p) {\n    return p.name === clientName ? Object.assign({}, p, { name: '_' + p.name }) : p;\n  });\n  return Object.assign({}, operation, { parameters: safeParams });\n}\n%>\n\nexport const <%= it.camelCaseName %> = {\n  queries: {\n<% getOperations.forEach((operation) => {\n  var opName = toOpName(operation.name);\n  var queryOperation = Object.assign({\n    rqOpName: 'use' + opName,\n    opKey: it.camelCaseName + opName,\n    clientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n  }, safeOperation(operation, it.camelCaseName));\n%>\n<%~ include('queryOperation.ejs', queryOperation); %>\n\n<% }); %>\n  },\n\n  mutations: {\n<% mutationOperations.forEach((operation) => {\n  var opName = operation.name.charAt(0).toUpperCase() + operation.name.slice(1);\n  var mutationOperation = Object.assign({\n    mutOpName: 'use' + opName,\n    clientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n  }, safeOperation(operation, it.camelCaseName));\n%>\n<%~ include('mutationOperation.ejs', mutationOperation); %>\n\n<% }); %>\n  },\n\n  queryKeys: {\n<% getOperations.forEach((operation) => {\n  var opName = toOpName(operation.name);\n  var keyName = opName.charAt(0).toLowerCase() + opName.slice(1);\n  var safeOp = safeOperation(operation, it.camelCaseName);\n%>\n    <%= keyName %>: (<% safeOp.parameters.forEach((parameter) => { %><%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>, <% }); %>) => ['<%= it.camelCaseName %>', '<%= it.camelCaseName + opName %>'<% safeOp.parameters.forEach((parameter) => { %>, <%= parameter.name %><% }); %>] as const,\n<% }); %>\n  },\n};\n",
-    "mutationOperation.ejs": "<%\nvar hasParams = it.parameters.length > 0;\n\nvar variablesType;\nif (!hasParams) {\n  variablesType = 'void';\n} else {\n  var parts = it.parameters.map(function(p) {\n    return p.name + (p.skippable ? '?' : '') + ': ' + p.type + (p.optional ? ' | null' : '');\n  });\n  variablesType = '{ ' + parts.join('; ') + ' }';\n}\n\nvar callArgs = it.parameters.map(function(p) { return 'vars.' + p.name; });\n\nvar baseAdditionalParams = '  * @param $config (optional) Additional configuration for TanStack Query\\n  * @param $httpConfig (optional) Additional HTTP client configuration (passed to the underlying ' + it.httpConfigType + ')';\nvar rawDocs = it.jsDocs\n  ? it.jsDocs.replace(/(\\s*)\\*\\/\\s*$/, '\\n' + baseAdditionalParams + '\\n */')\n  : '';\nvar docs = rawDocs ? rawDocs.replace(/^/gm, '  ') + '\\n' : '';\n%>\n<%~ docs %>\n    <%= it.mutOpName %><TData = <%~ it.returnType %>, TError = Error>(\n      $config?: UseMutationOptions<<%~ it.returnType %>, TError, <%~ variablesType %>>,\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      return useMutation<<%~ it.returnType %>, TError, <%~ variablesType %>>({\n        mutationFn: (<%= hasParams ? 'vars' : '' %>) => <%= it.clientName %>Client.<%= it.name %>(<%= callArgs.join(', ') %><%= callArgs.length > 0 ? ', ' : '' %>$httpConfig).then(res => res.data),\n        ...$config\n      });\n    },\n",
-    "queryOperation.ejs": "<%\nvar baseAdditionalParams = '  * @param $config (optional) Additional configuration for TanStack Query\\n  * @param $httpConfig (optional) Additional HTTP client configuration (passed to the underlying ' + it.httpConfigType + ')';\nvar rawDocs = it.jsDocs\n  ? it.jsDocs.replace(/(\\s*)\\*\\/\\s*$/, '\\n' + baseAdditionalParams + '\\n */')\n  : '';\nvar docs = rawDocs ? rawDocs.replace(/^/gm, '  ') + '\\n' : '';\n%>\n<%~ docs %>\n    <%= it.rqOpName %><TData = <%~ it.returnType %>, TError = Error>(\n<% it.parameters.forEach((parameter) => { %>      <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>,\n<% }); %>      $config?: Omit<UseQueryOptions<<%~ it.returnType %>, TError, TData>, 'queryKey' | 'queryFn'>,\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      return useQuery<<%~ it.returnType %>, TError, TData>({\n        queryKey: <%= it.clientName %>.queryKeys.<%= it.rqOpName.charAt(3).toLowerCase() + it.rqOpName.slice(4) %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>),\n        queryFn: () => <%= it.clientName %>Client.<%= it.name %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>$httpConfig).then(res => res.data),\n        ...$config\n      });\n    },\n"
+    "client.ejs": "export const <%= it.camelCaseName %>Client = {\n  <% it.operations.forEach((operation) => { %>\n<%~ include('operation.ejs', operation); %>\n\n<% }); %>\n};\n\n<% if (!it.splitMode) { %>\n<%\nvar getOperations = it.operations.filter((o) => o.method === 'GET');\nvar mutationOperations = it.operations.filter((o) => o.method !== 'GET');\n%>\n\nexport const <%= it.camelCaseName %> = {\n  queries: {\n<% getOperations.forEach((operation) => {\n  var opName = it.toOpName(operation.name);\n  var queryOperation = Object.assign({\n    rqOpName: 'use' + opName,\n    opKey: it.camelCaseName + opName,\n    clientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n  }, it.safeOperation(operation, it.camelCaseName));\n%>\n<%~ include('queryOperation.ejs', queryOperation); %>\n\n<% }); %>\n  },\n\n  mutations: {\n<% mutationOperations.forEach((operation) => {\n  var opName = operation.name.charAt(0).toUpperCase() + operation.name.slice(1);\n  var mutationOperation = Object.assign({\n    mutOpName: 'use' + opName,\n    clientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n  }, it.safeOperation(operation, it.camelCaseName));\n%>\n<%~ include('mutationOperation.ejs', mutationOperation); %>\n\n<% }); %>\n  },\n\n  queryKeys: {\n<% getOperations.forEach((operation) => {\n  var opName = it.toOpName(operation.name);\n  var keyName = opName.charAt(0).toLowerCase() + opName.slice(1);\n  var safeOp = it.safeOperation(operation, it.camelCaseName);\n%>\n    <%= keyName %>: (<% safeOp.parameters.forEach((parameter) => { %><%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>, <% }); %>) => ['<%= it.camelCaseName %>', '<%= it.camelCaseName + opName %>'<% safeOp.parameters.forEach((parameter) => { %>, <%= parameter.name %><% }); %>] as const,\n<% }); %>\n  },\n};\n<% } /* end !splitMode */ %>\n",
+    "hooksClient.ejs": "<%\nvar getOperations = it.operations.filter((o) => o.method === 'GET');\nvar mutationOperations = it.operations.filter((o) => o.method !== 'GET');\nvar httpClientPrefix = 'API.' + it.camelCaseName;\n%>\n\nexport const <%= it.camelCaseName %> = {\n  queries: {\n<% getOperations.forEach((operation) => {\n  var opName = it.toOpName(operation.name);\n  var safe = it.safeOperation(operation, it.camelCaseName);\n  var queryOperation = Object.assign({}, safe, {\n    rqOpName: 'use' + opName,\n    opKey: it.camelCaseName + opName,\n    clientName: it.camelCaseName,\n    httpClientName: httpClientPrefix,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    returnType: it.prefixApiType(safe.returnType),\n    parameters: safe.parameters.map(function(p) {\n      return Object.assign({}, p, { type: it.prefixApiType(p.type) });\n    }),\n  });\n%>\n<%~ include('queryOperation.ejs', queryOperation); %>\n\n<% }); %>\n  },\n\n  mutations: {\n<% mutationOperations.forEach((operation) => {\n  var opName = operation.name.charAt(0).toUpperCase() + operation.name.slice(1);\n  var safe = it.safeOperation(operation, it.camelCaseName);\n  var mutationOperation = Object.assign({}, safe, {\n    mutOpName: 'use' + opName,\n    clientName: it.camelCaseName,\n    httpClientName: httpClientPrefix,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    returnType: it.prefixApiType(safe.returnType),\n    parameters: safe.parameters.map(function(p) {\n      return Object.assign({}, p, { type: it.prefixApiType(p.type) });\n    }),\n  });\n%>\n<%~ include('mutationOperation.ejs', mutationOperation); %>\n\n<% }); %>\n  },\n\n  queryKeys: {\n<% getOperations.forEach((operation) => {\n  var opName = it.toOpName(operation.name);\n  var keyName = opName.charAt(0).toLowerCase() + opName.slice(1);\n  var safeOp = it.safeOperation(operation, it.camelCaseName);\n  var prefixedParams = safeOp.parameters.map(function(p) {\n    return Object.assign({}, p, { type: it.prefixApiType(p.type) });\n  });\n%>\n    <%= keyName %>: (<% prefixedParams.forEach((parameter) => { %><%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>, <% }); %>) => ['<%= it.camelCaseName %>', '<%= it.camelCaseName + opName %>'<% safeOp.parameters.forEach((parameter) => { %>, <%= parameter.name %><% }); %>] as const,\n<% }); %>\n  },\n};\n",
+    "mutationOperation.ejs": "<%\nvar hasParams = it.parameters.length > 0;\n\nvar variablesType;\nif (!hasParams) {\n  variablesType = 'void';\n} else {\n  var parts = it.parameters.map(function(p) {\n    return p.name + (p.skippable ? '?' : '') + ': ' + p.type + (p.optional ? ' | null' : '');\n  });\n  variablesType = '{ ' + parts.join('; ') + ' }';\n}\n\nvar callArgs = it.parameters.map(function(p) { return 'vars.' + p.name; });\n\nvar baseAdditionalParams = '  * @param $config (optional) Additional configuration for TanStack Query\\n  * @param $httpConfig (optional) Additional HTTP client configuration (passed to the underlying ' + it.httpConfigType + ')';\nvar rawDocs = it.jsDocs\n  ? it.jsDocs.replace(/(\\s*)\\*\\/\\s*$/, '\\n' + baseAdditionalParams + '\\n */')\n  : '';\nvar docs = rawDocs ? rawDocs.replace(/^/gm, '  ') + '\\n' : '';\nvar httpClientName = it.httpClientName || it.clientName;\n%>\n<%~ docs %>\n    <%= it.mutOpName %><TData = <%~ it.returnType %>, TError = Error>(\n      $config?: UseMutationOptions<<%~ it.returnType %>, TError, <%~ variablesType %>>,\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      return useMutation<<%~ it.returnType %>, TError, <%~ variablesType %>>({\n        mutationFn: (<%= hasParams ? 'vars' : '' %>) => <%= httpClientName %>Client.<%= it.name %>(<%= callArgs.join(', ') %><%= callArgs.length > 0 ? ', ' : '' %>$httpConfig)<%= it.responseMapper %>,\n        ...$config\n      });\n    },\n",
+    "queryOperation.ejs": "<%\nvar baseAdditionalParams = '  * @param $config (optional) Additional configuration for TanStack Query\\n  * @param $httpConfig (optional) Additional HTTP client configuration (passed to the underlying ' + it.httpConfigType + ')';\nvar rawDocs = it.jsDocs\n  ? it.jsDocs.replace(/(\\s*)\\*\\/\\s*$/, '\\n' + baseAdditionalParams + '\\n */')\n  : '';\nvar docs = rawDocs ? rawDocs.replace(/^/gm, '  ') + '\\n' : '';\nvar httpClientName = it.httpClientName || it.clientName;\n%>\n<%~ docs %>\n    <%= it.rqOpName %><TData = <%~ it.returnType %>, TError = Error>(\n<% it.parameters.forEach((parameter) => { %>      <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>,\n<% }); %>      $config?: Omit<UseQueryOptions<<%~ it.returnType %>, TError, TData>, 'queryKey' | 'queryFn'>,\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      return useQuery<<%~ it.returnType %>, TError, TData>({\n        queryKey: <%= it.clientName %>.queryKeys.<%= it.rqOpName.charAt(3).toLowerCase() + it.rqOpName.slice(4) %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>),\n        queryFn: () => <%= httpClientName %>Client.<%= it.name %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>$httpConfig)<%= it.responseMapper %>,\n        ...$config\n      });\n    },\n"
   },
   "xior": {
-    "barrel.ejs": "",
+    "barrel.ejs": "export { encodeParams } from 'xior';\n",
     "baseClient.ejs": "import xior, { type XiorResponse, type XiorRequestConfig, encodeParams } from \"xior\";\n\nexport const http = xior.create({\n  baseURL: '<%= it.baseUrl || '' %>',\n  paramsSerializer: (params: any) =>\n    encodeParams(params, true, null, {\n      allowDots: <%= it.allowDots %>,\n      arrayFormat: '<%= it.arrayFormat %>',\n    }),\n});\n\n",
+    "baseClientSetup.ejs": "/**\n * Xior client setup — GENERATED ONCE, will NOT be overwritten on subsequent runs.\n * Re-generate intentionally with: swaggie ... --clientSetup <path> --forceSetup\n *\n * This file is a write-once scaffold for configuring the xior instance exported\n * from the generated API client. It is NOT imported by api.ts — call\n * `setupApiClient()` once at your application startup.\n *\n * Usage in your app:\n *   import { setupApiClient } from '<%= it.relativeSetupImport %>';\n *   const cleanup = setupApiClient(); // call once before any API requests\n *\n * The setup function can accept any parameters your app needs (e.g. an auth ref):\n *   export function setupApiClient(authRef: AuthRef): () => void { ... }\n */\nimport { http } from '<%= it.relativeApiImport %>';\n\n/**\n * Registers interceptors on the shared xior instance.\n * Returns a cleanup function that ejects the interceptors — useful for\n * React effects or other lifecycle-managed contexts.\n */\nexport function setupApiClient(): () => void {\n  const requestInterceptor = http.interceptors.request.use(\n    (config) => {\n      // TODO: Add request interceptors, e.g. attach an Authorization header:\n      // const token = await authRef.current.getAccessToken();\n      // if (token) config.headers.Authorization = `Bearer ${token}`;\n      return config;\n    },\n    (error) => Promise.reject(error)\n  );\n\n  const responseInterceptor = http.interceptors.response.use(\n    (response) => response,\n    async (error) => {\n      // TODO: Add response error handling, e.g. redirect on 401:\n      // if (error.response?.status === 401) {\n      //   await authRef.current.loginWithRedirect({ returnTo: window.location.toString() });\n      //   return;\n      // }\n      return Promise.reject(error);\n    }\n  );\n\n  return () => {\n    http.interceptors.request.eject(requestInterceptor);\n    http.interceptors.response.eject(responseInterceptor);\n  };\n}\n",
     "client.ejs": "export const <%= it.camelCaseName %>Client = {\n  <% it.operations.forEach((operation) => { %>\n<%~ include('operation.ejs', operation); %>\n\n<% }); %>\n};\n\n",
     "operation.ejs": "<%~ it.jsDocs %>\n\n  <%= it.name %>(<% it.parameters.forEach((parameter) => { %>\n<%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,\n    <% }); %>\n$config?: XiorRequestConfig\n  ): Promise<XiorResponse<<%~ it.returnType %>>> {\n    const url = `<%= it.url %>`;\n\n    return http.request<<%~ it.returnType %>>({\n      url: url,\n      method: '<%= it.method %>',\n<% if(it.body) { -%>\n<% if(it.body.contentType === 'urlencoded') { -%>\n      data: new URLSearchParams(<%= it.body.name %> as any),\n<% } else { -%>\n      data: <%= it.body.name %>,\n<% } -%>\n<% } -%>\n<% if(it.query && it.query.length > 0) { -%>\n      params: {\n<% it.query.forEach((parameter) => { -%>\n<% if (it.queryParamObject) { -%>\n        '<%= parameter.originalName %>': <%= it.queryParamObject.name %>?.<%= parameter.name %>,\n<% } else { -%>\n        '<%= parameter.originalName %>': <%= parameter.name %>,\n<% } -%>\n<% }); -%>\n      },\n<% } -%>\n<% if(it.headers && it.headers.length > 0) { -%>\n      headers: {\n<% it.headers.forEach((parameter) => { -%>\n<% if (parameter.value) { -%>\n        '<%= parameter.originalName %>': '<%= parameter.value %>',\n<% } else { -%>\n        '<%= parameter.originalName %>': <%= parameter.name %>,\n<% } -%>\n<% }); -%>\n      },\n<% } -%>\n      ...$config,\n    });\n  },\n"
   }

package/dist/index.js

@@ -40,6 +40,28 @@ function verifyOptions(options) {
       '--mocks requires --out to be set, since the mock file needs to import the generated client'
     );
   }
+  if (options.hooksOut && !options.out) {
+    throw new Error('--hooksOut requires --out to be set');
+  }
+  if (options.clientSetup && !options.out) {
+    throw new Error('--clientSetup requires --out to be set');
+  }
+  if (options.forceSetup && !options.clientSetup) {
+    throw new Error('--forceSetup requires --clientSetup to be set');
+  }
+  if (options.hooksOut) {
+    // Validate after normalization — template may be a bare L2 string or a pair
+    const tpl = options.template;
+    const isL2 =
+      (typeof tpl === 'string' && _templateValidator.isL2Template.call(void 0, tpl)) ||
+      (Array.isArray(tpl) && typeof tpl[0] === 'string' && _templateValidator.isL2Template.call(void 0, tpl[0]));
+    if (!isL2) {
+      throw new Error(
+        '--hooksOut requires an L2 template (swr, tsq). ' +
+          'Reactive hooks are only generated for L2 template pairs.'
+      );
+    }
+  }
 }
 
 function gen(spec, options) {
@@ -103,6 +125,9 @@ function readFile(filePath) {
     queryParamsSerialization = {},
     mocks,
     testingFramework,
+    hooksOut,
+    clientSetup,
+    forceSetup,
     ...rest
   } = cliOpts;
   const mergedQueryParamsSerialization = {
@@ -129,6 +154,9 @@ function readFile(filePath) {
     queryParamsSerialization: mergedQueryParamsSerialization,
     ...(mocks !== undefined ? { mocks } : {}),
     ...(testingFramework !== undefined ? { testingFramework } : {}),
+    ...(hooksOut !== undefined ? { hooksOut } : {}),
+    ...(clientSetup !== undefined ? { clientSetup } : {}),
+    ...(forceSetup !== undefined ? { forceSetup } : {}),
   };
 } exports.prepareAppOptions = prepareAppOptions;
 

package/dist/types.d.ts

@@ -50,12 +50,23 @@ export interface ClientOptions {
      */
     enumNamesStyle?: EnumNamesStyle;
     /**
-     * Prepends `'use client';` as the very first line of the generated file.
+     * Prepends `'use client';` as the very first line of the generated hooks file
+     * (when `hooksOut` is set) or the main generated file (legacy single-file mode).
      * Required for Next.js App Router when using SWR or TanStack Query hooks,
      * which can only run in Client Components.
      * Has no effect and should not be used with non-RSC environments.
      */
     useClient?: boolean;
+    /**
+     * Output path for the generated reactive hooks file (L2 templates only).
+     * When set, the reactive hook namespaces (`pet.queries`, `pet.mutations`,
+     * `pet.queryKeys`) are written to this file instead of the main `out` file.
+     * The hooks file imports the main file as `import * as API from './api'`.
+     * When `useClient` is also set, the `'use client';` directive is prepended
+     * only to this file (the main file remains server-safe).
+     * Requires `out` to also be set.
+     */
+    hooksOut?: string;
     /**
      * Output path for the generated mock/stub file. Requires `testingFramework`
      * and `out` to also be set. When provided, a companion mock file is generated
@@ -69,6 +80,25 @@ export interface ClientOptions {
      * Requires `mocks` and `out` to also be set.
      */
     testingFramework?: TestingFramework;
+    /**
+     * Output path for the write-once client setup file. When provided, Swaggie
+     * generates a setup scaffold at this path on the first run and never overwrites
+     * it on subsequent runs (use `forceSetup` to override this).
+     *
+     * For the `ky` template, the generated `api.ts` imports from this file and uses
+     * its exported `createKyConfig()` to initialise the ky instance with hooks.
+     * For other templates (`axios`, `xior`, `fetch`), the setup file is a standalone
+     * scaffold showing how to configure the exported HTTP client — `api.ts` does not
+     * import it.
+     *
+     * Requires `out` to also be set.
+     */
+    clientSetup?: string;
+    /**
+     * When `true`, overwrites the setup file even if it already exists.
+     * Has no effect unless `clientSetup` is also set.
+     */
+    forceSetup?: boolean;
     /** Offers ability to adjust the OpenAPI spec before it is processed */
     modifiers?: {
         /** Global-level modifiers for parameter with a given name */
@@ -95,7 +125,7 @@ export interface FullAppOptions extends ClientOptions {
     config?: string;
 }
 /** HTTP client templates (standalone, no reactive layer) */
-export type L1Template = 'axios' | 'fetch' | 'xior' | 'ng1' | 'ng2';
+export type L1Template = 'axios' | 'fetch' | 'xior' | 'ng1' | 'ng2' | 'ky';
 /** Reactive query layer templates (must be composed with an L1 template) */
 export type L2Template = 'swr' | 'tsq';
 /** Any named built-in template */

package/dist/utils/fileUtils.js

@@ -35,3 +35,23 @@ var _nodepath = require('node:path');
     });
   });
 } exports.saveFile = saveFile;
+
+/**
+ * Writes `contents` to `filePath` only when the file does not already exist,
+ * or when `force` is `true`. Useful for write-once scaffold files that should
+ * survive re-generation without losing user edits.
+ *
+ * @returns `'written'` when the file was created/overwritten, `'skipped'` when
+ *          it already existed and `force` was not set.
+ */
+ async function saveFileIfMissing(
+  filePath,
+  contents,
+  force = false
+) {
+  if (!force && _nodefs.existsSync.call(void 0, filePath)) {
+    return 'skipped';
+  }
+  await saveFile(filePath, contents);
+  return 'written';
+} exports.saveFileIfMissing = saveFileIfMissing;

package/dist/utils/templateValidator.js

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-const L1_TEMPLATES = ['axios', 'fetch', 'xior', 'ng1', 'ng2'];
+const L1_TEMPLATES = ['axios', 'fetch', 'xior', 'ng1', 'ng2', 'ky'];
 const L2_TEMPLATES = ['swr', 'tsq'];
 
 /** L1 templates that are incompatible with any L2 (framework-specific clients) */
@@ -120,8 +120,36 @@ const DEFAULT_L1_FOR_L2 = 'fetch';
       return 'XiorRequestConfig';
     case 'fetch':
       return 'RequestInit';
+    case 'ky':
+      return 'KyOptions';
     default:
       // Custom path or unknown — fall back to a permissive type
       return 'Record<string, unknown>';
   }
 } exports.getHttpConfigType = getHttpConfigType;
+
+/**
+ * Returns the response mapper snippet used in L2 operation templates to extract
+ * the final data value from a client method call.
+ *
+ * Axios and xior wrap responses in `{ data: T }`, so the mapper unwraps `.data`.
+ * Fetch and ky resolve to `T` directly, so no unwrapping is needed.
+ *
+ * The returned string is appended after the client call expression:
+ *   `client.method(...args)` + responseMapper
+ *
+ * Examples:
+ *   axios/xior → `.then((resp) => resp.data)`
+ *   fetch/ky   → ``  (empty — the promise already resolves to T)
+ */
+ function getResponseMapper(template) {
+  const l1 = getL1Template(template);
+  switch (l1) {
+    case 'fetch':
+    case 'ky':
+      return '';
+    default:
+      // axios, xior, and unknown custom templates all use { data: T } wrapper
+      return '.then((resp) => resp.data)';
+  }
+} exports.getResponseMapper = getResponseMapper;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swaggie",
-  "version": "2.0.0",
+  "version": "2.1.0-alpha.4",
   "description": "Generate a fully typed TypeScript API client from your OpenAPI 3 spec",
   "author": {
     "name": "Piotr Dabrowski",

package/templates/axios/barrel.ejs

@@ -4,7 +4,7 @@
  * Implementation from: https://github.com/suhaotian/xior/blob/main/src/utils.ts
  * Kudos to @suhaotian for the original implementation
  */
-function encodeParams<T = any>(
+export function encodeParams<T = any>(
   params: T,
   parentKey: string | null = null,
   options?: {

package/templates/axios/baseClientSetup.ejs

@@ -0,0 +1,46 @@
+/**
+ * Axios client setup — GENERATED ONCE, will NOT be overwritten on subsequent runs.
+ * Re-generate intentionally with: swaggie ... --clientSetup <path> --forceSetup
+ *
+ * This file is a write-once scaffold for configuring the Axios instance exported
+ * from the generated API client. It is NOT imported by api.ts — call
+ * `setupApiClient()` once at your application startup.
+ *
+ * Usage in your app:
+ *   import { setupApiClient } from '<%= it.relativeSetupImport %>';
+ *   setupApiClient(); // call once before any API requests
+ *
+ * The setup function can accept any parameters your app needs (e.g. an auth ref):
+ *   export function setupApiClient(authRef: AuthRef): () => void { ... }
+ */
+import { axios } from '<%= it.relativeApiImport %>';
+
+/**
+ * Configures the shared Axios instance with request/response interceptors.
+ * Returns a cleanup function that ejects the interceptors — useful for
+ * React effects or other lifecycle-managed contexts.
+ */
+export function setupApiClient(): () => void {
+  const requestInterceptor = axios.interceptors.request.use(
+    (config) => {
+      // TODO: Add request interceptors, e.g. attach an Authorization header:
+      // config.headers.Authorization = `Bearer ${getToken()}`;
+      return config;
+    },
+    (error) => Promise.reject(error)
+  );
+
+  const responseInterceptor = axios.interceptors.response.use(
+    (response) => response,
+    (error) => {
+      // TODO: Add response error handling, e.g. redirect on 401:
+      // if (error.response?.status === 401) { loginWithRedirect(); }
+      return Promise.reject(error);
+    }
+  );
+
+  return () => {
+    axios.interceptors.request.eject(requestInterceptor);
+    axios.interceptors.response.eject(responseInterceptor);
+  };
+}

package/templates/fetch/barrel.ejs

@@ -4,7 +4,7 @@
  * Implementation from: https://github.com/suhaotian/xior/blob/main/src/utils.ts
  * Kudos to @suhaotian for the original implementation
  */
-function encodeParams<T = any>(
+export function encodeParams<T = any>(
   params: T,
   parentKey: string | null = null,
   options?: {

package/templates/fetch/baseClientSetup.ejs

@@ -0,0 +1,38 @@
+/**
+ * Fetch client setup — GENERATED ONCE, will NOT be overwritten on subsequent runs.
+ * Re-generate intentionally with: swaggie ... --clientSetup <path> --forceSetup
+ *
+ * This file is a write-once scaffold for configuring the fetch-based client
+ * exported from the generated API client. It is NOT imported by api.ts — call
+ * `setupApiClient()` once at your application startup.
+ *
+ * Usage in your app:
+ *   import { setupApiClient } from '<%= it.relativeSetupImport %>';
+ *   setupApiClient(); // call once before any API requests
+ *
+ * The setup function can accept any parameters your app needs (e.g. an auth ref):
+ *   export function setupApiClient(authRef: AuthRef): void { ... }
+ */
+import { defaults } from '<%= it.relativeApiImport %>';
+
+/**
+ * Configures the shared fetch client defaults.
+ * Override `defaults.fetch` to wrap the native fetch with custom behaviour
+ * (auth headers, error handling, logging, etc.).
+ */
+export function setupApiClient(): void {
+  const originalFetch = defaults.fetch ?? globalThis.fetch;
+
+  defaults.fetch = async (input, init) => {
+    // TODO: Add pre-request logic, e.g. attach an Authorization header:
+    // const token = await getToken();
+    // init = { ...init, headers: { ...init?.headers, Authorization: `Bearer ${token}` } };
+
+    const response = await originalFetch(input, init);
+
+    // TODO: Add post-response logic, e.g. handle 401 Unauthorized:
+    // if (response.status === 401) { loginWithRedirect(); }
+
+    return response;
+  };
+}

package/templates/ky/barrel.ejs

@@ -0,0 +1,57 @@
+
+/**
+ * Serializes a params object into a query string that is compatible with different REST APIs.
+ * Implementation from: https://github.com/suhaotian/xior/blob/main/src/utils.ts
+ * Kudos to @suhaotian for the original implementation
+ */
+export function encodeParams<T = any>(
+  params: T,
+  parentKey: string | null = null,
+  options?: {
+    allowDots?: boolean;
+    serializeDate?: (value: Date) => string;
+    arrayFormat?: 'indices' | 'repeat' | 'brackets';
+  }
+): string {
+  if (params === undefined || params === null) return '';
+  const encodedParams: string[] = [];
+  const paramsIsArray = Array.isArray(params);
+  const { arrayFormat, allowDots, serializeDate } = options || {};
+
+  const getKey = (key: string) => {
+    if (allowDots && !paramsIsArray) return `.${key}`;
+    if (paramsIsArray) {
+      if (arrayFormat === 'brackets') {
+        return '[]';
+      }
+      if (arrayFormat === 'repeat') {
+        return '';
+      }
+    }
+    return `[${key}]`;
+  };
+
+  for (const key in params) {
+    if (Object.prototype.hasOwnProperty.call(params, key)) {
+      let value = (params as any)[key];
+      if (value !== undefined) {
+        const encodedKey = parentKey ? `${parentKey}${getKey(key)}` : (key as string);
+
+        // biome-ignore lint/suspicious/noGlobalIsNan: <explanation>
+        if (!isNaN(value) && value instanceof Date) {
+          value = serializeDate ? serializeDate(value) : value.toISOString();
+        }
+        if (typeof value === 'object') {
+          // If the value is an object or array, recursively encode its contents
+          const result = encodeParams(value, encodedKey, options);
+          if (result !== '') encodedParams.push(result);
+        } else {
+          // Otherwise, encode the key-value pair
+          encodedParams.push(`${encodeURIComponent(encodedKey)}=${encodeURIComponent(value)}`);
+        }
+      }
+    }
+  }
+
+  return encodedParams.join('&');
+}

package/templates/ky/baseClient.ejs

@@ -0,0 +1,5 @@
+import ky, { type Options as KyOptions } from 'ky';
+
+export const http = ky.create({
+  prefix: '<%= it.baseUrl || '' %>',
+});