swaggie 2.2.2 → 2.4.0

package/README.md

@@ -396,6 +396,21 @@ Sometimes an API spec marks a parameter as required, but your client handles it
 - `"optional"` — the parameter becomes optional regardless of what the spec says
 - `"required"` — the parameter is always required (generally better to just fix the spec)
 
+### Excluding Operations
+
+Use `exclude` to drop entire operations from the generated output by tag or `operationId` — without modifying the spec. Types used exclusively by excluded operations are pruned automatically. Both fields support `*` and `?` wildcards.
+
+```json
+{
+  "exclude": {
+    "tags": ["admin", "internal"],
+    "operationIds": ["deleteAccount", "admin*"]
+  }
+}
+```
+
+See the [full documentation](https://yhnavein.github.io/swaggie/guide/advanced#excluding-operations) for details and examples.
+
 ### Code Quality
 
 Swaggie's output is functional but not always perfectly formatted, since it uses a templating engine internally. It is strongly recommended to run the output through a formatter to ensure consistent style across regenerations.

package/dist/cli.js

@@ -45,6 +45,12 @@ const queryParamsAsObjectOption = new (0, _commander.Option)(
   '--queryParamsAsObject [threshold]',
   'Group query params into a single object; pass a number to group only when query params count is greater than threshold'
 ).argParser(parseQueryParamsAsObjectArg);
+const responseShapeOption = new (0, _commander.Option)(
+  '--responseShape <shape>',
+  "Standardize operation return shape across templates: 'body' returns the body (T); " +
+    "'full' returns an APIResponse<T> wrapper with data, headers and statusCode. " +
+    'When omitted, each template keeps its current default return shape.'
+).choices(['body', 'full']);
 
 const program = new (0, _commander.Command)();
 program
@@ -101,6 +107,7 @@ program
   .addOption(dateFormatOption)
   .addOption(nullableStrategyOption)
   .addOption(queryParamsAsObjectOption)
+  .addOption(responseShapeOption)
   .option(
     '--hooksOut <filePath>',
     'Output path for the generated hooks file (L2 templates only). ' +

package/dist/gen/genMocks.js

@@ -287,14 +287,9 @@ function withMockSWR<Fn extends (...args: never[]) => unknown>(spy: ${ref}.Spied
 /** Augments a spy with a \`mockSWRMutation\` shorthand for useSWRMutation hooks. */
 function withMockSWRMutation<Fn extends (...args: never[]) => unknown>(spy: ${ref}.SpiedFunction<Fn>) {
   return Object.assign(spy, {
-    mockSWRMutation({
-      data,
-      ...rest
-    }: MockSWRMutationReturn) {
+    mockSWRMutation({ ...rest }: MockSWRMutationReturn) {
       spy.mockReturnValue({
         ...defaultSWRMutationReturn,
-        trigger: ${ref}.fn(() => Promise.resolve(undefined)),
-        data,
         ...rest,
       } as ReturnType<Fn>);
     },

package/dist/gen/genOperations.js

@@ -23,6 +23,16 @@ var _header = require('./header');
 
 var _jsDocs = require('./jsDocs');
 
+/**
+ * Name of the generated wrapper interface emitted when `responseShape: 'full'`.
+ * Exposed to templates as `it.apiResponseType` so the name lives in one place.
+ *
+ * NOTE: like the 3rd-party type imports (e.g. `AxiosRequestConfig`), this name is
+ * not currently guarded against collisions with a user-defined schema of the same
+ * name. Keep it stable and reasonably unique.
+ */
+const API_RESPONSE_TYPE = 'APIResponse';
+
 /**
  * Function that will analyze paths in the spec and generate the code for all the operations.
  *
@@ -45,6 +55,8 @@ var _jsDocs = require('./jsDocs');
     servicePrefix,
     baseUrl: options.baseUrl,
     ...options.queryParamsSerialization,
+    responseShape: options.responseShape,
+    apiResponseType: API_RESPONSE_TYPE,
     // For the ky+setup variant, embed the relative import to the setup file
     ...(isKyWithSetup && relativeSetupImport ? { relativeSetupImport } : {}),
   };
@@ -81,7 +93,9 @@ var _jsDocs = require('./jsDocs');
       ...clientData,
       servicePrefix,
       httpConfigType: _templateValidator.getHttpConfigType.call(void 0, options.template),
-      responseMapper: _templateValidator.getResponseMapper.call(void 0, options.template),
+      responseMapper: _templateValidator.getResponseMapper.call(void 0, options.template, options.responseShape),
+      responseShape: options.responseShape,
+      apiResponseType: API_RESPONSE_TYPE,
       // For the ky+setup variant, operations call getKyHttp() instead of the
       // module-level `http` singleton.
       httpAccessor: isKyWithSetup ? 'getKyHttp()' : 'http',
@@ -157,6 +171,8 @@ var _jsDocs = require('./jsDocs');
     servicePrefix,
     baseUrl: options.baseUrl,
     ...options.queryParamsSerialization,
+    responseShape: options.responseShape,
+    apiResponseType: API_RESPONSE_TYPE,
   };
 
   // L2 base client contains the reactive library imports (useSWR, useQuery, etc.)
@@ -191,7 +207,9 @@ var _jsDocs = require('./jsDocs');
       ...clientData,
       servicePrefix,
       httpConfigType: _templateValidator.getHttpConfigType.call(void 0, options.template),
-      responseMapper: _templateValidator.getResponseMapper.call(void 0, options.template),
+      responseMapper: _templateValidator.getResponseMapper.call(void 0, options.template, options.responseShape),
+      responseShape: options.responseShape,
+      apiResponseType: API_RESPONSE_TYPE,
       // Template helper functions — defined once here, used in all L2 templates.
       toOpName,
       safeOperation,
@@ -255,6 +273,18 @@ function prepareClient(
     ops = ops.filter((op) => !op.deprecated);
   }
 
+  if (_optionalChain([options, 'access', _2 => _2.exclude, 'optionalAccess', _3 => _3.tags, 'optionalAccess', _4 => _4.length])) {
+    ops = ops.filter(
+      (op) => !_optionalChain([op, 'access', _5 => _5.tags, 'optionalAccess', _6 => _6.some, 'call', _7 => _7((t) => options.exclude.tags.some((p) => matchesPattern(t, p)))])
+    );
+  }
+
+  if (_optionalChain([options, 'access', _8 => _8.exclude, 'optionalAccess', _9 => _9.operationIds, 'optionalAccess', _10 => _10.length])) {
+    ops = ops.filter(
+      (op) => !options.exclude.operationIds.some((p) => matchesPattern(_nullishCoalesce(op.operationId, () => ( '')), p))
+    );
+  }
+
   return ops.map((op) => {
     const operationContext = `${op.method.toUpperCase()} ${op.path} (${op.operationId || 'unknown operationId'})`;
 
@@ -295,9 +325,9 @@ function prepareClient(
 
       const headers = getParams(op.parameters , options, ['header']);
       // Some libraries need explicit Content-Type for request bodies.
-      if (_optionalChain([body, 'optionalAccess', _2 => _2.contentType]) === 'urlencoded') {
+      if (_optionalChain([body, 'optionalAccess', _11 => _11.contentType]) === 'urlencoded') {
         upsertFixedHeader(headers, 'Content-Type', 'application/x-www-form-urlencoded');
-      } else if (_optionalChain([body, 'optionalAccess', _3 => _3.contentType]) === 'json' && _templateValidator.getL1Template.call(void 0, options.template) === 'fetch') {
+      } else if (_optionalChain([body, 'optionalAccess', _12 => _12.contentType]) === 'json' && _templateValidator.getL1Template.call(void 0, options.template) === 'fetch') {
         upsertFixedHeader(headers, 'Content-Type', 'application/json');
       }
 
@@ -485,10 +515,10 @@ function prepareUrl(path) {
       type: _swagger.getParameterType.call(void 0, p, options),
       optional: p.required === undefined || p.required === null ? true : !p.required,
       original: p,
-      jsDoc: _optionalChain([p, 'access', _4 => _4.description, 'optionalAccess', _5 => _5.trim, 'call', _6 => _6()]),
+      jsDoc: _optionalChain([p, 'access', _13 => _13.description, 'optionalAccess', _14 => _14.trim, 'call', _15 => _15()]),
     }));
 
-  if (_optionalChain([options, 'access', _7 => _7.modifiers, 'optionalAccess', _8 => _8.parameters])) {
+  if (_optionalChain([options, 'access', _16 => _16.modifiers, 'optionalAccess', _17 => _17.parameters])) {
     for (const [name, modifier] of Object.entries(options.modifiers.parameters)) {
       const paramIndex = result.findIndex(
         (p) => p.original.in !== 'path' && (p.originalName === name || p.name === name)
@@ -539,7 +569,7 @@ function getRequestBody(
   let reqBody;
   if ('$ref' in rawReqBody) {
     const refName = rawReqBody.$ref.replace('#/components/requestBodies/', '');
-    const resolved = _optionalChain([components, 'optionalAccess', _9 => _9.requestBodies, 'optionalAccess', _10 => _10[refName]]);
+    const resolved = _optionalChain([components, 'optionalAccess', _18 => _18.requestBodies, 'optionalAccess', _19 => _19[refName]]);
     if (!resolved || '$ref' in resolved) {
       console.error(`RequestBody $ref '${rawReqBody.$ref}' not found in components/requestBodies`);
       return null;
@@ -673,6 +703,23 @@ function getL1HttpTypeImport(template) {
   }
 }
 
+/**
+ * Matches a value against a pattern that may contain `*` (any sequence of
+ * characters) or `?` (any single character). Falls back to exact equality for
+ * patterns that contain neither wildcard (fast path).
+ */
+ function matchesPattern(value, pattern) {
+  if (!pattern.includes('*') && !pattern.includes('?')) {
+    return value === pattern;
+  }
+  const regex = new RegExp(
+    '^' +
+      pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') +
+      '$'
+  );
+  return regex.test(value);
+} exports.matchesPattern = matchesPattern;
+
 function upsertFixedHeader(headers, headerName, value) {
   const headerIndex = headers.findIndex(
     (header) => header.originalName.toLowerCase() === headerName.toLowerCase()

package/dist/generated/bundledTemplates.js

@@ -4,58 +4,58 @@
  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 */\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",
+    "baseClient.ejs": "import Axios, { type AxiosPromise, type AxiosRequestConfig<% if (it.responseShape === 'full') { %>, type AxiosResponse<% } %> } 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<% if (it.responseShape === 'full') { %>\nexport interface <%= it.apiResponseType %><T> {\n  data: T;\n  headers: AxiosResponse<T>['headers'];\n  status: number;\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"
+    "operation.ejs": "<%\nvar returnTypeWrapped = 'AxiosPromise<' + it.returnType + '>';\nvar responseMapper = '';\nif (it.responseShape === 'full') {\n  // AxiosResponse<T> already exposes { data, headers, status } and is therefore\n  // structurally assignable to APIResponse<T> — no remap needed.\n  returnTypeWrapped = 'Promise<' + it.apiResponseType + '<' + it.returnType + '>>';\n} else if (it.responseShape === 'body') {\n  returnTypeWrapped = 'Promise<' + it.returnType + '>';\n  responseMapper = '.then((resp) => resp.data)';\n}\n%>\n<%~ 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  ): <%~ returnTypeWrapped %> {\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    })<%~ responseMapper %>;\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 */\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",
+    "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<% if (it.responseShape === 'full') { %>\nexport interface <%= it.apiResponseType %><T> {\n  data: T;\n  headers: Headers;\n  status: number;\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"
+    "operation.ejs": "<%\nvar parseMethod = it.responseContentType === 'binary' ? 'blob' : (it.responseContentType === 'text' ? 'text' : 'json');\nvar returnTypeWrapped = it.responseShape === 'full'\n  ? 'Promise<' + it.apiResponseType + '<' + it.returnType + '>>'\n  : 'Promise<' + it.returnType + '>';\n%>\n<%~ 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  ): <%~ returnTypeWrapped %> {\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.responseShape === 'full') { %>\n    .then(async (response) => ({\n      data: (await response.<%= parseMethod %>()) as <%~ it.returnType %>,\n      headers: response.headers,\n      status: response.status,\n    }));\n<% } else { %>\n    .then((response) => response.<%= parseMethod %>() 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 */\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/** Serializes a params object into a query string. Options override the generated defaults (allowDots, arrayFormat). */\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  return _encodeParams(params, parentKey, {\n    allowDots: <%= it.allowDots %>,\n    arrayFormat: '<%= it.arrayFormat %>',\n    ...options,\n  });\n}\n",
-    "baseClient.ejs": "import ky, { type Options as KyOptions } from 'ky';\n\nexport const http = ky.create({\n  prefix: '<%= it.baseUrl || '' %>',\n});\n",
+    "baseClient.ejs": "import ky, { type Options as KyOptions } from 'ky';\n\nexport const http = ky.create({\n  prefix: '<%= it.baseUrl || '' %>',\n});\n<% if (it.responseShape === 'full') { %>\nexport interface <%= it.apiResponseType %><T> {\n  data: T;\n  headers: Headers;\n  status: number;\n}\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",
+    "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<% if (it.responseShape === 'full') { %>\nexport interface <%= it.apiResponseType %><T> {\n  data: T;\n  headers: Headers;\n  status: number;\n}\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: encodeParams({\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<% 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"
+    "operation.ejs": "<%\nvar parseMethod = it.responseContentType === 'binary' ? 'blob' : (it.responseContentType === 'text' ? 'text' : 'json');\nvar returnTypeWrapped = it.responseShape === 'full'\n  ? 'Promise<' + it.apiResponseType + '<' + it.returnType + '>>'\n  : 'Promise<' + it.returnType + '>';\n%>\n<%~ 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  ): <%~ returnTypeWrapped %> {\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: encodeParams({\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<% if (it.responseShape === 'full') { -%>\n    }).then(async (response) => ({\n      data: (await response.<%= parseMethod %>()) as <%~ it.returnType %>,\n      headers: response.headers,\n      status: response.status,\n    }));\n<% } else 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",
+    "baseClient.ejs": "import type { IHttpService, IRequestShortcutConfig, IPromise<% if (it.responseShape === 'full') { %>, IHttpHeadersGetter<% } %> } 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<% if (it.responseShape === 'full') { %>\n  protected $getFull<T>(\n    url: string,\n    config?: IRequestShortcutConfig\n  ): IPromise<<%= it.apiResponseType %><T>> {\n    return this.$http.get(this.baseUrl + url, config).then((response: any) => this.processFull<T>(response));\n  }\n\n  protected $deleteFull<T>(\n    url: string,\n    config?: IRequestShortcutConfig\n  ): IPromise<<%= it.apiResponseType %><T>> {\n    return this.$http.delete(this.baseUrl + url, config).then((response: any) => this.processFull<T>(response));\n  }\n\n  protected $headFull<T>(\n    url: string,\n    config?: IRequestShortcutConfig\n  ): IPromise<<%= it.apiResponseType %><T>> {\n    return this.$http.head(this.baseUrl + url, config).then((response: any) => this.processFull<T>(response));\n  }\n\n  protected $jsonpFull<T>(\n    url: string,\n    config?: IRequestShortcutConfig\n  ): IPromise<<%= it.apiResponseType %><T>> {\n    return this.$http.jsonp(this.baseUrl + url, config).then((response: any) => this.processFull<T>(response));\n  }\n\n  protected $postFull<T>(\n    url: string,\n    data: any,\n    config?: IRequestShortcutConfig\n  ): IPromise<<%= it.apiResponseType %><T>> {\n    return this.$http.post(this.baseUrl + url, data, config).then((response: any) => this.processFull<T>(response));\n  }\n\n  protected $putFull<T>(\n    url: string,\n    data: any,\n    config?: IRequestShortcutConfig\n  ): IPromise<<%= it.apiResponseType %><T>> {\n    return this.$http.put(this.baseUrl + url, data, config).then((response: any) => this.processFull<T>(response));\n  }\n\n  protected $patchFull<T>(\n    url: string,\n    data: any,\n    config?: IRequestShortcutConfig\n  ): IPromise<<%= it.apiResponseType %><T>> {\n    return this.$http.patch(this.baseUrl + url, data, config).then((response: any) => this.processFull<T>(response));\n  }\n\n  protected processFull<T>(response: any): <%= it.apiResponseType %><T> {\n    return { data: response.data, headers: response.headers, status: response.status };\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<% if (it.responseShape === 'full') { %>\nexport interface <%= it.apiResponseType %><T> {\n  data: T;\n  headers: IHttpHeadersGetter;\n  status: number;\n}\n<% } %>\n\n",
     "client.ejs": "export class <%= it.clientName -%>Service extends BaseService {\n  /* @ngInject */\n  constructor($http: IHttpService, Api<%= it.servicePrefix -%>BaseUrl: string) {\n    super($http, Api<%= it.servicePrefix -%>BaseUrl);\n  }\n\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?: 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"
+    "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  ): <%~ it.responseShape === 'full' ? 'IPromise<' + it.apiResponseType + '<' + it.returnType + '>>' : '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() %><%= it.responseShape === 'full' ? 'Full' : '' %>(\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 */\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",
+    "baseClient.ejs": "import type { Observable } from \"rxjs\";\n<% if (it.responseShape === 'full') { %>import { map } from \"rxjs/operators\";\n<% } %>import { 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<% if (it.responseShape === 'full') { %>\nexport interface <%= it.apiResponseType %><T> {\n  data: T;\n  headers: HttpHeaders;\n  status: number;\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"
+    "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  ): <%~ it.responseShape === 'full' ? 'Observable<' + it.apiResponseType + '<' + it.returnType + '>>' : '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<%\nvar fullMap = '.pipe(\\n      map((response) => ({ data: response.body as ' + it.returnType + ', headers: response.headers, status: response.status }))\\n    )';\nvar bodyArg = it.body\n  ? (it.body.contentType === 'urlencoded' ? 'new URLSearchParams(' + it.body.name + ' as any)' : it.body.name)\n  : 'null';\n-%>\n<% if (it.responseShape === 'full') { -%>\n<% if(it.method === 'GET') { -%>\n    return this.http.get<<%~ it.returnType %>>(this.baseUrl + url, { ...config, observe: 'response' as const })<%~ fullMap %>;\n<% } else if(it.method === 'DELETE') { -%>\n    return this.http.delete<<%~ it.returnType %>>(this.baseUrl + url, { ...config, observe: 'response' as const })<%~ fullMap %>;\n<% } else if(['POST', 'PUT', 'PATCH'].includes(it.method)) { -%>\n    return this.http.<%= it.method.toLowerCase() %><%~ '<' + it.returnType + '>' %>(this.baseUrl + url, <%~ bodyArg %>, { ...config, observe: 'response' as const })<%~ fullMap %>;\n<% } -%>\n<% } else { -%>\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    return this.http.<%= it.method.toLowerCase() %><%~ '<' + it.returnType + '>' %>(this.baseUrl + url, <%~ bodyArg %>, config);\n<% } -%>\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<% 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.hooksCamelCaseName %> = {\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.hooksCamelCaseName,\n    httpClientName: 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.hooksCamelCaseName,\n    httpClientName: 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.hooksCamelCaseName %> = {\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.hooksCamelCaseName,\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.hooksCamelCaseName,\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, isValidating, 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, isValidating, error, mutate };\n    },\n"
+    "baseClient.ejs": "import useSWR, { type SWRConfiguration, type Key as SWRKey } 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?: SWRKey;\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.hooksCamelCaseName %> = {\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.hooksCamelCaseName,\n    httpClientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    responseShape: it.responseShape,\n    apiResponseType: it.apiResponseType,\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.hooksCamelCaseName,\n    httpClientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    responseShape: it.responseShape,\n    apiResponseType: it.apiResponseType,\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.hooksCamelCaseName %> = {\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.hooksCamelCaseName,\n    httpClientName: httpClientPrefix,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    responseShape: it.responseShape,\n    apiResponseType: it.prefixApiType(it.apiResponseType),\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.hooksCamelCaseName,\n    httpClientName: httpClientPrefix,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    responseShape: it.responseShape,\n    apiResponseType: it.prefixApiType(it.apiResponseType),\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;\nvar dataType = it.responseShape === 'full' ? it.apiResponseType + '<' + it.returnType + '>' : it.returnType;\n%>\n<%~ docs %>\n    <%= it.mutOpName %>(\n      $config?: SWRMutationConfiguration<<%~ dataType %>, Error, string, <%~ variablesType %>>,\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      return useSWRMutation<<%~ dataType %>, 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<% var dataType = it.responseShape === 'full' ? it.apiResponseType + '<' + it.returnType + '>' : it.returnType; %>\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?: SWRKey },\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, isValidating, mutate } = useSWR<<%~ dataType %>>(\n        cacheUrl,\n        () => <%= httpClientName %>Client.<%= it.name %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>$httpConfig)<%~ it.responseMapper %>,\n        config\n      );\n\n      return { data, isLoading, isValidating, 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<% 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.hooksCamelCaseName %> = {\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.hooksCamelCaseName + opName,\n    clientName: it.hooksCamelCaseName,\n    httpClientName: 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.hooksCamelCaseName,\n    httpClientName: 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.hooksCamelCaseName %>', '<%= it.hooksCamelCaseName + 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.hooksCamelCaseName %> = {\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.hooksCamelCaseName + opName,\n    clientName: it.hooksCamelCaseName,\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.hooksCamelCaseName,\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.hooksCamelCaseName %>', '<%= it.hooksCamelCaseName + 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"
+    "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.hooksCamelCaseName %> = {\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.hooksCamelCaseName + opName,\n    clientName: it.hooksCamelCaseName,\n    httpClientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    responseShape: it.responseShape,\n    apiResponseType: it.apiResponseType,\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.hooksCamelCaseName,\n    httpClientName: it.camelCaseName,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    responseShape: it.responseShape,\n    apiResponseType: it.apiResponseType,\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.hooksCamelCaseName %>', '<%= it.hooksCamelCaseName + 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.hooksCamelCaseName %> = {\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.hooksCamelCaseName + opName,\n    clientName: it.hooksCamelCaseName,\n    httpClientName: httpClientPrefix,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    responseShape: it.responseShape,\n    apiResponseType: it.prefixApiType(it.apiResponseType),\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.hooksCamelCaseName,\n    httpClientName: httpClientPrefix,\n    httpConfigType: it.httpConfigType,\n    responseMapper: it.responseMapper,\n    responseShape: it.responseShape,\n    apiResponseType: it.prefixApiType(it.apiResponseType),\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.hooksCamelCaseName %>', '<%= it.hooksCamelCaseName + 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;\nvar dataType = it.responseShape === 'full' ? it.apiResponseType + '<' + it.returnType + '>' : it.returnType;\n%>\n<%~ docs %>\n    <%= it.mutOpName %><TData = <%~ dataType %>, TError = Error>(\n      $config?: UseMutationOptions<<%~ dataType %>, TError, <%~ variablesType %>>,\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      return useMutation<<%~ dataType %>, 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;\nvar dataType = it.responseShape === 'full' ? it.apiResponseType + '<' + it.returnType + '>' : it.returnType;\n%>\n<%~ docs %>\n    <%= it.rqOpName %><TData = <%~ dataType %>, TError = Error>(\n<% it.parameters.forEach((parameter) => { %>      <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>,\n<% }); %>      $config?: Omit<UseQueryOptions<<%~ dataType %>, TError, TData>, 'queryKey' | 'queryFn'>,\n      $httpConfig?: <%= it.httpConfigType %>\n    ) {\n      return useQuery<<%~ dataType %>, 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": "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",
+    "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<% if (it.responseShape === 'full') { %>\nexport interface <%= it.apiResponseType %><T> {\n  data: T;\n  headers: XiorResponse<T>['headers'];\n  status: number;\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"
+    "operation.ejs": "<%\nvar returnTypeWrapped = 'Promise<XiorResponse<' + it.returnType + '>>';\nvar responseMapper = '';\nif (it.responseShape === 'full') {\n  // XiorResponse<T> already exposes { data, headers, status } and is therefore\n  // structurally assignable to APIResponse<T> — no remap needed.\n  returnTypeWrapped = 'Promise<' + it.apiResponseType + '<' + it.returnType + '>>';\n} else if (it.responseShape === 'body') {\n  returnTypeWrapped = 'Promise<' + it.returnType + '>';\n  responseMapper = '.then((resp) => resp.data)';\n}\n%>\n<%~ 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  ): <%~ returnTypeWrapped %> {\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    })<%~ responseMapper %>;\n  },\n"
   }
 } ; exports.BUNDLED_TEMPLATES = BUNDLED_TEMPLATES;
 

package/dist/index.js

@@ -10,6 +10,7 @@ var _gen = require('./gen'); var _gen2 = _interopRequireDefault(_gen);
 
 
 
+
 var _utils = require('./utils');
 var _templateValidator = require('./utils/templateValidator');
 var _swagger = require('./swagger');
@@ -86,6 +87,7 @@ function verifyOptions(options) {
       );
     }
   }
+  verifyExcludeOptions(options.exclude);
 }
 
 /**
@@ -126,6 +128,43 @@ function verifyEntryOptions(opts) {
       );
     }
   }
+  verifyExcludeOptions(opts.exclude);
+}
+
+/**
+ * Returns true when a pattern looks like a regex (starts with `/` or contains
+ * regex-specific metacharacters that are not our supported wildcards).
+ * Our supported wildcards are `*` and `?` only.
+ */
+function isRegexPattern(pattern) {
+  if (pattern.startsWith('/')) {
+    return true;
+  }
+  // Characters that are regex metacharacters but are NOT our supported wildcards
+  const regexOnlyChars = /[\\^$.|+()[\]{}]/;
+  return regexOnlyChars.test(pattern);
+}
+
+/**
+ * Throws if any pattern in `exclude.tags` or `exclude.operationIds` looks like
+ * a regex. Only plain strings and * / ? wildcards are supported.
+ */
+function verifyExcludeOptions(exclude) {
+  if (!exclude) {
+    return;
+  }
+  const allPatterns = [
+    ...(_nullishCoalesce(exclude.tags, () => ( []))).map((p) => ['exclude.tags', p]),
+    ...(_nullishCoalesce(exclude.operationIds, () => ( []))).map((p) => ['exclude.operationIds', p]),
+  ];
+  for (const [field, pattern] of allPatterns) {
+    if (isRegexPattern(pattern)) {
+      throw new Error(
+        `Invalid pattern "${pattern}" in ${field}: regex patterns are not supported. ` +
+          'Use plain strings or wildcard patterns with * and ? only.'
+      );
+    }
+  }
 }
 
 /**

package/dist/types.d.ts

@@ -4,6 +4,18 @@ interface QueryParamsSerializationOptions {
     arrayFormat?: ArrayFormat;
     queryParamsAsObject?: boolean | number;
 }
+export interface ExcludeOptions {
+    /**
+     * Exclude operations whose first tag matches any of these values.
+     * Supports * (any sequence of characters) and ? (any single character) wildcards.
+     */
+    tags?: string[];
+    /**
+     * Exclude operations whose operationId matches any of these values.
+     * Supports * (any sequence of characters) and ? (any single character) wildcards.
+     */
+    operationIds?: string[];
+}
 export interface ClientOptions {
     /**
      * Path or URL to the Swagger specification file (JSON or YAML).
@@ -106,6 +118,21 @@ export interface ClientOptions {
             [key: string]: 'optional' | 'required' | 'ignore';
         };
     };
+    /** Excludes specific operations from code generation by tag or operationId */
+    exclude?: ExcludeOptions;
+    /**
+     * Controls the shape of the value each generated operation returns.
+     * - `undefined` (default) — leave each template's current return shape untouched
+     *   (non-breaking). axios/xior return their full native response, while
+     *   fetch/ky/ng return the response body only.
+     * - `'body'` — standardize every template to return just the response body (`T`).
+     * - `'full'` — standardize every template to return a unified `APIResponse<T>`
+     *   wrapper exposing `data`, `headers` (template-native type) and `statusCode`.
+     *
+     * Any explicit value (`'body'` or `'full'`) is a deliberate, potentially
+     * breaking change relative to the template's default return shape.
+     */
+    responseShape?: ResponseShape;
 }
 export interface CliOptions extends Omit<FullAppOptions, 'enumNamesStyle'> {
     allowDots?: boolean;
@@ -150,6 +177,12 @@ export type SchemaDeclarationStyle = 'interface' | 'type';
 export type EnumDeclarationStyle = 'union' | 'enum';
 export type EnumNamesStyle = 'original' | 'PascalCase';
 export type TestingFramework = 'vitest' | 'jest';
+/**
+ * Controls the shape of the value each generated operation returns.
+ * `'body'` returns the response body (`T`); `'full'` returns an `APIResponse<T>`
+ * wrapper. When unset, each template keeps its current default return shape.
+ */
+export type ResponseShape = 'body' | 'full';
 /**
  * Internal options type used throughout the app after `prepareAppOptions` has run.
  * All fields that have defaults are required here so the rest of the codebase never

package/dist/utils/templateValidator.js

@@ -1,5 +1,11 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
+
+
+
+
+
+
 const L1_TEMPLATES = ['axios', 'fetch', 'xior', 'ng1', 'ng2', 'ky'];
 const L2_TEMPLATES = ['swr', 'tsq'];
 
@@ -138,11 +144,24 @@ const DEFAULT_L1_FOR_L2 = 'fetch';
  * The returned string is appended after the client call expression:
  *   `client.method(...args)` + responseMapper
  *
- * Examples:
+ * When `responseShape` is set (`'body'` or `'full'`), every L1 operation already
+ * resolves to the final shape (`T` or `APIResponse<T>`), so no extra mapping is
+ * needed and this returns an empty string regardless of the L1 template.
+ *
+ * Examples (responseShape unset):
  *   axios/xior → `.then((resp) => resp.data)`
  *   fetch/ky   → ``  (empty — the promise already resolves to T)
  */
- function getResponseMapper(template) {
+ function getResponseMapper(
+  template,
+  responseShape
+) {
+  // When the response shape is standardized, the L1 operation already returns
+  // the final value (body or APIResponse wrapper) — no unwrapping needed.
+  if (responseShape) {
+    return '';
+  }
+
   const l1 = getL1Template(template);
   switch (l1) {
     case 'fetch':

package/package.json

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

package/templates/axios/baseClient.ejs

@@ -1,4 +1,4 @@
-import Axios, { type AxiosPromise, type AxiosRequestConfig } from "axios";
+import Axios, { type AxiosPromise, type AxiosRequestConfig<% if (it.responseShape === 'full') { %>, type AxiosResponse<% } %> } from "axios";
 
 export const axios = Axios.create({
   baseURL: '<%= it.baseUrl || '' %>',
@@ -8,4 +8,11 @@ export const axios = Axios.create({
       arrayFormat: '<%= it.arrayFormat %>',
     }),
 });
+<% if (it.responseShape === 'full') { %>
+export interface <%= it.apiResponseType %><T> {
+  data: T;
+  headers: AxiosResponse<T>['headers'];
+  status: number;
+}
+<% } %>
 

package/templates/axios/operation.ejs

@@ -1,10 +1,22 @@
+<%
+var returnTypeWrapped = 'AxiosPromise<' + it.returnType + '>';
+var responseMapper = '';
+if (it.responseShape === 'full') {
+  // AxiosResponse<T> already exposes { data, headers, status } and is therefore
+  // structurally assignable to APIResponse<T> — no remap needed.
+  returnTypeWrapped = 'Promise<' + it.apiResponseType + '<' + it.returnType + '>>';
+} else if (it.responseShape === 'body') {
+  returnTypeWrapped = 'Promise<' + it.returnType + '>';
+  responseMapper = '.then((resp) => resp.data)';
+}
+%>
 <%~ it.jsDocs %>
 
   <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>
 $config?: AxiosRequestConfig
-  ): AxiosPromise<<%~ it.returnType %>> {
+  ): <%~ returnTypeWrapped %> {
     const url = `<%= it.url %>`;
 
     return axios.request<<%~ it.returnType %>>({
@@ -40,5 +52,5 @@ $config?: AxiosRequestConfig
       },
 <% } -%>
       ...$config,
-    });
+    })<%~ responseMapper %>;
   },

package/templates/fetch/baseClient.ejs

@@ -6,4 +6,11 @@ export const defaults = {
       arrayFormat: '<%= it.arrayFormat %>',
     }),
 };
+<% if (it.responseShape === 'full') { %>
+export interface <%= it.apiResponseType %><T> {
+  data: T;
+  headers: Headers;
+  status: number;
+}
+<% } %>
 

package/templates/fetch/operation.ejs

@@ -1,10 +1,16 @@
+<%
+var parseMethod = it.responseContentType === 'binary' ? 'blob' : (it.responseContentType === 'text' ? 'text' : 'json');
+var returnTypeWrapped = it.responseShape === 'full'
+  ? 'Promise<' + it.apiResponseType + '<' + it.returnType + '>>'
+  : 'Promise<' + it.returnType + '>';
+%>
 <%~ it.jsDocs %>
 
   <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>
 $config?: RequestInit
-  ): Promise<<%~ it.returnType %>> {
+  ): <%~ returnTypeWrapped %> {
     const url = `${defaults.baseUrl}<%= it.url %>?<%
     if(it.query && it.query.length > 0) { %>${defaults.paramsSerializer({<%
       it.query.forEach((parameter) => { %>
@@ -59,11 +65,13 @@ $config?: RequestInit
       ...$config,
     })
 <% } %>
-<% if(it.responseContentType === 'binary') { %>
-    .then((response) => response.blob() as Promise<<%~ it.returnType %>>);
-<% } else if(it.responseContentType === 'text') { %>
-    .then((response) => response.text() as Promise<<%~ it.returnType %>>);
+<% if (it.responseShape === 'full') { %>
+    .then(async (response) => ({
+      data: (await response.<%= parseMethod %>()) as <%~ it.returnType %>,
+      headers: response.headers,
+      status: response.status,
+    }));
 <% } else { %>
-    .then((response) => response.json() as Promise<<%~ it.returnType %>>);
+    .then((response) => response.<%= parseMethod %>() as Promise<<%~ it.returnType %>>);
 <% } %>
   },

package/templates/ky/baseClient.ejs

@@ -3,3 +3,10 @@ import ky, { type Options as KyOptions } from 'ky';
 export const http = ky.create({
   prefix: '<%= it.baseUrl || '' %>',
 });
+<% if (it.responseShape === 'full') { %>
+export interface <%= it.apiResponseType %><T> {
+  data: T;
+  headers: Headers;
+  status: number;
+}
+<% } %>

package/templates/ky/baseClientWithSetup.ejs

@@ -32,3 +32,10 @@ export function getKyHttp(): KyInstance {
   }
   return _http;
 }
+<% if (it.responseShape === 'full') { %>
+export interface <%= it.apiResponseType %><T> {
+  data: T;
+  headers: Headers;
+  status: number;
+}
+<% } %>

package/templates/ky/operation.ejs

@@ -1,10 +1,16 @@
+<%
+var parseMethod = it.responseContentType === 'binary' ? 'blob' : (it.responseContentType === 'text' ? 'text' : 'json');
+var returnTypeWrapped = it.responseShape === 'full'
+  ? 'Promise<' + it.apiResponseType + '<' + it.returnType + '>>'
+  : 'Promise<' + it.returnType + '>';
+%>
 <%~ it.jsDocs %>
 
   <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>
 $config?: KyOptions
-  ): Promise<<%~ it.returnType %>> {
+  ): <%~ returnTypeWrapped %> {
     const url = `<%= it.url.replace(/^\//, '') %>`;
 
     return <%= it.httpAccessor %>.<%= it.method.toLowerCase() %>(url, {
@@ -40,7 +46,13 @@ $config?: KyOptions
       },
 <% } -%>
       ...$config,
-<% if(it.responseContentType === 'binary') { -%>
+<% if (it.responseShape === 'full') { -%>
+    }).then(async (response) => ({
+      data: (await response.<%= parseMethod %>()) as <%~ it.returnType %>,
+      headers: response.headers,
+      status: response.status,
+    }));
+<% } else if(it.responseContentType === 'binary') { -%>
     }).blob() as Promise<<%~ it.returnType %>>;
 <% } else if(it.responseContentType === 'text') { -%>
     }).text() as Promise<<%~ it.returnType %>>;

package/templates/ng1/baseClient.ejs

@@ -1,4 +1,4 @@
-import type { IHttpService, IRequestShortcutConfig, IPromise } from 'angular';
+import type { IHttpService, IRequestShortcutConfig, IPromise<% if (it.responseShape === 'full') { %>, IHttpHeadersGetter<% } %> } from 'angular';
 
 abstract class BaseService {
   constructor(protected readonly $http: IHttpService, public baseUrl: string) { }
@@ -88,6 +88,63 @@ abstract class BaseService {
       });
   }
 
+<% if (it.responseShape === 'full') { %>
+  protected $getFull<T>(
+    url: string,
+    config?: IRequestShortcutConfig
+  ): IPromise<<%= it.apiResponseType %><T>> {
+    return this.$http.get(this.baseUrl + url, config).then((response: any) => this.processFull<T>(response));
+  }
+
+  protected $deleteFull<T>(
+    url: string,
+    config?: IRequestShortcutConfig
+  ): IPromise<<%= it.apiResponseType %><T>> {
+    return this.$http.delete(this.baseUrl + url, config).then((response: any) => this.processFull<T>(response));
+  }
+
+  protected $headFull<T>(
+    url: string,
+    config?: IRequestShortcutConfig
+  ): IPromise<<%= it.apiResponseType %><T>> {
+    return this.$http.head(this.baseUrl + url, config).then((response: any) => this.processFull<T>(response));
+  }
+
+  protected $jsonpFull<T>(
+    url: string,
+    config?: IRequestShortcutConfig
+  ): IPromise<<%= it.apiResponseType %><T>> {
+    return this.$http.jsonp(this.baseUrl + url, config).then((response: any) => this.processFull<T>(response));
+  }
+
+  protected $postFull<T>(
+    url: string,
+    data: any,
+    config?: IRequestShortcutConfig
+  ): IPromise<<%= it.apiResponseType %><T>> {
+    return this.$http.post(this.baseUrl + url, data, config).then((response: any) => this.processFull<T>(response));
+  }
+
+  protected $putFull<T>(
+    url: string,
+    data: any,
+    config?: IRequestShortcutConfig
+  ): IPromise<<%= it.apiResponseType %><T>> {
+    return this.$http.put(this.baseUrl + url, data, config).then((response: any) => this.processFull<T>(response));
+  }
+
+  protected $patchFull<T>(
+    url: string,
+    data: any,
+    config?: IRequestShortcutConfig
+  ): IPromise<<%= it.apiResponseType %><T>> {
+    return this.$http.patch(this.baseUrl + url, data, config).then((response: any) => this.processFull<T>(response));
+  }
+
+  protected processFull<T>(response: any): <%= it.apiResponseType %><T> {
+    return { data: response.data, headers: response.headers, status: response.status };
+  }
+<% } %>
   protected processSingle<T>(response: any): T {
     var data = response.data;
     var status = response.status;
@@ -110,4 +167,11 @@ abstract class BaseService {
     }
   }
 }
+<% if (it.responseShape === 'full') { %>
+export interface <%= it.apiResponseType %><T> {
+  data: T;
+  headers: IHttpHeadersGetter;
+  status: number;
+}
+<% } %>
 

package/templates/ng1/operation.ejs

@@ -4,7 +4,7 @@
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>
     config?: IRequestShortcutConfig
-  ): IPromise<<%~ it.returnType %>> {
+  ): <%~ it.responseShape === 'full' ? 'IPromise<' + it.apiResponseType + '<' + it.returnType + '>>' : 'IPromise<' + it.returnType + '>' %> {
     let url = `<%= it.url %>?`;
 <% if(it.query && it.query.length > 0) { %>
   <% it.query.forEach((parameter) => { %>
@@ -26,7 +26,7 @@
       config = { ...config, headers: { ...config?.headers, '<%= parameter.originalName %>': <%= parameter.name %> } };
     }
 <% } %><% }); } %>
-    return this.$<%= it.method.toLowerCase() %>(
+    return this.$<%= it.method.toLowerCase() %><%= it.responseShape === 'full' ? 'Full' : '' %>(
       url,
 <% if(['POST', 'PUT', 'PATCH'].includes(it.method)) { %>
   <% if(it.body) { %>

package/templates/ng2/baseClient.ejs

@@ -1,5 +1,6 @@
 import type { Observable } from "rxjs";
-import { Injectable, InjectionToken, inject } from "@angular/core";
+<% if (it.responseShape === 'full') { %>import { map } from "rxjs/operators";
+<% } %>import { Injectable, InjectionToken, inject } from "@angular/core";
 import { HttpClient, type HttpContext, type HttpHeaders, type HttpParams } from "@angular/common/http";
 
 export const <%= (it.servicePrefix || 'API').toUpperCase() -%>_BASE_URL = new InjectionToken<string>("<%= (it.servicePrefix || 'API').toUpperCase() -%>_BASE_URL");
@@ -19,4 +20,11 @@ function paramsSerializer(params: any) {
     arrayFormat: '<%= it.arrayFormat %>',
   });
 }
+<% if (it.responseShape === 'full') { %>
+export interface <%= it.apiResponseType %><T> {
+  data: T;
+  headers: HttpHeaders;
+  status: number;
+}
+<% } %>
 

package/templates/ng2/operation.ejs

@@ -5,7 +5,7 @@
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>
 config?: HttpConfig
-  ): Observable<<%~ it.returnType %>> {
+  ): <%~ it.responseShape === 'full' ? 'Observable<' + it.apiResponseType + '<' + it.returnType + '>>' : 'Observable<' + it.returnType + '>' %> {
 <% if(it.query && it.query.length > 0) { -%>
     const params = paramsSerializer({
 <% it.query.forEach((parameter) => { -%>
@@ -29,15 +29,27 @@ config?: HttpConfig
     }
 <% } -%>
 <% }); } -%>
+<%
+var fullMap = '.pipe(\n      map((response) => ({ data: response.body as ' + it.returnType + ', headers: response.headers, status: response.status }))\n    )';
+var bodyArg = it.body
+  ? (it.body.contentType === 'urlencoded' ? 'new URLSearchParams(' + it.body.name + ' as any)' : it.body.name)
+  : 'null';
+-%>
+<% if (it.responseShape === 'full') { -%>
+<% if(it.method === 'GET') { -%>
+    return this.http.get<<%~ it.returnType %>>(this.baseUrl + url, { ...config, observe: 'response' as const })<%~ fullMap %>;
+<% } else if(it.method === 'DELETE') { -%>
+    return this.http.delete<<%~ it.returnType %>>(this.baseUrl + url, { ...config, observe: 'response' as const })<%~ fullMap %>;
+<% } else if(['POST', 'PUT', 'PATCH'].includes(it.method)) { -%>
+    return this.http.<%= it.method.toLowerCase() %><%~ '<' + it.returnType + '>' %>(this.baseUrl + url, <%~ bodyArg %>, { ...config, observe: 'response' as const })<%~ fullMap %>;
+<% } -%>
+<% } else { -%>
 <% if(it.method === 'GET') { -%>
     return this.http.get<<%~ it.returnType %>>(this.baseUrl + url, config);
 <% } else if(it.method === 'DELETE') { -%>
     return this.http.delete<<%~ it.returnType %>>(this.baseUrl + url, config);
-<% } else if(['POST', 'PUT', 'PATCH'].includes(it.method)) {
-  const bodyArg = it.body
-    ? (it.body.contentType === 'urlencoded' ? 'new URLSearchParams(' + it.body.name + ' as any)' : it.body.name)
-    : 'null';
--%>
+<% } else if(['POST', 'PUT', 'PATCH'].includes(it.method)) { -%>
     return this.http.<%= it.method.toLowerCase() %><%~ '<' + it.returnType + '>' %>(this.baseUrl + url, <%~ bodyArg %>, config);
-<% } %>
+<% } -%>
+<% } -%>
   }

package/templates/swr/baseClient.ejs

@@ -1,7 +1,7 @@
-import useSWR, { type SWRConfiguration, type Key } from 'swr';
+import useSWR, { type SWRConfiguration, type Key as SWRKey } from 'swr';
 import useSWRMutation, { type SWRMutationConfiguration } from 'swr/mutation';
 
 interface SwrConfig extends SWRConfiguration {
   /* 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. */
-  key?: Key;
+  key?: SWRKey;
 }

package/templates/swr/client.ejs

@@ -21,6 +21,8 @@ export const <%= it.hooksCamelCaseName %> = {
     httpClientName: it.camelCaseName,
     httpConfigType: it.httpConfigType,
     responseMapper: it.responseMapper,
+    responseShape: it.responseShape,
+    apiResponseType: it.apiResponseType,
   }, it.safeOperation(operation, it.camelCaseName));
 %>
 <%~ include('swrOperation.ejs', swrOperation); %>
@@ -37,6 +39,8 @@ export const <%= it.hooksCamelCaseName %> = {
     httpClientName: it.camelCaseName,
     httpConfigType: it.httpConfigType,
     responseMapper: it.responseMapper,
+    responseShape: it.responseShape,
+    apiResponseType: it.apiResponseType,
   }, it.safeOperation(operation, it.camelCaseName));
 %>
 <%~ include('swrMutationOperation.ejs', swrMutationOperation); %>

package/templates/swr/hooksClient.ejs

@@ -15,6 +15,8 @@ export const <%= it.hooksCamelCaseName %> = {
     httpClientName: httpClientPrefix,
     httpConfigType: it.httpConfigType,
     responseMapper: it.responseMapper,
+    responseShape: it.responseShape,
+    apiResponseType: it.prefixApiType(it.apiResponseType),
     returnType: it.prefixApiType(safe.returnType),
     parameters: safe.parameters.map(function(p) {
       return Object.assign({}, p, { type: it.prefixApiType(p.type) });
@@ -36,6 +38,8 @@ export const <%= it.hooksCamelCaseName %> = {
     httpClientName: httpClientPrefix,
     httpConfigType: it.httpConfigType,
     responseMapper: it.responseMapper,
+    responseShape: it.responseShape,
+    apiResponseType: it.prefixApiType(it.apiResponseType),
     returnType: it.prefixApiType(safe.returnType),
     parameters: safe.parameters.map(function(p) {
       return Object.assign({}, p, { type: it.prefixApiType(p.type) });

package/templates/swr/swrMutationOperation.ejs

@@ -18,13 +18,14 @@ var swrKey = it.url.replace(/\$\{(?:[^{}]|\{[^{}]*\})*\}/g, '*');
 
 var docs = it.jsDocs ? it.jsDocs.replace(/^/gm, '  ') + '\n' : '';
 var httpClientName = it.httpClientName || it.clientName;
+var dataType = it.responseShape === 'full' ? it.apiResponseType + '<' + it.returnType + '>' : it.returnType;
 %>
 <%~ docs %>
     <%= it.mutOpName %>(
-      $config?: SWRMutationConfiguration<<%~ it.returnType %>, Error, string, <%~ variablesType %>>,
+      $config?: SWRMutationConfiguration<<%~ dataType %>, Error, string, <%~ variablesType %>>,
       $httpConfig?: <%= it.httpConfigType %>
     ) {
-      return useSWRMutation<<%~ it.returnType %>, Error, string, <%~ variablesType %>>(
+      return useSWRMutation<<%~ dataType %>, Error, string, <%~ variablesType %>>(
         '<%= swrKey %>',
         (_key: string, { arg }<%~ hasParams ? ': { arg: ' + variablesType + ' }' : '' %>) =>
           <%= httpClientName %>Client.<%= it.name %>(<%= callArgs.join(', ') %><%= callArgs.length > 0 ? ', ' : '' %>$httpConfig)<%~ it.responseMapper %>,

package/templates/swr/swrOperation.ejs

@@ -1,15 +1,16 @@
 <% var docs = it.jsDocs ? it.jsDocs.replace(/^/gm, '  ') + '\n' : ''; %>
 <% var httpClientName = it.httpClientName || it.clientName; %>
+<% var dataType = it.responseShape === 'full' ? it.apiResponseType + '<' + it.returnType + '>' : it.returnType; %>
 <%~ docs %>
     <%= it.swrOpName %>(
 <% it.parameters.forEach((parameter) => { %>      <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>,
-<% }); %>      $config?: Omit<SwrConfig, 'key'> & { key?: Key },
+<% }); %>      $config?: Omit<SwrConfig, 'key'> & { key?: SWRKey },
       $httpConfig?: <%= it.httpConfigType %>
     ) {
       const { key, ...config } = $config || {};
       const cacheUrl = key ?? <%= it.clientName %>.queryKeys.<%= it.swrOpName.charAt(3).toLowerCase() + it.swrOpName.slice(4) %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>);
 
-      const { data, error, isLoading, isValidating, mutate } = useSWR<<%~ it.returnType %>>(
+      const { data, error, isLoading, isValidating, mutate } = useSWR<<%~ dataType %>>(
         cacheUrl,
         () => <%= httpClientName %>Client.<%= it.name %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>$httpConfig)<%~ it.responseMapper %>,
         config

package/templates/tsq/client.ejs

@@ -22,6 +22,8 @@ export const <%= it.hooksCamelCaseName %> = {
     httpClientName: it.camelCaseName,
     httpConfigType: it.httpConfigType,
     responseMapper: it.responseMapper,
+    responseShape: it.responseShape,
+    apiResponseType: it.apiResponseType,
   }, it.safeOperation(operation, it.camelCaseName));
 %>
 <%~ include('queryOperation.ejs', queryOperation); %>
@@ -38,6 +40,8 @@ export const <%= it.hooksCamelCaseName %> = {
     httpClientName: it.camelCaseName,
     httpConfigType: it.httpConfigType,
     responseMapper: it.responseMapper,
+    responseShape: it.responseShape,
+    apiResponseType: it.apiResponseType,
   }, it.safeOperation(operation, it.camelCaseName));
 %>
 <%~ include('mutationOperation.ejs', mutationOperation); %>

package/templates/tsq/hooksClient.ejs

@@ -16,6 +16,8 @@ export const <%= it.hooksCamelCaseName %> = {
     httpClientName: httpClientPrefix,
     httpConfigType: it.httpConfigType,
     responseMapper: it.responseMapper,
+    responseShape: it.responseShape,
+    apiResponseType: it.prefixApiType(it.apiResponseType),
     returnType: it.prefixApiType(safe.returnType),
     parameters: safe.parameters.map(function(p) {
       return Object.assign({}, p, { type: it.prefixApiType(p.type) });
@@ -37,6 +39,8 @@ export const <%= it.hooksCamelCaseName %> = {
     httpClientName: httpClientPrefix,
     httpConfigType: it.httpConfigType,
     responseMapper: it.responseMapper,
+    responseShape: it.responseShape,
+    apiResponseType: it.prefixApiType(it.apiResponseType),
     returnType: it.prefixApiType(safe.returnType),
     parameters: safe.parameters.map(function(p) {
       return Object.assign({}, p, { type: it.prefixApiType(p.type) });

package/templates/tsq/mutationOperation.ejs

@@ -19,13 +19,14 @@ var rawDocs = it.jsDocs
   : '';
 var docs = rawDocs ? rawDocs.replace(/^/gm, '  ') + '\n' : '';
 var httpClientName = it.httpClientName || it.clientName;
+var dataType = it.responseShape === 'full' ? it.apiResponseType + '<' + it.returnType + '>' : it.returnType;
 %>
 <%~ docs %>
-    <%= it.mutOpName %><TData = <%~ it.returnType %>, TError = Error>(
-      $config?: UseMutationOptions<<%~ it.returnType %>, TError, <%~ variablesType %>>,
+    <%= it.mutOpName %><TData = <%~ dataType %>, TError = Error>(
+      $config?: UseMutationOptions<<%~ dataType %>, TError, <%~ variablesType %>>,
       $httpConfig?: <%= it.httpConfigType %>
     ) {
-      return useMutation<<%~ it.returnType %>, TError, <%~ variablesType %>>({
+      return useMutation<<%~ dataType %>, TError, <%~ variablesType %>>({
         mutationFn: (<%= hasParams ? 'vars' : '' %>) => <%= httpClientName %>Client.<%= it.name %>(<%= callArgs.join(', ') %><%= callArgs.length > 0 ? ', ' : '' %>$httpConfig)<%~ it.responseMapper %>,
         ...$config
       });

package/templates/tsq/queryOperation.ejs

@@ -5,14 +5,15 @@ var rawDocs = it.jsDocs
   : '';
 var docs = rawDocs ? rawDocs.replace(/^/gm, '  ') + '\n' : '';
 var httpClientName = it.httpClientName || it.clientName;
+var dataType = it.responseShape === 'full' ? it.apiResponseType + '<' + it.returnType + '>' : it.returnType;
 %>
 <%~ docs %>
-    <%= it.rqOpName %><TData = <%~ it.returnType %>, TError = Error>(
+    <%= it.rqOpName %><TData = <%~ dataType %>, TError = Error>(
 <% it.parameters.forEach((parameter) => { %>      <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %><%= parameter.optional ? (parameter.skippable ? ' | null' : ' | null | undefined') : '' %>,
-<% }); %>      $config?: Omit<UseQueryOptions<<%~ it.returnType %>, TError, TData>, 'queryKey' | 'queryFn'>,
+<% }); %>      $config?: Omit<UseQueryOptions<<%~ dataType %>, TError, TData>, 'queryKey' | 'queryFn'>,
       $httpConfig?: <%= it.httpConfigType %>
     ) {
-      return useQuery<<%~ it.returnType %>, TError, TData>({
+      return useQuery<<%~ dataType %>, TError, TData>({
         queryKey: <%= it.clientName %>.queryKeys.<%= it.rqOpName.charAt(3).toLowerCase() + it.rqOpName.slice(4) %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>),
         queryFn: () => <%= httpClientName %>Client.<%= it.name %>(<% it.parameters.forEach((parameter) => { %><%= parameter.name %>, <% }); %>$httpConfig)<%~ it.responseMapper %>,
         ...$config

package/templates/xior/baseClient.ejs

@@ -8,4 +8,11 @@ export const http = xior.create({
       arrayFormat: '<%= it.arrayFormat %>',
     }),
 });
+<% if (it.responseShape === 'full') { %>
+export interface <%= it.apiResponseType %><T> {
+  data: T;
+  headers: XiorResponse<T>['headers'];
+  status: number;
+}
+<% } %>
 

package/templates/xior/operation.ejs

@@ -1,10 +1,22 @@
+<%
+var returnTypeWrapped = 'Promise<XiorResponse<' + it.returnType + '>>';
+var responseMapper = '';
+if (it.responseShape === 'full') {
+  // XiorResponse<T> already exposes { data, headers, status } and is therefore
+  // structurally assignable to APIResponse<T> — no remap needed.
+  returnTypeWrapped = 'Promise<' + it.apiResponseType + '<' + it.returnType + '>>';
+} else if (it.responseShape === 'body') {
+  returnTypeWrapped = 'Promise<' + it.returnType + '>';
+  responseMapper = '.then((resp) => resp.data)';
+}
+%>
 <%~ it.jsDocs %>
 
   <%= it.name %>(<% it.parameters.forEach((parameter) => { %>
 <%= parameter.name %><%= parameter.skippable ? '?' : '' %>: <%~ parameter.type %> <%= parameter.optional ? (parameter.skippable ? '| null' : '| null | undefined') : '' %>,
     <% }); %>
 $config?: XiorRequestConfig
-  ): Promise<XiorResponse<<%~ it.returnType %>>> {
+  ): <%~ returnTypeWrapped %> {
     const url = `<%= it.url %>`;
 
     return http.request<<%~ it.returnType %>>({
@@ -40,5 +52,5 @@ $config?: XiorRequestConfig
       },
 <% } -%>
       ...$config,
-    });
+    })<%~ responseMapper %>;
   },