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

package/dist/index.d.ts

@@ -13,10 +13,34 @@ import { KubbReactNode } from "@kubb/renderer-jsx/types";
 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;
 };
 /**
  * Use either a preset `client` type OR a custom `importPath`, not both.
@@ -26,9 +50,10 @@ type ResolverClient = Resolver & {
  */
 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';
@@ -36,9 +61,12 @@ 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;
   /**
@@ -58,115 +86,124 @@ 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';
 };
 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.
-   * @default 'client'
+   * Validator applied to response bodies before they are returned to the caller.
+   * - `false` (default) — no validation. The client has no runtime parser; the response is
+   *   returned as-is, cast to the generated TypeScript type.
+   * - `'zod'` — pipes responses through schemas from `@kubb/plugin-zod`.
+   *
+   * @default false
    */
-  parser?: 'client' | 'zod';
+  parser?: false | '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
@@ -176,22 +213,23 @@ 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 & ParamsTypeOptions;
@@ -200,7 +238,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']>;
@@ -232,7 +270,7 @@ type Props = {
   isIndexable?: boolean;
   isConfigurable?: boolean;
   returnType?: string;
-  baseURL: string | undefined;
+  baseURL: string | null | undefined;
   dataReturnType: PluginClient['resolvedOptions']['dataReturnType'];
   paramsCasing: PluginClient['resolvedOptions']['paramsCasing'];
   paramsType: PluginClient['resolvedOptions']['pathParamsType'];
@@ -240,17 +278,9 @@ type Props = {
   parser: PluginClient['resolvedOptions']['parser'] | undefined;
   node: ast.OperationNode;
   tsResolver: ResolverTs;
-  zodResolver?: ResolverZod;
+  zodResolver?: ResolverZod | null;
   children?: KubbReactNode;
 };
-type GetParamsProps = {
-  paramsCasing: PluginClient['resolvedOptions']['paramsCasing'];
-  paramsType: PluginClient['resolvedOptions']['paramsType'];
-  pathParamsType: PluginClient['resolvedOptions']['pathParamsType'];
-  node: ast.OperationNode;
-  tsResolver: ResolverTs;
-  isConfigurable: boolean;
-};
 declare function Client({
   name,
   isExportable,
@@ -269,47 +299,78 @@ declare function Client({
   children,
   isConfigurable
 }: Props): KubbReactNode;
-declare namespace Client {
-  var getParams: ({
-    paramsType,
-    paramsCasing,
-    pathParamsType,
-    node,
-    tsResolver,
-    isConfigurable
-  }: GetParamsProps) => ast.FunctionParametersNode;
-}
 //#endregion
 //#region src/generators/classClientGenerator.d.ts
+/**
+ * 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.
+ */
 declare const classClientGenerator: _$_kubb_core0.Generator<PluginClient, unknown>;
 //#endregion
 //#region src/generators/clientGenerator.d.ts
+/**
+ * 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).
+ */
 declare const clientGenerator: _$_kubb_core0.Generator<PluginClient, unknown>;
 //#endregion
 //#region src/generators/groupedClientGenerator.d.ts
+/**
+ * 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.
+ */
 declare const groupedClientGenerator: _$_kubb_core0.Generator<PluginClient, unknown>;
 //#endregion
 //#region src/generators/operationsGenerator.d.ts
+/**
+ * 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).
+ */
 declare const operationsGenerator: _$_kubb_core0.Generator<PluginClient, unknown>;
 //#endregion
 //#region src/generators/staticClassClientGenerator.d.ts
+/**
+ * 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.
+ */
 declare const staticClassClientGenerator: _$_kubb_core0.Generator<PluginClient, unknown>;
 //#endregion
 //#region src/plugin.d.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.
  */
 declare const pluginClientName = "plugin-client";
 /**
- * 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',
+ *     }),
+ *   ],
  * })
  * ```
  */
@@ -317,12 +378,18 @@ declare const pluginClient: (options?: Options | undefined) => _$_kubb_core0.Plu
 //#endregion
 //#region src/resolvers/resolverClient.d.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'
+ * ```
  */
 declare const resolverClient: ResolverClient;
 //#endregion