@kubb/plugin-client 5.0.0-beta.22 → 5.0.0-beta.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-client",
-  "version": "5.0.0-beta.22",
+  "version": "5.0.0-beta.27",
   "description": "Generate type-safe HTTP clients from your OpenAPI specification. Supports Axios, Fetch, and custom client adapters with full TypeScript inference and zero boilerplate.",
   "keywords": [
     "api-client",
@@ -87,10 +87,10 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.22",
-    "@kubb/renderer-jsx": "5.0.0-beta.22",
-    "@kubb/plugin-ts": "5.0.0-beta.22",
-    "@kubb/plugin-zod": "5.0.0-beta.22"
+    "@kubb/core": "5.0.0-beta.27",
+    "@kubb/renderer-jsx": "5.0.0-beta.27",
+    "@kubb/plugin-ts": "5.0.0-beta.27",
+    "@kubb/plugin-zod": "5.0.0-beta.27"
   },
   "devDependencies": {
     "axios": "^1.16.1",
@@ -98,7 +98,7 @@
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.22",
+    "@kubb/renderer-jsx": "5.0.0-beta.27",
     "axios": "^1.7.2"
   },
   "peerDependenciesMeta": {

package/src/clients/axios.ts

@@ -4,6 +4,13 @@ import axios from 'axios'
 declare const AXIOS_BASE: string
 declare const AXIOS_HEADERS: string
 
+/**
+ * Header values may be objects (e.g. JSON-encoded headers like `X-Filter` in the Linode API).
+ * Non-string values are JSON-serialized before the request is sent.
+ */
+export type HeaderValue = string | number | boolean | null | undefined | object
+export type HeadersInit = Array<[string, HeaderValue]> | Record<string, HeaderValue>
+
 /**
  * Subset of AxiosRequestConfig
  */
@@ -16,7 +23,7 @@ export type RequestConfig<TData = unknown> = {
   responseType?: 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'
   signal?: AbortSignal
   validateStatus?: (status: number) => boolean
-  headers?: AxiosRequestConfig['headers']
+  headers?: HeadersInit
   paramsSerializer?: AxiosRequestConfig['paramsSerializer']
   contentType?: string
 }
@@ -56,14 +63,30 @@ export const mergeConfig = <T extends RequestConfig>(...configs: Array<Partial<T
       ...merged,
       ...config,
       headers: {
-        ...merged.headers,
-        ...config.headers,
+        ...(Array.isArray(merged.headers) ? Object.fromEntries(merged.headers) : merged.headers),
+        ...(Array.isArray(config.headers) ? Object.fromEntries(config.headers) : config.headers),
       },
     }
   }, {})
 }
 
-export const axiosInstance = axios.create(getConfig())
+/**
+ * Serializes header values into the string form axios ultimately puts on the wire.
+ * Objects (including arrays) are JSON-stringified so spec-defined object headers like `X-Filter`
+ * are sent in their canonical JSON-string form rather than `[object Object]`.
+ */
+function serializeHeaders(headers: HeadersInit | undefined): Record<string, string> {
+  if (!headers) return {}
+  const entries = Array.isArray(headers) ? headers : Object.entries(headers)
+  const result: Record<string, string> = {}
+  for (const [key, value] of entries) {
+    if (value === undefined || value === null) continue
+    result[key] = typeof value === 'string' ? value : typeof value === 'object' ? JSON.stringify(value) : String(value)
+  }
+  return result
+}
+
+export const axiosInstance = axios.create(getConfig() as AxiosRequestConfig)
 
 export const client = async <TResponseData, TError = unknown, TRequestData = unknown>(
   config: RequestConfig<TRequestData>,
@@ -76,7 +99,7 @@ export const client = async <TResponseData, TError = unknown, TRequestData = unk
       ...axiosConfig,
       headers: {
         ...(contentType && contentType !== 'multipart/form-data' ? { 'Content-Type': contentType } : {}),
-        ...headers,
+        ...serializeHeaders(headers),
       },
     })
     .catch((e: AxiosError<TError>) => {

package/src/clients/fetch.ts

@@ -3,6 +3,13 @@
  */
 export type RequestCredentials = 'omit' | 'same-origin' | 'include'
 
+/**
+ * Header values may be objects (e.g. JSON-encoded filter headers like `X-Filter`).
+ * Non-string values are JSON-serialized before the request is sent.
+ */
+export type HeaderValue = string | number | boolean | null | undefined | object
+export type HeadersInit = Array<[string, HeaderValue]> | Record<string, HeaderValue>
+
 /**
  * Subset of FetchRequestConfig
  */
@@ -14,7 +21,7 @@ export type RequestConfig<TData = unknown> = {
   data?: TData | FormData
   responseType?: 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'
   signal?: AbortSignal
-  headers?: [string, string][] | Record<string, string>
+  headers?: HeadersInit
   credentials?: RequestCredentials
   contentType?: string
 }
@@ -51,6 +58,22 @@ export const mergeConfig = <T extends RequestConfig>(...configs: Array<Partial<T
   }, {})
 }
 
+/**
+ * Serializes header values into the string form `fetch` expects.
+ * Objects (including arrays) are JSON-stringified so spec-defined object
+ * headers like `X-Filter` are sent in their canonical JSON-string form.
+ */
+function serializeHeaders(headers: HeadersInit | undefined): Record<string, string> {
+  if (!headers) return {}
+  const entries = Array.isArray(headers) ? headers : Object.entries(headers)
+  const result: Record<string, string> = {}
+  for (const [key, value] of entries) {
+    if (value === undefined || value === null) continue
+    result[key] = typeof value === 'string' ? value : typeof value === 'object' ? JSON.stringify(value) : String(value)
+  }
+  return result
+}
+
 export type ResponseErrorConfig<TError = unknown> = TError
 
 export type Client = <TResponseData, _TError = unknown, TRequestData = unknown>(
@@ -85,7 +108,7 @@ export const client = async <TResponseData, _TError = unknown, RequestData = unk
     signal: config.signal,
     headers: {
       ...(config.contentType && config.contentType !== 'multipart/form-data' ? { 'Content-Type': config.contentType } : {}),
-      ...(Array.isArray(config.headers) ? Object.fromEntries(config.headers) : config.headers),
+      ...serializeHeaders(config.headers),
     },
   })
 

package/src/components/ClassClient.tsx

@@ -14,7 +14,7 @@ type OperationData = {
   node: ast.OperationNode
   name: string
   tsResolver: ResolverTs
-  zodResolver?: ResolverZod
+  zodResolver?: ResolverZod | null
 }
 
 type Props = {
@@ -35,7 +35,7 @@ type GenerateMethodProps = {
   node: ast.OperationNode
   name: string
   tsResolver: ResolverTs
-  zodResolver?: ResolverZod
+  zodResolver?: ResolverZod | null
   baseURL: string | null | undefined
   dataReturnType: PluginClient['resolvedOptions']['dataReturnType']
   parser: PluginClient['resolvedOptions']['parser'] | undefined
@@ -62,7 +62,7 @@ function generateMethod({
   const { defaultContentType: contentType, isMultipleContentTypes, hasFormData } = getContentTypeInfo(node)
   const isFormData = !isMultipleContentTypes && contentType === 'multipart/form-data'
   const { header: headerParams } = getOperationParameters(node)
-  const headerParamsName = headerParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, headerParams[0]!) : undefined
+  const headerParamsName = headerParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, headerParams[0]!) : null
   const headers = isMultipleContentTypes ? (headerParamsName ? ['...headers'] : []) : buildHeaders(contentType, !!headerParamsName)
   const generics = buildGenerics(node, tsResolver)
   const paramsNode = buildClientParamsNode({ paramsType, paramsCasing, pathParamsType, node, tsResolver, isConfigurable: true })

package/src/components/Client.tsx

@@ -1,4 +1,11 @@
-import { buildOperationComments, buildParamsMapping, buildRequestConfigType, getContentTypeInfo, getOperationParameters } from '@internals/shared'
+import {
+  buildOperationComments,
+  buildParamsMapping,
+  buildRequestConfigType,
+  getContentTypeInfo,
+  getOperationParameters,
+  resolveSuccessNames,
+} from '@internals/shared'
 import { isValidVarName, URLPath } from '@internals/utils'
 import { ast } from '@kubb/core'
 import type { ResolverTs } from '@kubb/plugin-ts'
@@ -26,7 +33,7 @@ type Props = {
   parser: PluginClient['resolvedOptions']['parser'] | undefined
   node: ast.OperationNode
   tsResolver: ResolverTs
-  zodResolver?: ResolverZod
+  zodResolver?: ResolverZod | null
   children?: KubbReactNode
 }
 
@@ -96,17 +103,18 @@ export function Client({
   const { path: originalPathParams, query: originalQueryParams, header: originalHeaderParams } = getOperationParameters(node)
   const { path: casedPathParams, query: casedQueryParams, header: casedHeaderParams } = getOperationParameters(node, { paramsCasing })
 
-  const pathParamsMapping = paramsCasing && !urlName ? buildParamsMapping(originalPathParams, casedPathParams) : undefined
-  const queryParamsMapping = paramsCasing ? buildParamsMapping(originalQueryParams, casedQueryParams) : undefined
-  const headerParamsMapping = paramsCasing ? buildParamsMapping(originalHeaderParams, casedHeaderParams) : undefined
+  const pathParamsMapping = paramsCasing && !urlName ? buildParamsMapping(originalPathParams, casedPathParams) : null
+  const queryParamsMapping = paramsCasing ? buildParamsMapping(originalQueryParams, casedQueryParams) : null
+  const headerParamsMapping = paramsCasing ? buildParamsMapping(originalHeaderParams, casedHeaderParams) : null
 
-  const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : undefined
-  const responseName = tsResolver.resolveResponseName(node)
-  const queryParamsName = originalQueryParams.length > 0 ? tsResolver.resolveQueryParamsName(node, originalQueryParams[0]!) : undefined
-  const headerParamsName = originalHeaderParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, originalHeaderParams[0]!) : undefined
+  const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : null
+  const successNames = resolveSuccessNames(node, tsResolver)
+  const responseName = successNames.length > 0 ? successNames.join(' | ') : tsResolver.resolveResponseName(node)
+  const queryParamsName = originalQueryParams.length > 0 ? tsResolver.resolveQueryParamsName(node, originalQueryParams[0]!) : null
+  const headerParamsName = originalHeaderParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, originalHeaderParams[0]!) : null
 
-  const zodResponseName = zodResolver && parser === 'zod' ? zodResolver.resolveResponseName?.(node) : undefined
-  const zodRequestName = zodResolver && parser === 'zod' && node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : undefined
+  const zodResponseName = zodResolver && parser === 'zod' ? zodResolver.resolveResponseName?.(node) : null
+  const zodRequestName = zodResolver && parser === 'zod' && node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : null
 
   const errorNames = node.responses
     .filter((r) => {
@@ -116,8 +124,8 @@ export function Client({
     .map((r) => tsResolver.resolveResponseStatusName(node, r.statusCode))
 
   const headers = [
-    !isMultipleContentTypes && contentType !== 'application/json' && contentType !== 'multipart/form-data' ? `'Content-Type': '${contentType}'` : undefined,
-    headerParamsName ? (headerParamsMapping ? '...mappedHeaders' : '...headers') : undefined,
+    !isMultipleContentTypes && contentType !== 'application/json' && contentType !== 'multipart/form-data' ? `'Content-Type': '${contentType}'` : null,
+    headerParamsName ? (headerParamsMapping ? '...mappedHeaders' : '...headers') : null,
   ].filter(Boolean)
 
   const TError = `ResponseErrorConfig<${errorNames.length > 0 ? errorNames.join(' | ') : 'Error'}>`
@@ -158,8 +166,8 @@ export function Client({
             ? {
                 value: `\`${baseURL}\``,
               }
-            : undefined,
-        params: queryParamsName ? (queryParamsMapping ? { value: 'mappedParams' } : {}) : undefined,
+            : null,
+        params: queryParamsName ? (queryParamsMapping ? { value: 'mappedParams' } : {}) : null,
         data: requestName
           ? {
               value:
@@ -169,18 +177,18 @@ export function Client({
                     ? 'formData as FormData'
                     : 'requestData',
             }
-          : undefined,
-        contentType: isConfigurable && isMultipleContentTypes ? {} : undefined,
+          : null,
+        contentType: isConfigurable && isMultipleContentTypes ? {} : null,
         requestConfig: isConfigurable
           ? {
               mode: 'inlineSpread',
             }
-          : undefined,
+          : null,
         headers: headers.length
           ? {
               value: isConfigurable ? `{ ${headers.join(', ')}, ...requestConfig.headers }` : `{ ${headers.join(', ')} }`,
             }
-          : undefined,
+          : null,
       },
     },
   })

package/src/components/StaticClassClient.tsx

@@ -14,7 +14,7 @@ type OperationData = {
   node: ast.OperationNode
   name: string
   tsResolver: ResolverTs
-  zodResolver?: ResolverZod
+  zodResolver?: ResolverZod | null
 }
 
 type Props = {
@@ -35,7 +35,7 @@ type GenerateMethodProps = {
   node: ast.OperationNode
   name: string
   tsResolver: ResolverTs
-  zodResolver?: ResolverZod
+  zodResolver?: ResolverZod | null
   baseURL: string | null | undefined
   dataReturnType: PluginClient['resolvedOptions']['dataReturnType']
   parser: PluginClient['resolvedOptions']['parser'] | undefined
@@ -62,7 +62,7 @@ function generateMethod({
   const { defaultContentType: contentType, isMultipleContentTypes, hasFormData } = getContentTypeInfo(node)
   const isFormData = !isMultipleContentTypes && contentType === 'multipart/form-data'
   const { header: headerParams } = getOperationParameters(node)
-  const headerParamsName = headerParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, headerParams[0]!) : undefined
+  const headerParamsName = headerParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, headerParams[0]!) : null
   const headers = isMultipleContentTypes ? (headerParamsName ? ['...headers'] : []) : buildHeaders(contentType, !!headerParamsName)
   const generics = buildGenerics(node, tsResolver)
   const paramsNode = buildClientParamsNode({ paramsType, paramsCasing, pathParamsType, node, tsResolver, isConfigurable: true })

package/src/components/Url.tsx

@@ -70,7 +70,7 @@ export function Url({
 
   const { path: originalPathParams } = getOperationParameters(node)
   const { path: casedPathParams } = getOperationParameters(node, { paramsCasing })
-  const pathParamsMapping = paramsCasing ? buildParamsMapping(originalPathParams, casedPathParams) : undefined
+  const pathParamsMapping = paramsCasing ? buildParamsMapping(originalPathParams, casedPathParams) : null
 
   return (
     <File.Source name={name} isExportable={isExportable} isIndexable={isIndexable}>

package/src/functionParams.ts

@@ -11,7 +11,7 @@ type ParamLeaf = {
 
 type ParamGroup = {
   mode: 'object' | 'inlineSpread'
-  children: Record<string, ParamLeaf | undefined>
+  children: Record<string, ParamLeaf | null | undefined>
   default?: string
 }
 
@@ -25,14 +25,14 @@ function isGroup(spec: ParamSpec): spec is ParamGroup {
 }
 
 function createType(type?: string) {
-  return type ? ast.createParamsType({ variant: 'reference', name: type }) : undefined
+  return type ? ast.createParamsType({ variant: 'reference', name: type }) : null
 }
 
 function createDeclarationLeaf(name: string, spec: ParamLeaf): ast.FunctionParameterNode {
   if (spec.default !== undefined) {
     return ast.createFunctionParameter({
       name,
-      type: createType(spec.type),
+      type: createType(spec.type) ?? undefined,
       default: spec.default,
       rest: spec.mode === 'inlineSpread',
     })
@@ -40,7 +40,7 @@ function createDeclarationLeaf(name: string, spec: ParamLeaf): ast.FunctionParam
 
   return ast.createFunctionParameter({
     name,
-    type: createType(spec.type),
+    type: createType(spec.type) ?? undefined,
     optional: !!spec.optional,
     rest: spec.mode === 'inlineSpread',
   })
@@ -52,7 +52,7 @@ function createDeclarationParam(name: string, spec: ParamSpec): ast.FunctionPara
       inline: spec.mode === 'inlineSpread',
       default: spec.default,
       properties: Object.entries(spec.children)
-        .filter(([, child]) => child !== undefined)
+        .filter(([, child]) => child != null)
         .map(([childName, child]) => createDeclarationLeaf(childName, child!)),
     })
   }
@@ -65,7 +65,7 @@ function createCallParam(name: string, spec: ParamSpec): ast.FunctionParameterNo
     return ast.createParameterGroup({
       inline: spec.mode === 'inlineSpread',
       properties: Object.entries(spec.children)
-        .filter(([, child]) => child !== undefined)
+        .filter(([, child]) => child != null)
         .map(([childName, child]) =>
           ast.createFunctionParameter({
             name:
@@ -92,8 +92,8 @@ function createCallParam(name: string, spec: ParamSpec): ast.FunctionParameterNo
  * Creates function parameter builders for generating function signatures and calls.
  * Returns utilities to output constructor signatures (`toConstructor()`) or call expressions (`toCall()`).
  */
-export function createFunctionParams(params: Record<string, ParamSpec | undefined>) {
-  const entries = Object.entries(params).filter(([, spec]) => spec !== undefined) as Array<[string, ParamSpec]>
+export function createFunctionParams(params: Record<string, ParamSpec | null | undefined>) {
+  const entries = Object.entries(params).filter(([, spec]) => spec != null) as Array<[string, ParamSpec]>
 
   return {
     toConstructor() {

package/src/generators/classClientGenerator.tsx

@@ -16,9 +16,9 @@ type OperationData = {
   node: ast.OperationNode
   name: string
   tsResolver: ResolverTs
-  zodResolver: ResolverZod | undefined
+  zodResolver: ResolverZod | null
   typeFile: ast.FileNode
-  zodFile: ast.FileNode | undefined
+  zodFile: ast.FileNode | null
 }
 
 type Controller = {
@@ -33,13 +33,18 @@ function resolveTypeImportNames(node: ast.OperationNode, tsResolver: ResolverTs)
 }
 
 function resolveZodImportNames(node: ast.OperationNode, zodResolver: ResolverZod): Array<string> {
-  const names: Array<string | undefined> = [
+  const names: Array<string | null | undefined> = [
     zodResolver.resolveResponseName?.(node),
-    node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : undefined,
+    node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : null,
   ]
   return names.filter((n): n is string => Boolean(n))
 }
 
+/**
+ * Built-in `operations` generator for `@kubb/plugin-client` when
+ * `clientType: 'class'`. Emits one class per tag, with one instance method
+ * per operation and a shared constructor for request configuration.
+ */
 export const classClientGenerator = defineGenerator<PluginClient>({
   name: 'classClient',
   renderer: jsxRendererSync,
@@ -53,8 +58,8 @@ export const classClientGenerator = defineGenerator<PluginClient>({
 
     const tsResolver = driver.getResolver(pluginTsName)
     const tsPluginOptions = pluginTs.options
-    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : undefined
-    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : undefined
+    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : null
+    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : null
 
     function buildOperationData(node: ast.OperationNode): OperationData {
       const typeFile = tsResolver.resolveFile(
@@ -65,9 +70,9 @@ export const classClientGenerator = defineGenerator<PluginClient>({
         zodResolver && pluginZod?.options
           ? zodResolver.resolveFile(
               { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-              { root, output: pluginZod.options?.output ?? output, group: pluginZod.options?.group },
+              { root, output: pluginZod.options?.output ?? output, group: pluginZod.options?.group ?? undefined },
             )
-          : undefined
+          : null
 
       return {
         node: node,
@@ -85,7 +90,7 @@ export const classClientGenerator = defineGenerator<PluginClient>({
 
       if (!tag && !group) {
         const name = resolver.resolveClassName('ApiClient')
-        const file = resolver.resolveFile({ name, extname: '.ts' }, { root, output, group })
+        const file = resolver.resolveFile({ name, extname: '.ts' }, { root, output, group: group ?? undefined })
         const operationData = buildOperationData(operationNode)
         const previous = acc.find((item) => item.file.path === file.path)
 
@@ -99,7 +104,7 @@ export const classClientGenerator = defineGenerator<PluginClient>({
 
       if (tag) {
         const name = groupName
-        const file = resolver.resolveFile({ name, extname: '.ts', tag }, { root, output, group })
+        const file = resolver.resolveFile({ name, extname: '.ts', tag }, { root, output, group: group ?? undefined })
         const operationData = buildOperationData(operationNode)
         const previous = acc.find((item) => item.file.path === file.path)
 
@@ -215,7 +220,7 @@ export const classClientGenerator = defineGenerator<PluginClient>({
     })
 
     if (sdk) {
-      const sdkFile = resolver.resolveFile({ name: sdk.className, extname: '.ts' }, { root, output, group })
+      const sdkFile = resolver.resolveFile({ name: sdk.className, extname: '.ts' }, { root, output, group: group ?? undefined })
 
       files.push(
         <File

package/src/generators/clientGenerator.tsx

@@ -8,6 +8,11 @@ import { Client } from '../components/Client'
 import { Url } from '../components/Url.tsx'
 import type { PluginClient } from '../types'
 
+/**
+ * Built-in operation generator for `@kubb/plugin-client`. Emits one async
+ * function per OpenAPI operation, plus the matching URL helper. Used when
+ * `clientType: 'function'` (the default).
+ */
 export const clientGenerator = defineGenerator<PluginClient>({
   name: 'client',
   renderer: jsxRendererSync,
@@ -24,14 +29,14 @@ export const clientGenerator = defineGenerator<PluginClient>({
 
     const tsResolver = driver.getResolver(pluginTsName)
 
-    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : undefined
-    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : undefined
+    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : null
+    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : null
 
     const importedTypeNames = resolveOperationTypeNames(node, tsResolver, { paramsCasing })
 
     const importedZodNames =
       zodResolver && parser === 'zod'
-        ? [zodResolver.resolveResponseName?.(node), node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : undefined].filter(
+        ? [zodResolver.resolveResponseName?.(node), node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : null].filter(
             (name): name is string => Boolean(name),
           )
         : []
@@ -39,13 +44,16 @@ export const clientGenerator = defineGenerator<PluginClient>({
     const meta = {
       name: resolver.resolveName(node.operationId),
       urlName: resolver.resolveUrlName(node),
-      file: resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      file: resolver.resolveFile(
+        { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      ),
       fileTs: tsResolver.resolveFile(
         { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
         {
           root,
           output: pluginTs.options?.output ?? output,
-          group: pluginTs.options?.group,
+          group: pluginTs.options?.group ?? undefined,
         },
       ),
       fileZod:
@@ -55,10 +63,10 @@ export const clientGenerator = defineGenerator<PluginClient>({
               {
                 root,
                 output: pluginZod.options.output ?? output,
-                group: pluginZod.options?.group,
+                group: pluginZod.options?.group ?? undefined,
               },
             )
-          : undefined,
+          : null,
     } as const
 
     const hasFormData = node.requestBody?.content?.some((e) => e.contentType === 'multipart/form-data') ?? false
@@ -90,7 +98,7 @@ export const clientGenerator = defineGenerator<PluginClient>({
 
         {hasFormData && <File.Import name={['buildFormData']} root={meta.file.path} path={path.resolve(root, '.kubb/config.ts')} />}
 
-        {meta.fileZod && importedZodNames.length > 0 && <File.Import name={importedZodNames as string[]} root={meta.file.path} path={meta.fileZod.path} />}
+        {meta.fileZod && importedZodNames.length > 0 && <File.Import name={importedZodNames as Array<string>} root={meta.file.path} path={meta.fileZod.path} />}
 
         {meta.fileTs && importedTypeNames.length > 0 && (
           <File.Import name={Array.from(new Set(importedTypeNames))} root={meta.file.path} path={meta.fileTs.path} isTypeOnly />

package/src/generators/groupedClientGenerator.tsx

@@ -4,6 +4,12 @@ import { defineGenerator } from '@kubb/core'
 import { File, Function, jsxRendererSync } from '@kubb/renderer-jsx'
 import type { PluginClient } from '../types'
 
+/**
+ * Emits one aggregate file per tag/group when `group` is configured. Each
+ * file re-exports every client function for that group, so callers can
+ * `import { petController } from './gen/clients'` instead of importing
+ * each operation individually.
+ */
 export const groupedClientGenerator = defineGenerator<PluginClient>({
   name: 'groupedClient',
   renderer: jsxRendererSync,
@@ -15,16 +21,16 @@ export const groupedClientGenerator = defineGenerator<PluginClient>({
       (acc, operationNode) => {
         if (group?.type === 'tag') {
           const tag = operationNode.tags[0]
-          const name = tag ? group?.name?.({ group: camelCase(tag) }) : undefined
+          const name = tag ? group?.name?.({ group: camelCase(tag) }) : null
 
           if (!tag || !name) {
             return acc
           }
 
-          const file = resolver.resolveFile({ name, extname: '.ts', tag }, { root, output, group })
+          const file = resolver.resolveFile({ name, extname: '.ts', tag }, { root, output, group: group ?? undefined })
           const clientFile = resolver.resolveFile(
             { name: operationNode.operationId, extname: '.ts', tag: operationNode.tags[0] ?? 'default', path: operationNode.path },
-            { root, output, group },
+            { root, output, group: group ?? undefined },
           )
 
           const client = {

package/src/generators/operationsGenerator.tsx

@@ -3,6 +3,12 @@ import { File, jsxRendererSync } from '@kubb/renderer-jsx'
 import { Operations } from '../components/Operations'
 import type { PluginClient } from '../types'
 
+/**
+ * Generates an `operations.ts` file that re-exports every operation grouped
+ * by HTTP method. Enabled when `pluginClient({ operations: true })`. Useful
+ * for building meta-tooling on top of the generated client (route
+ * registries, API explorers).
+ */
 export const operationsGenerator = defineGenerator<PluginClient>({
   name: 'client',
   renderer: jsxRendererSync,
@@ -11,7 +17,7 @@ export const operationsGenerator = defineGenerator<PluginClient>({
     const { output, group } = ctx.options
 
     const name = 'operations'
-    const file = resolver.resolveFile({ name, extname: '.ts' }, { root, output, group })
+    const file = resolver.resolveFile({ name, extname: '.ts' }, { root, output, group: group ?? undefined })
 
     return (
       <File

package/src/generators/staticClassClientGenerator.tsx

@@ -15,9 +15,9 @@ type OperationData = {
   node: ast.OperationNode
   name: string
   tsResolver: ResolverTs
-  zodResolver: ResolverZod | undefined
+  zodResolver: ResolverZod | null
   typeFile: ast.FileNode
-  zodFile: ast.FileNode | undefined
+  zodFile: ast.FileNode | null
 }
 
 type Controller = {
@@ -31,13 +31,19 @@ function resolveTypeImportNames(node: ast.OperationNode, tsResolver: ResolverTs)
 }
 
 function resolveZodImportNames(node: ast.OperationNode, zodResolver: ResolverZod): Array<string> {
-  const names: Array<string | undefined> = [
+  const names: Array<string | null | undefined> = [
     zodResolver.resolveResponseName?.(node),
-    node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : undefined,
+    node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : null,
   ]
   return names.filter((n): n is string => Boolean(n))
 }
 
+/**
+ * Built-in `operations` generator for `@kubb/plugin-client` when
+ * `clientType: 'staticClass'`. Emits one class per tag, with a static method
+ * per operation so callers can use `Pet.getPetById(...)` without
+ * instantiating the class.
+ */
 export const staticClassClientGenerator = defineGenerator<PluginClient>({
   name: 'staticClassClient',
   renderer: jsxRendererSync,
@@ -51,8 +57,8 @@ export const staticClassClientGenerator = defineGenerator<PluginClient>({
 
     const tsResolver = driver.getResolver(pluginTsName)
     const tsPluginOptions = pluginTs.options
-    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : undefined
-    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : undefined
+    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : null
+    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : null
 
     function buildOperationData(node: ast.OperationNode): OperationData {
       const typeFile = tsResolver.resolveFile(
@@ -63,9 +69,9 @@ export const staticClassClientGenerator = defineGenerator<PluginClient>({
         zodResolver && pluginZod?.options
           ? zodResolver.resolveFile(
               { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-              { root, output: pluginZod.options?.output ?? output, group: pluginZod.options?.group },
+              { root, output: pluginZod.options?.output ?? output, group: pluginZod.options?.group ?? undefined },
             )
-          : undefined
+          : null
 
       return {
         node: node,
@@ -83,7 +89,7 @@ export const staticClassClientGenerator = defineGenerator<PluginClient>({
 
       if (!tag && !group) {
         const name = resolver.resolveClassName('ApiClient')
-        const file = resolver.resolveFile({ name, extname: '.ts' }, { root, output, group })
+        const file = resolver.resolveFile({ name, extname: '.ts' }, { root, output, group: group ?? undefined })
         const operationData = buildOperationData(operationNode)
         const previous = acc.find((item) => item.file.path === file.path)
 
@@ -97,7 +103,7 @@ export const staticClassClientGenerator = defineGenerator<PluginClient>({
 
       if (tag) {
         const name = groupName
-        const file = resolver.resolveFile({ name, extname: '.ts', tag }, { root, output, group })
+        const file = resolver.resolveFile({ name, extname: '.ts', tag }, { root, output, group: group ?? undefined })
         const operationData = buildOperationData(operationNode)
         const previous = acc.find((item) => item.file.path === file.path)