@kubb/plugin-client 5.0.0-beta.3 → 5.0.0-beta.30

package/src/generators/staticClassClientGenerator.tsx

@@ -1,12 +1,13 @@
 import path from 'node:path'
-import { camelCase, pascalCase } from '@internals/utils'
+import { resolveOperationTypeNames } from '@internals/shared'
+import { camelCase } from '@internals/utils'
 import type { ast } from '@kubb/core'
 import { defineGenerator } from '@kubb/core'
 import type { ResolverTs } from '@kubb/plugin-ts'
 import { pluginTsName } from '@kubb/plugin-ts'
 import type { ResolverZod } from '@kubb/plugin-zod'
 import { pluginZodName } from '@kubb/plugin-zod'
-import { File, jsxRenderer } from '@kubb/renderer-jsx'
+import { File, jsxRendererSync } from '@kubb/renderer-jsx'
 import { StaticClassClient } from '../components/StaticClassClient'
 import type { PluginClient } from '../types'
 
@@ -14,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 = {
@@ -26,40 +27,38 @@ type Controller = {
 }
 
 function resolveTypeImportNames(node: ast.OperationNode, tsResolver: ResolverTs): Array<string> {
-  const names: Array<string | undefined> = [
-    node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : undefined,
-    tsResolver.resolveResponseName(node),
-    ...node.parameters.filter((p) => p.in === 'path').map((p) => tsResolver.resolvePathParamsName(node, p)),
-    ...node.parameters.filter((p) => p.in === 'query').map((p) => tsResolver.resolveQueryParamsName(node, p)),
-    ...node.parameters.filter((p) => p.in === 'header').map((p) => tsResolver.resolveHeaderParamsName(node, p)),
-    ...node.responses.map((res) => tsResolver.resolveResponseStatusName(node, res.statusCode)),
-  ]
-  return names.filter((n): n is string => Boolean(n))
+  return resolveOperationTypeNames(node, tsResolver, { order: 'body-response-first' })
 }
 
 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: jsxRenderer,
+  renderer: jsxRendererSync,
   operations(nodes, ctx) {
-    const { adapter, config, driver, resolver, root } = ctx
+    const { config, driver, resolver, root } = ctx
     const { output, group, dataReturnType, paramsCasing, paramsType, pathParamsType, parser, importPath } = ctx.options
-    const baseURL = ctx.options.baseURL ?? adapter.inputNode?.meta?.baseURL
+    const baseURL = ctx.options.baseURL ?? ctx.meta.baseURL
 
     const pluginTs = driver.getPlugin(pluginTsName)
     if (!pluginTs) return null
 
     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(
@@ -70,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,
@@ -86,11 +85,11 @@ export const staticClassClientGenerator = defineGenerator<PluginClient>({
 
     const controllers = nodes.reduce((acc, operationNode) => {
       const tag = operationNode.tags[0]
-      const groupName = tag ? (group?.name?.({ group: camelCase(tag) }) ?? pascalCase(tag)) : 'Client'
+      const groupName = tag ? (group?.name?.({ group: camelCase(tag) }) ?? resolver.resolveGroupName(tag)) : resolver.resolveGroupName('Client')
 
       if (!tag && !group) {
-        const name = 'ApiClient'
-        const file = resolver.resolveFile({ name, extname: '.ts' }, { root, output, group })
+        const name = resolver.resolveClassName('ApiClient')
+        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,9 +98,12 @@ export const staticClassClientGenerator = defineGenerator<PluginClient>({
         } else {
           acc.push({ name, file, operations: [operationData] })
         }
-      } else if (tag) {
+        return acc
+      }
+
+      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)
 
@@ -160,7 +162,7 @@ export const staticClassClientGenerator = defineGenerator<PluginClient>({
           const { typeImportsByFile, typeFilesByPath } = collectTypeImports(ops)
           const { zodImportsByFile, zodFilesByPath } =
             parser === 'zod' ? collectZodImports(ops) : { zodImportsByFile: new Map<string, Set<string>>(), zodFilesByPath: new Map<string, ast.FileNode>() }
-          const hasFormData = ops.some((op) => op.node.requestBody?.content?.[0]?.contentType === 'multipart/form-data')
+          const hasFormData = ops.some((op) => op.node.requestBody?.content?.some((e) => e.contentType === 'multipart/form-data') ?? false)
 
           return (
             <File
@@ -168,18 +170,18 @@ export const staticClassClientGenerator = defineGenerator<PluginClient>({
               baseName={file.baseName}
               path={file.path}
               meta={file.meta}
-              banner={resolver.resolveBanner(adapter.inputNode, { output, config })}
-              footer={resolver.resolveFooter(adapter.inputNode, { output, config })}
+              banner={resolver.resolveBanner(ctx.meta, { output, config, file: { path: file.path, baseName: file.baseName } })}
+              footer={resolver.resolveFooter(ctx.meta, { output, config, file: { path: file.path, baseName: file.baseName } })}
             >
               {importPath ? (
                 <>
-                  <File.Import name={'fetch'} path={importPath} />
+                  <File.Import name={'client'} path={importPath} />
                   <File.Import name={['mergeConfig']} path={importPath} />
                   <File.Import name={['Client', 'RequestConfig', 'ResponseErrorConfig']} path={importPath} isTypeOnly />
                 </>
               ) : (
                 <>
-                  <File.Import name={['fetch']} root={file.path} path={path.resolve(root, '.kubb/client.ts')} />
+                  <File.Import name={['client']} root={file.path} path={path.resolve(root, '.kubb/client.ts')} />
                   <File.Import name={['mergeConfig']} root={file.path} path={path.resolve(root, '.kubb/client.ts')} />
                   <File.Import
                     name={['Client', 'RequestConfig', 'ResponseErrorConfig']}

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(Boolean),
+    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,22 +1,45 @@
-import { camelCase } 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>((ctx) => ({
+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 ctx.default(name, 'function')
+    return this.default(name, 'function')
+  },
+  resolvePathName(name, type) {
+    return this.default(name, type)
+  },
+  resolveClassName(name) {
+    return ensureValidVarName(pascalCase(name))
+  },
+  resolveGroupName(name) {
+    return ensureValidVarName(pascalCase(name))
+  },
+  resolveClientPropertyName(name) {
+    return ensureValidVarName(camelCase(name))
+  },
+  resolveUrlName(node) {
+    const name = this.resolveName(node.operationId)
+    return `get${name.charAt(0).toUpperCase()}${name.slice(1)}Url`
   },
 }))

package/src/types.ts

@@ -7,10 +7,34 @@ import type { ast, Exclude, Generator, Group, Include, Output, Override, PluginF
 export type ResolverClient = Resolver & {
   /**
    * Resolves the function name for a given raw operation name.
+   *
    * @example Resolving operation names
    * `resolver.resolveName('show pet by id') // -> 'showPetById'`
    */
   resolveName(this: ResolverClient, name: string): string
+  /**
+   * Resolves the output file name for a client module.
+   */
+  resolvePathName(this: ResolverClient, name: string, type?: 'file' | 'function' | 'type' | 'const'): string
+  /**
+   * Resolves the generated class name for class-based clients.
+   */
+  resolveClassName(this: ResolverClient, name: string): string
+  /**
+   * Resolves the generated class name for tag-based client groups.
+   */
+  resolveGroupName(this: ResolverClient, name: string): string
+  /**
+   * Resolves the generated SDK facade property name for a client class.
+   */
+  resolveClientPropertyName(this: ResolverClient, name: string): string
+  /**
+   * Resolves the URL helper function name for an operation.
+   *
+   * @example Resolving URL helper names
+   * `resolver.resolveUrlName(node) // -> 'getShowPetByIdUrl'`
+   */
+  resolveUrlName(this: ResolverClient, node: ast.OperationNode): string
 }
 
 /**
@@ -22,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'
@@ -33,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
       /**
@@ -57,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'
@@ -87,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
@@ -177,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 &
@@ -203,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']>