@kubb/plugin-client 5.12.0 → 6.0.1

package/src/builders/validatorOptions.ts

@@ -0,0 +1,53 @@
+import { ast, text } from '@kubb/kit'
+import type { ResolverZod } from '@kubb/plugin-zod'
+import type { ValidatorOptions } from '../types.ts'
+
+/**
+ * Returns `true` when any direction of the validator uses zod (used for dependency checks).
+ */
+export function isValidatorEnabled(validator: ValidatorOptions | undefined): boolean {
+  if (!validator) return false
+  if (validator === 'zod') return true
+  return Boolean(validator.request || validator.params || validator.response)
+}
+
+/**
+ * Returns `'zod'` when request body parsing is enabled, `null` otherwise. The string shorthand
+ * `'zod'` validates the response only, so it does not enable request parsing.
+ */
+export function resolveRequestValidator(validator: ValidatorOptions | undefined): 'zod' | null {
+  if (!validator || validator === 'zod') return null
+  return validator.request ?? null
+}
+
+/**
+ * Returns `'zod'` when path, query, and header params parsing is enabled, `null` otherwise. Only the
+ * object form `{ params: 'zod' }` enables it.
+ */
+export function resolveParamsValidator(validator: ValidatorOptions | undefined): 'zod' | null {
+  if (!validator || validator === 'zod') return null
+  return validator.params ?? null
+}
+
+/**
+ * Returns `'zod'` when response parsing is enabled, `null` otherwise. The string shorthand `'zod'`
+ * maps to response parsing.
+ */
+export function resolveResponseValidator(validator: ValidatorOptions | undefined): 'zod' | null {
+  if (!validator) return null
+  if (validator === 'zod') return 'zod'
+  return validator.response ?? null
+}
+
+/**
+ * Builds the `validator.error` map of a call, one plugin-zod `<operation>StatusNNNSchema` per non-2xx response with a
+ * schema, such as `{ 404: getPetStatus404Schema, '5xx': getPetStatus5xxSchema }`. Returns `null` without one.
+ */
+export function buildZodErrorParse(node: ast.OperationNode, zodResolver: ResolverZod): { literal: string; names: Array<string> } | null {
+  const entries = node.responses
+    .filter((res) => !ast.http.status.isSuccess(res) && res.content?.some((entry) => entry.schema))
+    .map((res) => ({ key: String(res.statusCode), name: zodResolver.response.status(node, res.statusCode) }))
+  if (!entries.length) return null
+  const literal = entries.map(({ key, name }) => `${/^\d+$/.test(key) ? key : text.quote(key)}: ${name}`).join(', ')
+  return { literal: `{ ${literal} }`, names: entries.map(({ name }) => name) }
+}

package/src/clientTypes.ts

@@ -0,0 +1,195 @@
+import type { ReturnTypeOption } from '@internals/client'
+import type { ast, ResolverPatch, Exclude, Group, Include, Output, OutputOptions, Override, PluginType, Resolver } from '@kubb/kit'
+
+/**
+ * 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 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 the error body.
+ */
+export type ValidatorOptions = false | 'zod' | { request?: 'zod'; params?: 'zod'; response?: 'zod' }
+
+/**
+ * How the class-based SDK groups operations.
+ * - `'tag'`: one class per tag, optionally composed into a root client.
+ * - `'flat'`: one class with every operation as a direct method.
+ */
+export type Mode = 'tag' | 'flat'
+
+/**
+ * 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).
+ */
+export type ResolverClient = Resolver & {
+  /**
+   * Resolves the generated class name for class-based clients.
+   */
+  className(this: ResolverClient, name: string): string
+  /**
+   * Resolves the generated class name for a tag-based client group. The default appends a
+   * `Client` suffix (tag `pet` becomes `PetClient`) so the class never collides with the schema
+   * model of the same name in the barrel.
+   *
+   * @example
+   * `resolver.groupName('pet') // -> 'PetClient'`
+   */
+  groupName(this: ResolverClient, name: string): string
+  /**
+   * Resolves the property name a tag client is exposed under on the composed root SDK
+   * (`new PetStore(config).pet`).
+   */
+  propertyName(this: ResolverClient, name: string): string
+}
+
+/**
+ * The shared options surface for the client plugins. Deliberately small: there is one
+ * response contract and one grouped options object. Each plugin extends this with its own
+ * `transport` field.
+ */
+export type ClientOptions = OutputOptions & {
+  /**
+   * Skip operations matching at least one entry in the list.
+   */
+  exclude?: Array<Exclude>
+  /**
+   * Restrict generation to operations matching at least one entry in the list.
+   */
+  include?: Array<Include>
+  /**
+   * Apply a different options object to operations matching a pattern.
+   */
+  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 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
+  /**
+   * Default error behavior for generated operations and their client. Per-call `throwOnError`
+   * takes precedence.
+   *
+   * @default true
+   */
+  throwOnErrorDefault?: boolean
+  /**
+   * Validate the request body, the request params, and the response with schemas from `@kubb/plugin-zod`.
+   *
+   * @default false
+   */
+  validator?: ValidatorOptions
+  /**
+   * Shape of the value a generated operation function resolves to. Applies to the standalone
+   * functions and the class-based SDK. The query-hook plugins (`@kubb/plugin-react-query`,
+   * `@kubb/plugin-vue-query`, `@kubb/plugin-swr`) and `@kubb/plugin-mcp` read it to unwrap the
+   * call they make, and their own `returnType` sets what a hook resolves to.
+   *
+   * @default 'full'
+   * @example
+   * ```ts
+   * pluginAxios({ returnType: 'data' })
+   * // const pet = await getPetById({ path: { petId: 1 } }) // Pet, not { status, data, ... }
+   * ```
+   */
+  returnType?: ReturnTypeOption
+  /**
+   * Generates a class-based SDK instead of the standalone functions. Each tag client is an instance
+   * class whose constructor takes a client config and builds its own client, so every environment is
+   * a separate instance. Leave `sdk` unset to keep the standalone per-operation functions (the
+   * default), which is also what query plugins consume.
+   *
+   * @example Instance class per tag
+   * ```ts
+   * pluginFetch({ sdk: {} })
+   * // const api = new PetClient({ baseURL: 'https://api.example.com' })
+   * // await api.getPetById({ path: { petId: 1 } })
+   * ```
+   * @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
+   * ```ts
+   * pluginFetch({ sdk: { name: 'petStore', mode: 'flat' } })
+   * // const api = new PetStore({ baseURL })
+   * // await api.getPetById({ path: { petId: 1 } })
+   * ```
+   */
+  sdk?: {
+    /**
+     * How the SDK groups operations.
+     * - `'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'
+     */
+    mode?: Mode
+    /**
+     * Name of the generated entry point, also the file name. With `mode: 'tag'` it emits a
+     * composed root class that creates one client and shares it with every tag client. With
+     * `mode: 'flat'` it names the single class.
+     */
+    name?: string
+  }
+  /**
+   * Override how names and file paths are built. Methods you omit fall back to the default resolver.
+   */
+  resolver?: ResolverPatch<ResolverClient>
+  /**
+   * Macros applied to each operation node before code is printed.
+   */
+  macros?: Array<ast.Macro>
+}
+
+/**
+ * The resolved options after defaults are applied.
+ */
+export type ClientResolvedOptions = {
+  output: Output
+  exclude: Array<Exclude>
+  include: Array<Include> | undefined
+  override: Array<Override<Omit<ClientResolvedOptions, 'throwOnErrorDefault'>>>
+  group: Group | null
+  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<ClientOptions['validator']>
+  returnType: ReturnTypeOption
+  sdk:
+    | {
+        mode: Mode
+        name: string | undefined
+      }
+    | undefined
+  resolver: ResolverClient
+}
+
+/**
+ * The plugin type behind the shared resolver. Each concrete plugin (plugin-fetch, plugin-axios)
+ * declares its own name and registers itself; this base ties the shared builders, resolver, and
+ * components to one option/resolver shape.
+ */
+export type PluginContractClient = PluginType<'plugin-contract-client', ClientOptions, ClientResolvedOptions, ResolverClient>
+
+/**
+ * The shape any client plugin (plugin-fetch, plugin-axios) must satisfy to reuse the shared
+ * client and SDK generators. Pins the option, resolved-option, and resolver shapes while leaving
+ * the plugin name free.
+ */
+export type ContractClientFactory = PluginType<string, ClientOptions, ClientResolvedOptions, ResolverClient>

package/src/components/ClientRuntime.tsx

@@ -0,0 +1,97 @@
+import { objectKey } from '@internals/utils'
+import path from 'node:path'
+import { getFormContentTypes, hasEventStreamContent, hasStreamVariant, isEventStream } from '@internals/shared'
+
+import { ast, text } from '@kubb/kit'
+import { File } from '@kubb/renderer-jsx'
+import { buildSecuritySchemes } from '../builders/security.ts'
+import { hasQueryStyles } from '../builders/styles.ts'
+import type { KubbReactNode } from '@kubb/renderer-jsx'
+
+function buildServersExport(servers: Array<ast.InputServer> | undefined): string | null {
+  const named = ast.server.groupByName(servers)
+  if (!named.size) return null
+  const entries = [...named].map(([name, { url }]) => `${objectKey(name)}: ${text.quote(url)}`)
+  return `/**\n * The servers from the spec by name, for \`baseURL\`.\n */\nexport const servers = { ${entries.join(', ')} } as const`
+}
+
+// The form media types, each in its own file under `templates/mediaTypes/`, so a document ships only the ones it uses.
+const formMediaTypes = {
+  'multipart/form-data': { file: 'mediaTypes/formData', name: 'multipartFormData' },
+  'application/x-www-form-urlencoded': { file: 'mediaTypes/urlencoded', name: 'urlencoded' },
+} as const
+
+/**
+ * Writes the runtime a document needs into `.kubb/`: the optional media type, serializer and `sse.ts` files, and a
+ * `config.ts` that imports them, which `client.ts` passes to `setConfig`. The footer of `client.ts` gets the named
+ * `servers` and `securitySchemes` and the `sse.ts` re-export. `templates` is the folder the runtime is copied from, set
+ * by the plugins that ship it, so a custom client from `@kubb/plugin-client` gets none of this.
+ */
+export function ClientRuntime({
+  nodes,
+  root,
+  templates,
+  baseURL,
+  servers,
+  auth,
+}: {
+  nodes: Array<ast.OperationNode>
+  root: string
+  templates?: string
+  baseURL?: string
+  servers?: Array<ast.InputServer>
+  auth?: Array<ast.AuthScheme>
+}): KubbReactNode {
+  if (!templates) return null
+  const hasParameter = (match: (parameter: ast.ParameterNode) => boolean) => nodes.some((node) => node.parameters.some(match))
+  const streams = nodes.some((node) => hasEventStreamContent(node) || isEventStream(node) || hasStreamVariant(node))
+  const forms = [...new Set(nodes.flatMap(getFormContentTypes))].sort().map((contentType) => ({ contentType, ...formMediaTypes[contentType] }))
+  const queryStyles = nodes.some(hasQueryStyles)
+
+  const serializers = [
+    queryStyles
+      ? { key: 'query', file: 'serializers/queryStyles', name: 'serializeStyledQuery' }
+      : { key: 'query', file: 'serializers/query', name: 'serializeQuery' },
+    hasParameter((parameter) => parameter.in === 'path' && (parameter.style === 'label' || parameter.style === 'matrix'))
+      ? { key: 'path', file: 'serializers/pathStyles', name: 'serializeStyledPath' }
+      : { key: 'path', file: 'serializers/path', name: 'serializePath' },
+    hasParameter((parameter) => parameter.in === 'header') ? { key: 'header', file: 'serializers/headers', name: 'serializeHeaders' } : null,
+    hasParameter((parameter) => parameter.in === 'cookie') ? { key: 'cookie', file: 'serializers/cookies', name: 'serializeCookies' } : null,
+  ].filter((serializer) => serializer !== null)
+  const imports = [...forms, ...(streams ? [{ file: 'sse', name: 'streamMediaTypes' }] : []), ...serializers]
+  // `pathStyles.ts` builds on `path.ts`, and the urlencoded media type on `queryStyles.ts`.
+  const files = new Set([
+    ...imports.map(({ file }) => file),
+    'serializers/path',
+    ...(forms.some(({ name }) => name === 'urlencoded') ? ['serializers/queryStyles'] : []),
+  ])
+
+  const baseURLExpression = baseURL ? (baseURL.includes('${') ? `\`${baseURL.replaceAll('`', '\\`')}\`` : JSON.stringify(baseURL)) : undefined
+  const mediaTypes = [...forms.map(({ contentType, name }) => `'${contentType}': ${name}`), streams ? '...streamMediaTypes' : null].filter(Boolean)
+  const config = [
+    baseURLExpression ? `baseURL: ${baseURLExpression}` : null,
+    mediaTypes.length ? `mediaTypes: { ${mediaTypes.join(', ')} }` : null,
+    `serializer: { ${serializers.map(({ key, name }) => `${key}: ${name}`).join(', ')} }`,
+  ].filter(Boolean)
+  const footer = [buildServersExport(servers), buildSecuritySchemes(auth), streams ? `export * from './sse.ts'` : null].filter(Boolean).join('\n')
+  const configPath = path.resolve(root, '.kubb/config.ts')
+  const runtimePath = (file: string) => path.resolve(root, '.kubb', `${file}.ts`)
+
+  return (
+    <>
+      {[...files].map((file) => (
+        <File key={file} baseName={`${path.basename(file)}.ts`} path={runtimePath(file)} copy={path.join(templates, `${file}.ts`)} />
+      ))}
+      <File baseName="config.ts" path={configPath}>
+        {imports.map(({ file, name }) => (
+          <File.Import key={name} name={[name]} root={configPath} path={runtimePath(file)} />
+        ))}
+        <File.Import name={['ClientConfig']} root={configPath} path={runtimePath('core')} isTypeOnly />
+        <File.Source name="defaultConfig" isExportable>
+          {`/**\n * The config \`client.ts\` starts with: what this spec needs from the runtime.\n */\nexport const defaultConfig: ClientConfig = { ${config.join(', ')} }`}
+        </File.Source>
+      </File>
+      {footer && <File baseName="client.ts" path={path.resolve(root, '.kubb/client.ts')} footer={footer} />}
+    </>
+  )
+}

package/src/components/Operation.tsx

@@ -0,0 +1,72 @@
+import type { OperationTypeNames } from '@internals/client'
+import { buildOperationComments } from '@internals/shared'
+import { ast } from '@kubb/kit'
+import { File, Function } from '@kubb/renderer-jsx'
+import type { KubbReactNode } from '@kubb/renderer-jsx'
+import { buildOperationBody } from '../builders/operationBody.ts'
+import type { SecurityRequirement } from '../builders/security.ts'
+import type { ValidatorHooks } from '../builders/validator.ts'
+import type { ReturnTypeOption } from '../types.ts'
+
+type Props = {
+  /**
+   * The generated function name.
+   */
+  name: string
+  /**
+   * The operation being generated.
+   */
+  node: ast.OperationNode
+  /**
+   * The operation type names the signature references, from `plugin-ts` or `plugin-zod`'s inferred
+   * types.
+   */
+  types: OperationTypeNames
+  /**
+   * The operation's validator hooks, built once by the generator and shared with its zod imports.
+   */
+  validatorHooks: ValidatorHooks | null
+  /**
+   * Shape of the value the generated function resolves to.
+   */
+  returnType: ReturnTypeOption
+  throwOnErrorDefault: boolean
+  /**
+   * Per-operation security, resolved from the spec into inline security requirements and serialized onto the
+   * call config's `security` field for the runtime `auth` resolver to consume.
+   */
+  security?: Array<SecurityRequirement>
+  /** The operation's own server URL from a path-level or operation-level `servers` entry, emitted as the call's default `baseURL`. */
+  baseURL?: string
+}
+
+/**
+ * Renders one client operation: the grouped `<Name>Request` type and the function that forwards a
+ * single `options` object to the resolved client and returns the `Unwrappable<RequestResult>`. The
+ * type, signature, and call config are built with the AST factory, and only the jsx-renderer emits
+ * the source.
+ */
+export function Operation({ name, node, types, validatorHooks, returnType, throwOnErrorDefault, security, baseURL }: Props): KubbReactNode {
+  if (!ast.http.isOperation(node)) return null
+
+  const body = buildOperationBody({ node, types, validatorHooks, security, baseURL, returnType, throwOnErrorDefault })
+
+  return (
+    <File.Source name={name} isExportable isIndexable>
+      <Function
+        name={name}
+        export
+        generics={body.generics}
+        params={body.paramsSignature}
+        returnType={body.returnType}
+        JSDoc={{ comments: buildOperationComments(node, { splitLines: true }) }}
+      >
+        {body.mergeContentType
+          ? 'const { client: apiClient = client, contentType, ...config } = options'
+          : 'const { client: apiClient = client, ...config } = options'}
+        <br />
+        {body.statement}
+      </Function>
+    </File.Source>
+  )
+}

package/src/components/SdkClient.tsx

@@ -0,0 +1,100 @@
+import type { OperationTypeNames } from '@internals/client'
+import { buildOperationComments } from '@internals/shared'
+import { buildJSDoc } from '@internals/utils'
+import { ast } from '@kubb/kit'
+import { File } from '@kubb/renderer-jsx'
+import type { KubbReactNode } from '@kubb/renderer-jsx'
+import { buildOperationBody } from '../builders/operationBody.ts'
+import type { SecurityRequirement } from '../builders/security.ts'
+import type { ValidatorHooks } from '../builders/validator.ts'
+import type { ReturnTypeOption } from '../types.ts'
+
+/**
+ * Builds one instance method of a generated SDK class; a per-call `options.client` overrides `this.client`.
+ */
+export function buildSdkMethod({
+  node,
+  name,
+  types,
+  validatorHooks,
+  security,
+  baseURL,
+  returnType,
+  throwOnErrorDefault,
+}: {
+  node: ast.OperationNode
+  name: string
+  types: OperationTypeNames
+  validatorHooks: ValidatorHooks | null
+  security?: Array<SecurityRequirement>
+  baseURL?: string
+  returnType: ReturnTypeOption
+  throwOnErrorDefault: boolean
+}): string {
+  if (!ast.http.isOperation(node)) return ''
+
+  const body = buildOperationBody({ node, types, validatorHooks, security, baseURL, returnType, throwOnErrorDefault })
+  const generics = body.generics.length ? `<${body.generics.join(', ')}>` : ''
+  const jsdoc = buildJSDoc(buildOperationComments(node, { splitLines: true }))
+
+  const destructure = body.mergeContentType
+    ? 'const { client: apiClient = this.client, contentType, ...config } = options'
+    : 'const { client: apiClient = this.client, ...config } = options'
+  const methodBody = [destructure, '', body.statement].map((line) => (line ? `    ${line}` : '')).join('\n')
+
+  return `${jsdoc}  public ${name}${generics}(${body.paramsSignature}): ${body.returnType} {\n${methodBody}\n  }`
+}
+
+type OperationData = {
+  node: ast.OperationNode
+  name: string
+  types: OperationTypeNames
+  validatorHooks: ValidatorHooks | null
+  security?: Array<SecurityRequirement>
+  baseURL?: string
+}
+
+type Props = {
+  name: string
+  operations: Array<OperationData>
+  returnType: ReturnTypeOption
+  throwOnErrorDefault: boolean
+}
+
+/**
+ * Renders one instance class per tag with one method per operation. The constructor takes a client
+ * config object and builds its own client through `createClient`, so each environment is a separate
+ * instance: `const api = new PetClient({ baseURL }); api.getPetById(...)`. It also takes an existing
+ * client, which is how the root SDK shares one client across its tags. The client is public so callers
+ * can add interceptors, and a per-call `client` option still overrides it for a one-off call.
+ */
+export function SdkClient({ name, operations, returnType, throwOnErrorDefault }: Props): KubbReactNode {
+  const methods = operations.map(({ node, name: methodName, types, validatorHooks, security, baseURL }) =>
+    buildSdkMethod({
+      node,
+      name: methodName,
+      types,
+      validatorHooks,
+      security,
+      baseURL,
+      returnType,
+      throwOnErrorDefault,
+    }),
+  )
+
+  const constructor = [
+    '  readonly client: ClientInstance',
+    '',
+    '  constructor(config: ClientConfig | ClientInstance = {}) {',
+    "    this.client = typeof config === 'function' ? config : createClient(config)",
+    '  }',
+  ].join('\n')
+
+  const classCode = `export class ${name} {\n${constructor}\n\n${methods.join('\n\n')}\n}`
+
+  return (
+    <File.Source name={name} isExportable isIndexable>
+      {classCode}
+    </File.Source>
+  )
+}

package/src/components/SdkFacade.tsx

@@ -0,0 +1,35 @@
+import { File } from '@kubb/renderer-jsx'
+import type { KubbReactNode } from '@kubb/renderer-jsx'
+
+type Member = {
+  className: string
+  propName: string
+}
+
+type Props = {
+  name: string
+  members: Array<Member>
+}
+
+/**
+ * Renders a composed root SDK class that creates one client from the config and hands it to every tag
+ * client, so `new PetStore({ baseURL }).pet.getPetById(...)` reaches an operation through a single entry
+ * point bound to one environment. The shared client is the public `client` field, where interceptors
+ * registered once apply to every tag. The per-tag clients are read-only fields built in the constructor.
+ */
+export function SdkFacade({ name, members }: Props): KubbReactNode {
+  const fields = ['  readonly client: ClientInstance', ...members.map((member) => `  readonly ${member.propName}: ${member.className}`)]
+  const assignments = [
+    '    this.client = createClient(config)',
+    ...members.map((member) => `    this.${member.propName} = new ${member.className}(this.client)`),
+  ]
+  const body = [...fields, '', '  constructor(config: ClientConfig = {}) {', ...assignments, '  }'].join('\n')
+
+  const classCode = `export class ${name} {\n${body}\n}`
+
+  return (
+    <File.Source name={name} isExportable isIndexable>
+      {classCode}
+    </File.Source>
+  )
+}

package/src/generators/clientGenerator.tsx

@@ -1,9 +1,94 @@
-import { createClientGenerator } from '@internals/client'
-import type { PluginClient } from '../types.ts'
+import path from 'node:path'
+import { resolveOperationTypes, resultTypeName } from '@internals/client'
+import { getEventStream, operationFileEntry } from '@internals/shared'
+import { ast, defineGenerator } from '@kubb/kit'
+import type { Generator } from '@kubb/kit'
+import { File, jsxRenderer } from '@kubb/renderer-jsx'
+import { resolveOperationData } from '../builders/operationData.ts'
+import { buildEventStreamImports } from '../builders/returnStatement.ts'
+import { Operation } from '../components/Operation.tsx'
+import { ClientRuntime } from '../components/ClientRuntime.tsx'
+import type { ContractClientFactory } from '../types.ts'
 
 /**
- * Built-in operation generator for `@kubb/plugin-client`. Emits one async function per OpenAPI
- * operation using the shared `Operation` component: a grouped `<Name>Request` type and a function
- * that forwards a single `options` object to the user-provided client module and returns the `RequestResult`.
+ * Builds the per-operation client generator shared by the client plugins. `templates` is the folder the optional runtime, such as `sse.ts`, is copied from.
  */
-export const clientGenerator = createClientGenerator<PluginClient>('client')
+export function createClientGenerator<TFactory extends ContractClientFactory>(name: string, { templates }: { templates?: string } = {}): Generator<TFactory> {
+  return defineGenerator<TFactory>({
+    name,
+    renderer: jsxRenderer,
+    operations(nodes, ctx) {
+      return <ClientRuntime nodes={nodes} root={ctx.root} templates={templates} baseURL={ctx.options.baseURL} servers={ctx.meta.servers} auth={ctx.meta.auth} />
+    },
+    operation(node, ctx) {
+      if (!ast.http.isOperation(node)) return null
+
+      const { config, driver, resolver, root } = ctx
+      const { output, returnType, throwOnErrorDefault, group, importPath } = ctx.options
+
+      const resolvedTypes = resolveOperationTypes(driver, ctx.plugin.name)
+      // A custom client module keeps the two-argument `RequestResult` it documents, so its results get no typed headers.
+      const types = importPath === undefined ? resolvedTypes : { ...resolvedTypes, response: { ...resolvedTypes.response, headers: undefined } }
+
+      const data = resolveOperationData({ node, ctx, types })
+      const { validatorHooks, headerTypeNames } = data
+      const file = resolver.file({ ...operationFileEntry(node, node.operationId), root, output, group: group ?? undefined })
+      const importedTypeNames = [types.response.options(node), types.response.responses(node), ...headerTypeNames]
+
+      // A custom client module is emitted verbatim, so `importPath` is used exactly as configured.
+      // The default `.kubb/client.ts` is a file path and is made relative to the operation file.
+      const clientPath = importPath ?? path.resolve(root, '.kubb/client.ts')
+      const clientRoot = importPath === undefined ? file.path : undefined
+      // The headers validator helper ships in `.kubb/standardSchema.ts`; a custom client module exports it
+      // alongside its other runtime helpers.
+      const standardSchemaPath = importPath ?? path.resolve(root, '.kubb/standardSchema.ts')
+      const stream = getEventStream(node)
+
+      const clientValueImports = [
+        ...{
+          plain: ['client'],
+          data: ['client', 'unwrapResult', 'resolveThrowOnError'],
+          full: ['client', 'withUnwrap', 'resolveThrowOnError'],
+        }[returnType],
+        ...(importPath === undefined && data.security ? ['securitySchemes'] : []),
+      ]
+
+      const clientTypeImports = stream
+        ? buildEventStreamImports({ node, types, returnType })
+        : { plain: ['Options', 'RequestResult'], data: ['Options', 'UnwrappedResult'], full: ['Options', 'Unwrappable', 'RequestResult'] }[returnType].map(
+            (name) => (name.endsWith('Result') ? resultTypeName(name, headerTypeNames.length > 0) : name),
+          )
+
+      return (
+        <File
+          baseName={file.baseName}
+          path={file.path}
+          meta={file.meta}
+          banner={resolver.default.banner(ctx.meta, { output, config, file: { path: file.path, baseName: file.baseName } })}
+          footer={resolver.default.footer(ctx.meta, { output, config, file: { path: file.path, baseName: file.baseName } })}
+        >
+          <File.Import name={clientValueImports} root={clientRoot} path={clientPath} />
+          <File.Import name={clientTypeImports} root={clientRoot} path={clientPath} isTypeOnly />
+
+          <File.Import name={Array.from(new Set(importedTypeNames))} root={file.path} path={data.typeFile.path} isTypeOnly />
+
+          {data.zodFile && validatorHooks.importedZodNames.length > 0 && (
+            <File.Import name={validatorHooks.importedZodNames} root={file.path} path={data.zodFile.path} />
+          )}
+          {validatorHooks.headers && <File.Import name={['toHeadersStandardSchema']} root={clientRoot} path={standardSchemaPath} />}
+
+          <Operation
+            name={data.name}
+            node={node}
+            types={types}
+            validatorHooks={validatorHooks}
+            returnType={returnType}
+            throwOnErrorDefault={throwOnErrorDefault}
+            security={data.security}
+            baseURL={data.baseURL}
+          />
+        </File>
+      )
+    },
+  })
+}