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

package/src/plugin.ts

@@ -16,20 +16,33 @@ import { source as configSource } from './templates/config.source.ts'
 import type { PluginClient } from './types.ts'
 
 /**
- * Canonical plugin name for `@kubb/plugin-client`, used in driver lookups and warnings.
+ * Canonical plugin name for `@kubb/plugin-client`. Used for driver lookups and
+ * cross-plugin dependency references.
  */
 export const pluginClientName = 'plugin-client' satisfies PluginClient['name']
 
 /**
- * Generates type-safe HTTP client functions or classes from an OpenAPI specification.
- * Creates client APIs by walking operations and delegating to generators.
- * Writes barrel files based on the configured `barrelType`.
+ * Generates one HTTP client function per OpenAPI operation. Each function has
+ * typed path params, query params, body, and response, so callers use the API
+ * like any other typed function. Ships with `axios` and `fetch` runtimes; bring
+ * your own by setting `importPath`.
  *
- * @example Client generator
+ * @example
  * ```ts
- * import pluginClient from '@kubb/plugin-client'
+ * import { defineConfig } from 'kubb'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginClient } from '@kubb/plugin-client'
+ *
  * export default defineConfig({
- *   plugins: [pluginClient({ output: { path: 'clients' } })]
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginClient({
+ *       output: { path: './clients' },
+ *       client: 'fetch',
+ *     }),
+ *   ],
  * })
  * ```
  */
@@ -63,8 +76,8 @@ export const pluginClient = definePlugin<PluginClient>((options) => {
     options.generators ??
     [
       clientType === 'staticClass' ? staticClassClientGenerator : clientType === 'class' ? classClientGenerator : clientGenerator,
-      group && clientType === 'function' ? groupedClientGenerator : undefined,
-      operations ? operationsGenerator : undefined,
+      group && clientType === 'function' ? groupedClientGenerator : null,
+      operations ? operationsGenerator : null,
     ].filter((x): x is NonNullable<typeof x> => Boolean(x))
 
   const groupConfig = group
@@ -79,12 +92,12 @@ export const pluginClient = definePlugin<PluginClient>((options) => {
               return `${camelCase(ctx.group)}Controller`
             },
       } satisfies Group)
-    : undefined
+    : null
 
   return {
     name: pluginClientName,
     options,
-    dependencies: [pluginTsName, parser === 'zod' ? pluginZodName : undefined].filter((dependency): dependency is string => Boolean(dependency)),
+    dependencies: [pluginTsName, parser === 'zod' ? pluginZodName : null].filter((dependency): dependency is string => Boolean(dependency)),
     hooks: {
       'kubb:plugin:setup'(ctx) {
         const resolver = userResolver ? { ...resolverClient, ...userResolver } : resolverClient

package/src/resolvers/resolverClient.ts

@@ -1,20 +1,27 @@
-import { camelCase, pascalCase } from '@internals/utils'
+import { camelCase, ensureValidVarName, pascalCase } from '@internals/utils'
 import { defineResolver } from '@kubb/core'
 import type { PluginClient } from '../types.ts'
 
 /**
- * Naming convention resolver for client plugin.
+ * Default resolver used by `@kubb/plugin-client`. Decides the names and file
+ * paths for every generated client function or class. Functions and files use
+ * camelCase; classes and tag groups use PascalCase.
  *
- * Provides default naming helpers using camelCase for functions and file paths.
+ * @example Resolve client function and class names
+ * ```ts
+ * import { resolverClient } from '@kubb/plugin-client'
  *
- * @example
- * `resolverClient.default('list pets', 'function')  // → 'listPets'`
+ * resolverClient.default('list pets', 'function') // 'listPets'
+ * resolverClient.resolveClassName('pet')          // 'Pet'
+ * resolverClient.resolveUrlName(operationNode)    // 'getShowPetByIdUrl'
+ * ```
  */
 export const resolverClient = defineResolver<PluginClient>(() => ({
   name: 'default',
   pluginName: 'plugin-client',
   default(name, type) {
-    return camelCase(name, { isFile: type === 'file' })
+    const resolved = camelCase(name, { isFile: type === 'file' })
+    return type === 'file' ? resolved : ensureValidVarName(resolved)
   },
   resolveName(name) {
     return this.default(name, 'function')
@@ -23,13 +30,13 @@ export const resolverClient = defineResolver<PluginClient>(() => ({
     return this.default(name, type)
   },
   resolveClassName(name) {
-    return pascalCase(name)
+    return ensureValidVarName(pascalCase(name))
   },
   resolveGroupName(name) {
-    return pascalCase(name)
+    return ensureValidVarName(pascalCase(name))
   },
   resolveClientPropertyName(name) {
-    return camelCase(name)
+    return ensureValidVarName(camelCase(name))
   },
   resolveUrlName(node) {
     const name = this.resolveName(node.operationId)

package/src/types.ts

@@ -46,9 +46,10 @@ export type ResolverClient = Resolver & {
 export type ClientImportPath =
   | {
       /**
-       * Which client should be used to do the HTTP calls.
-       * - 'axios' uses axios client for HTTP requests.
-       * - 'fetch' uses native fetch API for HTTP requests.
+       * HTTP client used by the generated code.
+       * - `'axios'` — imports from `@kubb/plugin-client/clients/axios`. Requires `axios` at runtime.
+       * - `'fetch'` — imports from `@kubb/plugin-client/clients/fetch`. Uses the global `fetch`.
+       *
        * @default 'axios'
        */
       client?: 'axios' | 'fetch'
@@ -57,9 +58,12 @@ export type ClientImportPath =
   | {
       client?: never
       /**
-       * Client import path for API calls.
-       * Used as `import client from '${importPath}'`.
-       * Accepts relative and absolute paths; path changes are not performed.
+       * Path to a custom client module. Generated files import their HTTP runtime from here
+       * instead of `@kubb/plugin-client/clients/{client}`. Accepts both relative paths and
+       * bare module specifiers; the value is used as-is.
+       *
+       * @note When combined with a query plugin, the module must export `Client`,
+       * `RequestConfig`, and `ResponseErrorConfig` types.
        */
       importPath: string
       /**
@@ -81,29 +85,28 @@ export type ClientImportPath =
 type ParamsTypeOptions =
   | {
       /**
-       * All parameters — path, query, headers, and body — are merged into a single
+       * Every operation parameter (path, query, headers, body) is wrapped in a single
        * destructured object argument.
-       * - 'object' returns the params and pathParams as an object.
-       * @default 'inline'
        */
       paramsType: 'object'
       /**
        * `pathParamsType` has no effect when `paramsType` is `'object'`.
-       * Path params are already inside the single destructured object.
+       * Path params already live inside the single destructured object.
        */
       pathParamsType?: never
     }
   | {
       /**
-       * Each parameter group is emitted as a separate function argument.
-       * - 'inline' returns the params as comma separated params.
+       * Each parameter group is emitted as a separate positional function argument.
+       *
        * @default 'inline'
        */
       paramsType?: 'inline'
       /**
-       * Controls how path parameters are arranged within the inline argument list.
-       * - 'object' groups path params into a destructured object: `{ petId }: PathParams`.
-       * - 'inline' emits each path param as its own argument: `petId: string`.
+       * How URL path parameters are arranged inside the inline argument list.
+       * - `'object'` groups them into one destructured object: `{ petId }: PathParams`.
+       * - `'inline'` emits each path param as its own argument: `petId: string`.
+       *
        * @default 'inline'
        */
       pathParamsType?: 'object' | 'inline'
@@ -111,87 +114,96 @@ type ParamsTypeOptions =
 
 export type Options = {
   /**
-   * Specify the export location for the files and define the behavior of the output.
-   * @default { path: 'clients', barrelType: 'named' }
+   * Where the generated client files are written and how they are exported.
+   *
+   * @default { path: 'clients', barrel: { type: 'named' } }
    */
   output?: Output
   /**
-   * Group the clients based on the provided name.
+   * Split generated files into subfolders based on the operation's tag.
    */
   group?: Group
   /**
-   * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
+   * Skip operations matching at least one entry in the list.
    */
   exclude?: Array<Exclude>
   /**
-   * Array containing include parameters to include tags/operations/methods/paths.
+   * Restrict generation to operations matching at least one entry in the list.
    */
   include?: Array<Include>
   /**
-   * Array containing override parameters to override `options` based on tags/operations/methods/paths.
+   * Apply a different options object to operations matching a pattern.
    */
   override?: Array<Override<ResolvedOptions>>
   /**
-   * Create `operations.ts` file with all operations grouped by methods.
+   * Emit an `operations.ts` file that re-exports every generated function grouped by HTTP method.
+   *
    * @default false
    */
   operations?: boolean
   /**
-   * Export urls that are used by operation x.
-   * - 'export' makes them part of your barrel file.
-   * - false does not make them exportable.
+   * Whether to also export the URL builder helpers (`get<Operation>Url`).
+   * - `'export'` exposes them via the barrel.
+   * - `false` keeps them private.
+   *
    * @default false
-   * @example getGetPetByIdUrl
    */
   urlType?: 'export' | false
   /**
-   * Allows you to set a custom base url for all generated calls.
+   * Base URL prepended to every request. When omitted, falls back to the adapter's
+   * server URL (typically `servers[0].url`).
    */
   baseURL?: string
   /**
-   * ReturnType that is used when calling the client.
-   * - 'data' returns ResponseConfig[data].
-   * - 'full' returns ResponseConfig.
+   * Shape of the value returned by each generated client function.
+   * - `'data'` — only the response body.
+   * - `'full'` — the full response config (body, status, headers, request).
+   *
    * @default 'data'
    */
   dataReturnType?: 'data' | 'full'
   /**
-   * How to style your params, by default no casing is applied.
-   * - 'camelcase' uses camelCase for pathParams, queryParams and headerParams names
-   * @note response types (data/body) are not affected by this option
+   * Rename parameter properties in the generated client (path, query, headers).
+   * The HTTP request still uses the original spec names; Kubb writes the mapping for you.
+   *
+   * @note Use the same value on `@kubb/plugin-ts` so types stay compatible.
    */
   paramsCasing?: 'camelcase'
   /**
-   * Which parser can be used before returning the data.
-   * - 'client' returns the data as-is from the client.
-   * - 'zod' uses @kubb/plugin-zod to parse the data.
+   * Validator applied to response bodies before they are returned to the caller.
+   * - `'client'` — no validation. Trusts the API.
+   * - `'zod'` — pipes responses through schemas from `@kubb/plugin-zod`.
+   *
    * @default 'client'
    */
   parser?: 'client' | 'zod'
   /**
-   * How to generate the client code.
-   * - 'function' generates standalone functions for each operation.
-   * - 'class' generates a class with methods for each operation.
-   * - 'staticClass' generates a class with static methods for each operation.
+   * Shape of the generated client.
+   * - `'function'` — one standalone async function per operation.
+   * - `'class'` — one class per tag with instance methods.
+   * - `'staticClass'` — one class per tag with static methods.
+   *
    * @default 'function'
+   * @note Only `'function'` is compatible with query plugins.
    */
   clientType?: 'function' | 'class' | 'staticClass'
   /**
-   * Bundle the selected client into the generated `.kubb` directory.
-   * When disabled the generated clients will import the shared runtime from `@kubb/plugin-client/clients/*`.
+   * Copy the HTTP client runtime into the generated output so consumers do not need
+   * `@kubb/plugin-client` at runtime. When `false`, generated files import from
+   * `@kubb/plugin-client/clients/{client}`.
+   *
    * @default false
-   * In version 5 of Kubb this is by default true
    */
   bundle?: boolean
   /**
-   * Generate an SDK facade class that composes all tag-based client classes into a single entry point.
-   * Setting this option automatically enables `clientType: 'class'`.
+   * Generate a single SDK class composing every tag-based client into one entry point.
+   * Automatically enables `clientType: 'class'`.
+   *
    * @example
    * ```ts
    * pluginClient({
    *   sdk: { className: 'PetStoreSDK' },
    * })
-   * // Generates a class with a shared constructor config and one property per tag:
    * // class PetStoreSDK {
    * //   readonly petController: petController
    * //   readonly storeController: storeController
@@ -201,22 +213,23 @@ export type Options = {
    */
   sdk?: {
     /**
-     * Name of the generated SDK facade class.
+     * Name of the generated SDK facade class. Also the file name.
      */
     className: string
   }
   /**
-   * Override individual resolver methods. Any method you omit falls back to the
-   * preset resolver's implementation. Use `this.default(...)` to call it.
+   * Override how names and file paths are built for the generated client.
+   * Methods you omit fall back to the default resolver. `this` is bound to the
+   * full resolver, so `this.default(name)` delegates to the built-in implementation.
    */
   resolver?: Partial<ResolverClient> & ThisType<ResolverClient>
   /**
-   * Single AST visitor applied to each node before printing.
-   * Return `null` or `undefined` from a method to leave the node unchanged.
+   * AST visitor applied to each operation node before code is printed.
+   * Return `null` or `undefined` to leave the node unchanged.
    */
   transformer?: ast.Visitor
   /**
-   * Define some generators next to the client generators.
+   * Custom generators that run alongside the built-in client generators.
    */
   generators?: Array<Generator<PluginClient>>
 } & ClientImportPath &
@@ -227,7 +240,7 @@ type ResolvedOptions = {
   exclude: Array<Exclude>
   include: Array<Include> | undefined
   override: Array<Override<ResolvedOptions>>
-  group: Group | undefined
+  group: Group | null
   client: Options['client']
   clientType: NonNullable<Options['clientType']>
   bundle: NonNullable<Options['bundle']>

package/src/utils.ts

@@ -1,4 +1,4 @@
-import { getOperationParameters } from '@internals/shared'
+import { getOperationParameters, resolveSuccessNames } from '@internals/shared'
 import type { URLPath } from '@internals/utils'
 import type { ast } from '@kubb/core'
 import type { ResolverTs } from '@kubb/plugin-ts'
@@ -12,8 +12,8 @@ import type { PluginClient } from './types.ts'
  */
 export function buildHeaders(contentType: string, hasHeaderParams: boolean): Array<string> {
   return [
-    contentType !== 'application/json' && contentType !== 'multipart/form-data' ? `'Content-Type': '${contentType}'` : undefined,
-    hasHeaderParams ? '...headers' : undefined,
+    contentType !== 'application/json' && contentType !== 'multipart/form-data' ? `'Content-Type': '${contentType}'` : null,
+    hasHeaderParams ? '...headers' : null,
   ].filter(Boolean) as Array<string>
 }
 
@@ -22,8 +22,9 @@ export function buildHeaders(contentType: string, hasHeaderParams: boolean): Arr
  * Includes response type, error type, and optional request type.
  */
 export function buildGenerics(node: ast.OperationNode, tsResolver: ResolverTs): Array<string> {
-  const responseName = tsResolver.resolveResponseName(node)
-  const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : undefined
+  const successNames = resolveSuccessNames(node, tsResolver)
+  const responseName = successNames.length > 0 ? successNames.join(' | ') : tsResolver.resolveResponseName(node)
+  const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : null
   const errorNames = node.responses.filter((r) => Number.parseInt(r.statusCode, 10) >= 400).map((r) => tsResolver.resolveResponseStatusName(node, r.statusCode))
   const TError = `ResponseErrorConfig<${errorNames.length > 0 ? errorNames.join(' | ') : 'Error'}>`
   return [responseName, TError, requestName || 'unknown'].filter(Boolean)
@@ -53,8 +54,8 @@ export function buildClassClientParams({
   headers: Array<string>
 }) {
   const { query: queryParams } = getOperationParameters(node)
-  const queryParamsName = queryParams.length > 0 ? tsResolver.resolveQueryParamsName(node, queryParams[0]!) : undefined
-  const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : undefined
+  const queryParamsName = queryParams.length > 0 ? tsResolver.resolveQueryParamsName(node, queryParams[0]!) : null
+  const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : null
 
   return createFunctionParams({
     config: {
@@ -73,8 +74,8 @@ export function buildClassClientParams({
           ? {
               value: JSON.stringify(baseURL),
             }
-          : undefined,
-        params: queryParamsName ? {} : undefined,
+          : null,
+        params: queryParamsName ? {} : null,
         data: requestName
           ? {
               value:
@@ -84,13 +85,13 @@ export function buildClassClientParams({
                     ? 'formData as FormData'
                     : 'requestData',
             }
-          : undefined,
-        contentType: isMultipleContentTypes ? {} : undefined,
+          : null,
+        contentType: isMultipleContentTypes ? {} : null,
         headers: headers.length
           ? {
               value: `{ ${headers.join(', ')}, ...requestConfig.headers }`,
             }
-          : undefined,
+          : null,
       },
     },
   })
@@ -107,9 +108,9 @@ export function buildRequestDataLine({
 }: {
   parser: PluginClient['resolvedOptions']['parser'] | undefined
   node: ast.OperationNode
-  zodResolver?: ResolverZod
+  zodResolver?: ResolverZod | null
 }): string {
-  const zodRequestName = zodResolver && parser === 'zod' && node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : undefined
+  const zodRequestName = zodResolver && parser === 'zod' && node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : null
   if (parser === 'zod' && zodRequestName) {
     return `const requestData = ${zodRequestName}.parse(data)`
   }
@@ -140,9 +141,9 @@ export function buildReturnStatement({
   dataReturnType: PluginClient['resolvedOptions']['dataReturnType']
   parser: PluginClient['resolvedOptions']['parser'] | undefined
   node: ast.OperationNode
-  zodResolver?: ResolverZod
+  zodResolver?: ResolverZod | null
 }): string {
-  const zodResponseName = zodResolver && parser === 'zod' ? zodResolver.resolveResponseName?.(node) : undefined
+  const zodResponseName = zodResolver && parser === 'zod' ? zodResolver.resolveResponseName?.(node) : null
   if (dataReturnType === 'full' && parser === 'zod' && zodResponseName) {
     return `return {...res, data: ${zodResponseName}.parse(res.data)}`
   }