@kubb/plugin-client 5.12.0 → 6.0.0

package/dist/index.d.cts

@@ -1,14 +1,71 @@
 import { Exclude, Group, Include, Output, OutputOptions, Override, PluginType, Resolver, ResolverPatch, ast } from "@kubb/kit";
-import "@kubb/plugin-zod";
 import { ResolverTs } from "@kubb/plugin-ts";
+/**
+ * Shape of the value a generated operation function resolves to.
+ * - `'full'`: the complete `{ status, data, error, contentType, request, response }` result.
+ * - `'data'`: the bare success body when `throwOnError` is true, or the full result when it is false
+ *   so callers can inspect `error`.
+ * - `'plain'`: the client's own promise typed as `RequestResult`, with no `withUnwrap` / `unwrapResult`
+ *   helper. Backs `@kubb/plugin-client`.
+ */
+type ReturnTypeOption = 'full' | 'data' | 'plain';
+/**
+ * The per-operation type names a generated client references: the grouped input, the per-status
+ * responses record its `RequestResult` is keyed on, and the headers each response declares.
+ */
+type OperationTypeNames = {
+  response: {
+    /**
+     * Resolves the name of the operation's grouped `{ body, path, query, headers, cookies }` input type.
+     */
+    options(node: ast.OperationNode): string;
+    /**
+     * Resolves the name of the operation's per-status responses record type.
+     */
+    responses(node: ast.OperationNode): string;
+    /**
+     * Resolves the name of the type of the headers one response declares. Left out, results keep untyped headers.
+     */
+    headers?(node: ast.OperationNode, statusCode: ast.StatusCode): string;
+  };
+};
+/**
+ * Where a generated client sources its operation types, plus the resolver and output the file
+ * declaring them is resolved with.
+ */
+type OperationTypeSource = OperationTypeNames & {
+  /**
+   * `plugin-ts` shaped resolver of the plugin supplying the names, also used to resolve the file they are exported from.
+   */
+  resolver: ResolverTs;
+  /**
+   * The supplying plugin's own `output`, when it configured one.
+   */
+  output: Output | undefined;
+  /**
+   * The supplying plugin's own `group`, when it configured one.
+   */
+  group: Group | undefined;
+};
+declare global {
+  namespace Kubb {
+    interface MemoRegistry {
+      operationTypes: OperationTypeSource;
+      /**
+       * Nests every key the zod-backed `ResolverTs` memoizes, so it holds each of their value types.
+       */
+      zodTypes: unknown;
+    }
+  }
+}
 /**
  * Validator applied to the request and response using schemas from `@kubb/plugin-zod`.
  * - `false`: no validation.
- * - `'zod'`: validates the success (2xx) response body, and the error body when a non-2xx call does
- *   not throw (`throwOnError: false`).
+ * - `'zod'`: validates the success (2xx) response body, and the error body of a non-2xx call, whether it
+ *   throws or returns the error.
  * - `{ request?: 'zod'; params?: 'zod'; response?: 'zod' }`: opt in per slot. `request` encodes the
  *   request body before the call; `params` validate the path, query, and header params;
- *   `response` validates the success response body and, on the non-throw path, the error body.
+ *   `response` validates the success response body and the error body.
  */
 type ValidatorOptions = false | 'zod' | {
   request?: 'zod';
@@ -21,15 +78,6 @@ type ValidatorOptions = false | 'zod' | {
  * - `'flat'`: one class with every operation as a direct method.
  */
 type Mode = 'tag' | 'flat';
-/**
- * Shape of the value a generated operation function resolves to.
- * - `'full'`: the complete `{ status, data, error, contentType, request, response }` result.
- * - `'data'`: the bare success body when `throwOnError` is true, or the full result when it is false
- *   so callers can inspect `error`.
- * - `'plain'`: the client's own promise typed as `RequestResult`, with no `withUnwrap` / `unwrapResult`
- *   helper. Backs `@kubb/plugin-client`.
- */
-type ReturnTypeOption = 'full' | 'data' | 'plain';
 /**
  * The resolver shared by the client plugins. Inherits the built-in camelCase `name` and `file`;
  * classes and tag groups use PascalCase (with a `Client` suffix for groups).
@@ -59,7 +107,7 @@ type ResolverClient = Resolver & {
  * response contract and one grouped options object. Each plugin extends this with its own
  * `transport` field.
  */
-type Options$1 = OutputOptions & {
+type ClientOptions = OutputOptions & {
   /**
    * Skip operations matching at least one entry in the list.
    */
@@ -71,12 +119,12 @@ type Options$1 = OutputOptions & {
   /**
    * Apply a different options object to operations matching a pattern.
    */
-  override?: Array<Override<Omit<ResolvedOptions$1, 'throwOnErrorDefault'>>>;
+  override?: Array<Override<Omit<ClientResolvedOptions, 'throwOnErrorDefault'>>>;
   /**
-   * Base URL prepended to every request. When omitted, the generated client sets no base URL, so
-   * set one at runtime with `client.setConfig({ baseURL })`. The adapter's server URL is not used.
-   * Values containing a `${...}` interpolation are emitted as template literals in the generated
-   * client config, which keeps runtime environment reads dynamic.
+   * Base URL prepended to every request. When omitted, the generated client sets no base URL, so set one at runtime with
+   * `client.setConfig({ baseURL })`. The top-level server URL is not used, but an operation with path-level or operation-level `servers` calls it.
+   * Values containing a `${...}` interpolation are emitted as template literals in the generated client config, which keeps
+   * runtime environment reads dynamic.
    */
   baseURL?: string;
   /**
@@ -118,15 +166,17 @@ type Options$1 = OutputOptions & {
    * // const api = new PetClient({ baseURL: 'https://api.example.com' })
    * // await api.getPetById({ path: { petId: 1 } })
    * ```
-   * @example Composed root that instantiates every tag client from one config
+   * @example Composed root that shares one client with every tag client
    * ```ts
    * pluginFetch({ sdk: { name: 'petStore' } })
    * // class PetStore {
+   * //   readonly client: ClientInstance
    * //   readonly pet: PetClient
    * //   readonly store: StoreClient
    * //   constructor(config = {}) { ... }
    * // }
    * // const api = new PetStore({ baseURL })
+   * // api.client.interceptors.request.use(...) // applies to every tag
    * // await api.pet.getPetById({ path: { petId: 1 } })
    * ```
    * @example Flat class with every operation as a direct method
@@ -139,7 +189,7 @@ type Options$1 = OutputOptions & {
   sdk?: {
     /**
      * How the SDK groups operations.
-     * - `'tag'`: one class per tag. With `name`, a composed root instantiates every tag client.
+     * - `'tag'`: one class per tag, such as `PetClient`. With `name`, a composed root shares one client with every tag client.
      * - `'flat'`: one class named by `name`, with every operation as a direct method.
      *
      * @default 'tag'
@@ -147,7 +197,7 @@ type Options$1 = OutputOptions & {
     mode?: Mode;
     /**
      * Name of the generated entry point, also the file name. With `mode: 'tag'` it emits a
-     * composed root class that instantiates every tag client from one shared config. With
+     * composed root class that creates one client and shares it with every tag client. With
      * `mode: 'flat'` it names the single class.
      */
     name?: string;
@@ -164,19 +214,19 @@ type Options$1 = OutputOptions & {
 /**
  * The resolved options after defaults are applied.
  */
-type ResolvedOptions$1 = {
+type ClientResolvedOptions = {
   output: Output;
   exclude: Array<Exclude>;
   include: Array<Include> | undefined;
-  override: Array<Override<Omit<ResolvedOptions$1, 'throwOnErrorDefault'>>>;
+  override: Array<Override<Omit<ClientResolvedOptions, 'throwOnErrorDefault'>>>;
   group: Group | null;
-  baseURL: Options$1['baseURL'];
+  baseURL: ClientOptions['baseURL'];
   /**
    * Module the generated operations import the client runtime from, used verbatim. Unset, they import the bundled `.kubb/client.ts`.
    */
   importPath?: string;
   throwOnErrorDefault: boolean;
-  validator: NonNullable<Options$1['validator']>;
+  validator: NonNullable<ClientOptions['validator']>;
   returnType: ReturnTypeOption;
   sdk: {
     mode: Mode;
@@ -184,51 +234,6 @@ type ResolvedOptions$1 = {
   } | undefined;
   resolver: ResolverClient;
 };
-/**
- * The two per-operation type names a generated client references: the grouped input and the
- * per-status responses record its `RequestResult` is keyed on.
- */
-type OperationTypeNames = {
-  response: {
-    /**
-     * Resolves the name of the operation's grouped `{ body, path, query, headers }` input type.
-     */
-    options(node: ast.OperationNode): string;
-    /**
-     * Resolves the name of the operation's per-status responses record type.
-     */
-    responses(node: ast.OperationNode): string;
-  };
-};
-/**
- * Where a generated client sources its operation types, plus the resolver and output the file
- * declaring them is resolved with.
- */
-type OperationTypeSource = OperationTypeNames & {
-  /**
-   * `plugin-ts` shaped resolver of the plugin supplying the names, also used to resolve the file they are exported from.
-   */
-  resolver: ResolverTs;
-  /**
-   * The supplying plugin's own `output`, when it configured one.
-   */
-  output: Output | undefined;
-  /**
-   * The supplying plugin's own `group`, when it configured one.
-   */
-  group: Group | undefined;
-};
-declare global {
-  namespace Kubb {
-    interface MemoRegistry {
-      operationTypes: OperationTypeSource;
-      /**
-       * Nests every key the zod-backed `ResolverTs` memoizes, so it holds each of their value types.
-       */
-      zodTypes: unknown;
-    }
-  }
-}
 /**
  * Omits keys from every member of a union, where the built-in `Omit` would collapse the union into one shape.
  */
@@ -242,7 +247,7 @@ type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K>
  * pluginClient({ importPath: '../../../client' })
  * ```
  */
-type Options = DistributiveOmit<Options$1, 'sdk' | 'returnType' | 'baseURL' | 'override'> & {
+type Options = DistributiveOmit<ClientOptions, 'sdk' | 'returnType' | 'baseURL' | 'override'> & {
   /**
    * Shape of the value a generated operation resolves to. `'full'` and `'data'` import `withUnwrap` or `unwrapResult`
    * and their types from your `importPath` module, so that module must export them.
@@ -275,7 +280,7 @@ type Options = DistributiveOmit<Options$1, 'sdk' | 'returnType' | 'baseURL' | 'o
 /**
  * Options after `pluginClient` applies its defaults.
  */
-type ResolvedOptions = ResolvedOptions$1 & {
+type ResolvedOptions = ClientResolvedOptions & {
   importPath: string;
 };
 /**
@@ -304,5 +309,40 @@ export declare const pluginClientName = "plugin-client";
  * ```
  */
 export declare const pluginClient: import("@kubb/kit").PluginFactory<PluginClient>;
-export { type Options, type PluginClient, type ResolvedOptions, type ResolverClient, pluginClient as default };
+/**
+ * Default resolver shared by the client plugins. Functions use safe camelCase identifiers and
+ * files inherit the built-in casing; classes and tag groups use PascalCase.
+ *
+ * @example
+ * ```ts
+ * resolverClient.name('show pet by id')  // 'showPetById'
+ * resolverClient.groupName('pet')        // 'PetClient'
+ * ```
+ */
+export declare const resolverClient: ResolverClient;
+/**
+ * Applies the client option defaults and merges a user `resolver` over the built-in one.
+ */
+export declare function resolveClientOptions(options: ClientOptions): ClientResolvedOptions;
+/**
+ * Wires a client plugin in its `setup`: resolver, macros, client or SDK generator, and the `.kubb/` runtime with the plugin's own `client.ts`.
+ */
+export declare function setupClient({ name, resolved, macros, client }: {
+  name: string;
+  resolved: ClientResolvedOptions;
+  macros?: ClientOptions['macros'];
+  client: string;
+}): void;
+/**
+ * Declares `plugin-ts` as optional and `plugin-zod` as required once `validator` enables a direction.
+ */
+export declare function clientDependencies(options: Pick<ClientOptions, 'validator'>): {
+  "plugin-ts": {
+    optional: boolean;
+  };
+  "plugin-zod": {
+    optional: boolean;
+  };
+};
+export { type ClientOptions, type ClientResolvedOptions, type Options, type PluginClient, type ResolvedOptions, type ResolverClient, pluginClient as default };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,14 +1,71 @@
 import { Exclude, Group, Include, Output, OutputOptions, Override, PluginType, Resolver, ResolverPatch, ast } from "@kubb/kit";
-import "@kubb/plugin-zod";
 import { ResolverTs } from "@kubb/plugin-ts";
+/**
+ * Shape of the value a generated operation function resolves to.
+ * - `'full'`: the complete `{ status, data, error, contentType, request, response }` result.
+ * - `'data'`: the bare success body when `throwOnError` is true, or the full result when it is false
+ *   so callers can inspect `error`.
+ * - `'plain'`: the client's own promise typed as `RequestResult`, with no `withUnwrap` / `unwrapResult`
+ *   helper. Backs `@kubb/plugin-client`.
+ */
+type ReturnTypeOption = 'full' | 'data' | 'plain';
+/**
+ * The per-operation type names a generated client references: the grouped input, the per-status
+ * responses record its `RequestResult` is keyed on, and the headers each response declares.
+ */
+type OperationTypeNames = {
+  response: {
+    /**
+     * Resolves the name of the operation's grouped `{ body, path, query, headers, cookies }` input type.
+     */
+    options(node: ast.OperationNode): string;
+    /**
+     * Resolves the name of the operation's per-status responses record type.
+     */
+    responses(node: ast.OperationNode): string;
+    /**
+     * Resolves the name of the type of the headers one response declares. Left out, results keep untyped headers.
+     */
+    headers?(node: ast.OperationNode, statusCode: ast.StatusCode): string;
+  };
+};
+/**
+ * Where a generated client sources its operation types, plus the resolver and output the file
+ * declaring them is resolved with.
+ */
+type OperationTypeSource = OperationTypeNames & {
+  /**
+   * `plugin-ts` shaped resolver of the plugin supplying the names, also used to resolve the file they are exported from.
+   */
+  resolver: ResolverTs;
+  /**
+   * The supplying plugin's own `output`, when it configured one.
+   */
+  output: Output | undefined;
+  /**
+   * The supplying plugin's own `group`, when it configured one.
+   */
+  group: Group | undefined;
+};
+declare global {
+  namespace Kubb {
+    interface MemoRegistry {
+      operationTypes: OperationTypeSource;
+      /**
+       * Nests every key the zod-backed `ResolverTs` memoizes, so it holds each of their value types.
+       */
+      zodTypes: unknown;
+    }
+  }
+}
 /**
  * Validator applied to the request and response using schemas from `@kubb/plugin-zod`.
  * - `false`: no validation.
- * - `'zod'`: validates the success (2xx) response body, and the error body when a non-2xx call does
- *   not throw (`throwOnError: false`).
+ * - `'zod'`: validates the success (2xx) response body, and the error body of a non-2xx call, whether it
+ *   throws or returns the error.
  * - `{ request?: 'zod'; params?: 'zod'; response?: 'zod' }`: opt in per slot. `request` encodes the
  *   request body before the call; `params` validate the path, query, and header params;
- *   `response` validates the success response body and, on the non-throw path, the error body.
+ *   `response` validates the success response body and the error body.
  */
 type ValidatorOptions = false | 'zod' | {
   request?: 'zod';
@@ -21,15 +78,6 @@ type ValidatorOptions = false | 'zod' | {
  * - `'flat'`: one class with every operation as a direct method.
  */
 type Mode = 'tag' | 'flat';
-/**
- * Shape of the value a generated operation function resolves to.
- * - `'full'`: the complete `{ status, data, error, contentType, request, response }` result.
- * - `'data'`: the bare success body when `throwOnError` is true, or the full result when it is false
- *   so callers can inspect `error`.
- * - `'plain'`: the client's own promise typed as `RequestResult`, with no `withUnwrap` / `unwrapResult`
- *   helper. Backs `@kubb/plugin-client`.
- */
-type ReturnTypeOption = 'full' | 'data' | 'plain';
 /**
  * The resolver shared by the client plugins. Inherits the built-in camelCase `name` and `file`;
  * classes and tag groups use PascalCase (with a `Client` suffix for groups).
@@ -59,7 +107,7 @@ type ResolverClient = Resolver & {
  * response contract and one grouped options object. Each plugin extends this with its own
  * `transport` field.
  */
-type Options$1 = OutputOptions & {
+type ClientOptions = OutputOptions & {
   /**
    * Skip operations matching at least one entry in the list.
    */
@@ -71,12 +119,12 @@ type Options$1 = OutputOptions & {
   /**
    * Apply a different options object to operations matching a pattern.
    */
-  override?: Array<Override<Omit<ResolvedOptions$1, 'throwOnErrorDefault'>>>;
+  override?: Array<Override<Omit<ClientResolvedOptions, 'throwOnErrorDefault'>>>;
   /**
-   * Base URL prepended to every request. When omitted, the generated client sets no base URL, so
-   * set one at runtime with `client.setConfig({ baseURL })`. The adapter's server URL is not used.
-   * Values containing a `${...}` interpolation are emitted as template literals in the generated
-   * client config, which keeps runtime environment reads dynamic.
+   * Base URL prepended to every request. When omitted, the generated client sets no base URL, so set one at runtime with
+   * `client.setConfig({ baseURL })`. The top-level server URL is not used, but an operation with path-level or operation-level `servers` calls it.
+   * Values containing a `${...}` interpolation are emitted as template literals in the generated client config, which keeps
+   * runtime environment reads dynamic.
    */
   baseURL?: string;
   /**
@@ -118,15 +166,17 @@ type Options$1 = OutputOptions & {
    * // const api = new PetClient({ baseURL: 'https://api.example.com' })
    * // await api.getPetById({ path: { petId: 1 } })
    * ```
-   * @example Composed root that instantiates every tag client from one config
+   * @example Composed root that shares one client with every tag client
    * ```ts
    * pluginFetch({ sdk: { name: 'petStore' } })
    * // class PetStore {
+   * //   readonly client: ClientInstance
    * //   readonly pet: PetClient
    * //   readonly store: StoreClient
    * //   constructor(config = {}) { ... }
    * // }
    * // const api = new PetStore({ baseURL })
+   * // api.client.interceptors.request.use(...) // applies to every tag
    * // await api.pet.getPetById({ path: { petId: 1 } })
    * ```
    * @example Flat class with every operation as a direct method
@@ -139,7 +189,7 @@ type Options$1 = OutputOptions & {
   sdk?: {
     /**
      * How the SDK groups operations.
-     * - `'tag'`: one class per tag. With `name`, a composed root instantiates every tag client.
+     * - `'tag'`: one class per tag, such as `PetClient`. With `name`, a composed root shares one client with every tag client.
      * - `'flat'`: one class named by `name`, with every operation as a direct method.
      *
      * @default 'tag'
@@ -147,7 +197,7 @@ type Options$1 = OutputOptions & {
     mode?: Mode;
     /**
      * Name of the generated entry point, also the file name. With `mode: 'tag'` it emits a
-     * composed root class that instantiates every tag client from one shared config. With
+     * composed root class that creates one client and shares it with every tag client. With
      * `mode: 'flat'` it names the single class.
      */
     name?: string;
@@ -164,19 +214,19 @@ type Options$1 = OutputOptions & {
 /**
  * The resolved options after defaults are applied.
  */
-type ResolvedOptions$1 = {
+type ClientResolvedOptions = {
   output: Output;
   exclude: Array<Exclude>;
   include: Array<Include> | undefined;
-  override: Array<Override<Omit<ResolvedOptions$1, 'throwOnErrorDefault'>>>;
+  override: Array<Override<Omit<ClientResolvedOptions, 'throwOnErrorDefault'>>>;
   group: Group | null;
-  baseURL: Options$1['baseURL'];
+  baseURL: ClientOptions['baseURL'];
   /**
    * Module the generated operations import the client runtime from, used verbatim. Unset, they import the bundled `.kubb/client.ts`.
    */
   importPath?: string;
   throwOnErrorDefault: boolean;
-  validator: NonNullable<Options$1['validator']>;
+  validator: NonNullable<ClientOptions['validator']>;
   returnType: ReturnTypeOption;
   sdk: {
     mode: Mode;
@@ -184,51 +234,6 @@ type ResolvedOptions$1 = {
   } | undefined;
   resolver: ResolverClient;
 };
-/**
- * The two per-operation type names a generated client references: the grouped input and the
- * per-status responses record its `RequestResult` is keyed on.
- */
-type OperationTypeNames = {
-  response: {
-    /**
-     * Resolves the name of the operation's grouped `{ body, path, query, headers }` input type.
-     */
-    options(node: ast.OperationNode): string;
-    /**
-     * Resolves the name of the operation's per-status responses record type.
-     */
-    responses(node: ast.OperationNode): string;
-  };
-};
-/**
- * Where a generated client sources its operation types, plus the resolver and output the file
- * declaring them is resolved with.
- */
-type OperationTypeSource = OperationTypeNames & {
-  /**
-   * `plugin-ts` shaped resolver of the plugin supplying the names, also used to resolve the file they are exported from.
-   */
-  resolver: ResolverTs;
-  /**
-   * The supplying plugin's own `output`, when it configured one.
-   */
-  output: Output | undefined;
-  /**
-   * The supplying plugin's own `group`, when it configured one.
-   */
-  group: Group | undefined;
-};
-declare global {
-  namespace Kubb {
-    interface MemoRegistry {
-      operationTypes: OperationTypeSource;
-      /**
-       * Nests every key the zod-backed `ResolverTs` memoizes, so it holds each of their value types.
-       */
-      zodTypes: unknown;
-    }
-  }
-}
 /**
  * Omits keys from every member of a union, where the built-in `Omit` would collapse the union into one shape.
  */
@@ -242,7 +247,7 @@ type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K>
  * pluginClient({ importPath: '../../../client' })
  * ```
  */
-type Options = DistributiveOmit<Options$1, 'sdk' | 'returnType' | 'baseURL' | 'override'> & {
+type Options = DistributiveOmit<ClientOptions, 'sdk' | 'returnType' | 'baseURL' | 'override'> & {
   /**
    * Shape of the value a generated operation resolves to. `'full'` and `'data'` import `withUnwrap` or `unwrapResult`
    * and their types from your `importPath` module, so that module must export them.
@@ -275,7 +280,7 @@ type Options = DistributiveOmit<Options$1, 'sdk' | 'returnType' | 'baseURL' | 'o
 /**
  * Options after `pluginClient` applies its defaults.
  */
-type ResolvedOptions = ResolvedOptions$1 & {
+type ResolvedOptions = ClientResolvedOptions & {
   importPath: string;
 };
 /**
@@ -304,5 +309,40 @@ export declare const pluginClientName = "plugin-client";
  * ```
  */
 export declare const pluginClient: import("@kubb/kit").PluginFactory<PluginClient>;
-export { type Options, type PluginClient, type ResolvedOptions, type ResolverClient, pluginClient as default };
+/**
+ * Default resolver shared by the client plugins. Functions use safe camelCase identifiers and
+ * files inherit the built-in casing; classes and tag groups use PascalCase.
+ *
+ * @example
+ * ```ts
+ * resolverClient.name('show pet by id')  // 'showPetById'
+ * resolverClient.groupName('pet')        // 'PetClient'
+ * ```
+ */
+export declare const resolverClient: ResolverClient;
+/**
+ * Applies the client option defaults and merges a user `resolver` over the built-in one.
+ */
+export declare function resolveClientOptions(options: ClientOptions): ClientResolvedOptions;
+/**
+ * Wires a client plugin in its `setup`: resolver, macros, client or SDK generator, and the `.kubb/` runtime with the plugin's own `client.ts`.
+ */
+export declare function setupClient({ name, resolved, macros, client }: {
+  name: string;
+  resolved: ClientResolvedOptions;
+  macros?: ClientOptions['macros'];
+  client: string;
+}): void;
+/**
+ * Declares `plugin-ts` as optional and `plugin-zod` as required once `validator` enables a direction.
+ */
+export declare function clientDependencies(options: Pick<ClientOptions, 'validator'>): {
+  "plugin-ts": {
+    optional: boolean;
+  };
+  "plugin-zod": {
+    optional: boolean;
+  };
+};
+export { type ClientOptions, type ClientResolvedOptions, type Options, type PluginClient, type ResolvedOptions, type ResolverClient, pluginClient as default };
 //# sourceMappingURL=index.d.ts.map