@kubb/plugin-client 5.12.0 → 6.0.1

package/src/builders/generics.ts

@@ -0,0 +1,29 @@
+import type { ast } from '@kubb/kit'
+import { buildResponseHeadersType, buildResultTypeRef, type OperationTypeNames } from '@internals/client'
+import type { ReturnTypeOption } from '../types.ts'
+
+/**
+ * Builds the `RequestResult` type arguments of one operation: responses, `ThrowOnError` and the response headers, when a response declares any.
+ *
+ * @example
+ * `buildRequestResultGenerics({ node, types }) // "LoginUserResponses, ThrowOnError, { '200': LoginUserStatus200Headers }"`
+ */
+export function buildRequestResultGenerics({ node, types }: { node: ast.OperationNode; types: OperationTypeNames }): string {
+  return [types.response.responses(node), 'ThrowOnError', buildResponseHeadersType({ node, types })].filter(Boolean).join(', ')
+}
+
+/**
+ * Builds the full return type an operation's function signature uses: `Unwrappable<RequestResult>`
+ * for the default `returnType: 'full'`, already a promise so no further wrapping is needed, a plain
+ * `Promise<RequestResult>` for the internal `'plain'` shape, or a
+ * `Promise` of the runtime's `UnwrappedResult` when `returnType: 'data'` narrows a resolved call
+ * down to the bare success body.
+ *
+ * @example
+ * `buildResultType({ node, types, returnType: 'data' }) // 'Promise<UnwrappedResult<AddPetResponses, ThrowOnError>>'`
+ */
+export function buildResultType({ node, types, returnType }: { node: ast.OperationNode; types: OperationTypeNames; returnType: ReturnTypeOption }): string {
+  const name = returnType === 'data' ? 'UnwrappedResult' : 'RequestResult'
+  const result = buildResultTypeRef(name, types.response.responses(node), buildResponseHeadersType({ node, types }), ['ThrowOnError'])
+  return returnType === 'full' ? `Unwrappable<${result}>` : `Promise<${result}>`
+}

package/src/builders/operationBody.ts

@@ -0,0 +1,43 @@
+import type { ast } from '@kubb/kit'
+import type { OperationTypeNames } from '@internals/client'
+import type { ReturnTypeOption } from '../types.ts'
+import { buildCallConfig } from './callConfig.ts'
+import { buildEventStreamReturn, buildReturnStatement } from './returnStatement.ts'
+import type { SecurityRequirement } from './security.ts'
+import { buildGroupedOptionsSignature } from './signature.ts'
+import type { ValidatorHooks } from './validator.ts'
+
+/**
+ * The pieces of a generated operation: its generics, `options` parameter, return type, return statement, and whether the
+ * body destructures `contentType` from `options`. Shared by the standalone functions and the SDK methods, so a
+ * streamed operation is wired to `apiClient.stream` in one place.
+ */
+export function buildOperationBody({
+  node,
+  types,
+  validatorHooks,
+  security,
+  baseURL,
+  returnType,
+  throwOnErrorDefault,
+}: {
+  node: ast.HttpOperationNode
+  types: OperationTypeNames
+  validatorHooks: ValidatorHooks | null
+  security?: Array<SecurityRequirement>
+  baseURL?: string
+  returnType: ReturnTypeOption
+  throwOnErrorDefault: boolean
+}): { generics: Array<string>; paramsSignature: string; returnType: string; statement: string; mergeContentType: boolean } {
+  const { callConfig, mergeContentType, eventStream } = buildCallConfig({ node, validatorHooks, security, baseURL, throwOnErrorDefault, returnType })
+  const signature = buildGroupedOptionsSignature({ node, types, returnType, throwOnErrorDefault, eventStream })
+  const stream = eventStream ? buildEventStreamReturn({ node, types, callConfig, returnType, throwOnErrorDefault }) : null
+
+  return {
+    generics: signature.generics,
+    paramsSignature: signature.paramsSignature,
+    returnType: stream?.returnType ?? signature.returnType,
+    statement: stream?.statement ?? buildReturnStatement({ node, types, callConfig, returnType, throwOnErrorDefault }),
+    mergeContentType,
+  }
+}

package/src/builders/operationData.ts

@@ -0,0 +1,64 @@
+import { getResponseHeadersTypeNames, type OperationTypeNames, type OperationTypeSource } from '@internals/client'
+import { operationKey, resolveOperationFile } from '@internals/shared'
+import { ast, type Generator } from '@kubb/kit'
+import { pluginZodName } from '@kubb/plugin-zod'
+import type { ContractClientFactory } from '../types.ts'
+import { getOperationSecurity, type SecurityRequirement } from './security.ts'
+import { buildValidatorHooks, type ValidatorHooks } from './validator.ts'
+import { isValidatorEnabled } from './validatorOptions.ts'
+
+export type GeneratorContext = Parameters<NonNullable<Generator<ContractClientFactory>['operations']>>[1]
+
+export type OperationData = {
+  node: ast.HttpOperationNode
+  name: string
+  types: OperationTypeNames
+  typeFile: ast.FileNode
+  /**
+   * `null` unless `validator` turns a direction on.
+   */
+  zodFile: ast.FileNode | null
+  validatorHooks: ValidatorHooks
+  /**
+   * The names of the headers types the result references.
+   */
+  headerTypeNames: Array<string>
+  security?: Array<SecurityRequirement>
+  baseURL?: string
+}
+
+/**
+ * Resolves what the function and SDK generators both print for one operation: its name, the files its types and zod
+ * schemas come from, and its validator hooks, security, base URL and response headers types.
+ */
+export function resolveOperationData({ node, ctx, types }: { node: ast.HttpOperationNode; ctx: GeneratorContext; types: OperationTypeSource }): OperationData {
+  const { driver, resolver, root } = ctx
+  const { output, validator, importPath } = ctx.options
+  const pluginZod = isValidatorEnabled(validator) ? driver.getPlugin(pluginZodName) : null
+  const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : null
+
+  return {
+    node,
+    name: resolver.resolveName({ key: operationKey(node), name: resolver.name(node.operationId) }),
+    types,
+    typeFile: resolveOperationFile({ ctx, node, resolver: types.resolver, root, output: types.output ?? output, group: types.group }),
+    zodFile:
+      zodResolver && pluginZod?.options
+        ? resolveOperationFile({
+            ctx,
+            node,
+            resolver: zodResolver,
+            root,
+            output: pluginZod.options.output ?? output,
+            group: pluginZod.options.group ?? undefined,
+          })
+        : null,
+    validatorHooks: buildValidatorHooks({ node, validator, zodResolver }),
+    headerTypeNames: getResponseHeadersTypeNames({ node, types }),
+    // The fetch and axios clients write `securitySchemes` into `.kubb/client.ts`. A custom client module has none.
+    security: getOperationSecurity({ auth: node.auth, schemes: ctx.meta.auth, hoist: importPath === undefined }),
+    baseURL: ast.http.getBaseURL(
+      ast.server.get({ servers: node.servers, index: (ctx.adapter.options as { server?: { index?: number } } | undefined)?.server?.index }),
+    ),
+  }
+}

package/src/builders/returnStatement.ts

@@ -0,0 +1,103 @@
+import { getEventStream } from '@internals/shared'
+import type { ast } from '@kubb/kit'
+import { buildResponseHeadersType, buildResultTypeRef, resultTypeName, type OperationTypeNames } from '@internals/client'
+import type { ReturnTypeOption } from '../types.ts'
+import { buildRequestResultGenerics } from './generics.ts'
+
+/**
+ * Builds the return statement of a generated operation function. The client call takes the responses record and
+ * `ThrowOnError` as type arguments, so its result is already the operation's `RequestResult` and needs no cast. With the
+ * default `returnType: 'full'` it is wrapped in `withUnwrap`, so the caller can `await` it or call `.unwrap()`. With
+ * `returnType: 'data'` it goes through `unwrapResult`, which keeps the success body when the call throws on errors.
+ * With `returnType: 'plain'` it is returned as is.
+ *
+ * @example
+ * `return withUnwrap(apiClient<AddPetResponses, ThrowOnError>({ method: 'POST', url: '/pet', ...config }))`
+ * @example
+ * `return unwrapResult(apiClient<AddPetResponses, ThrowOnError>({ ... }), resolveThrowOnError(config.throwOnError, true))`
+ * @example
+ * `return apiClient<AddPetResponses, ThrowOnError>({ method: 'POST', url: '/pet', ...config })`
+ */
+export function buildReturnStatement({
+  node,
+  types,
+  callConfig,
+  returnType,
+  throwOnErrorDefault,
+}: {
+  node: ast.OperationNode
+  types: OperationTypeNames
+  callConfig: string
+  returnType: ReturnTypeOption
+  throwOnErrorDefault: boolean
+}): string {
+  const call = `apiClient<${buildRequestResultGenerics({ node, types })}>(${callConfig})`
+  if (returnType === 'data') return `return unwrapResult(${call}, resolveThrowOnError(config.throwOnError, ${throwOnErrorDefault}))`
+  if (returnType === 'plain') return `return ${call}`
+  return `return withUnwrap(${call})`
+}
+
+/**
+ * Builds the return type and statement of a streamed operation, which calls `apiClient.stream`. The item type is
+ * `TypedEvent<...>` when each event declares its own `event` and `data`, the success type itself for JSON Lines, and
+ * otherwise the default, `ServerSentEvent` around the payload, which needs no type argument.
+ */
+export function buildEventStreamReturn({
+  node,
+  types,
+  callConfig,
+  returnType,
+  throwOnErrorDefault,
+}: {
+  node: ast.HttpOperationNode
+  types: OperationTypeNames
+  callConfig: string
+  returnType: ReturnTypeOption
+  throwOnErrorDefault: boolean
+}): {
+  returnType: string
+  statement: string
+} {
+  const shape = getEventStream(node) ?? 'data'
+  const responses = types.response.responses(node)
+  const headers = buildResponseHeadersType({ node, types })
+  const success = `SuccessOf<${responses}>`
+  const item = { event: `TypedEvent<${success}>`, data: null, line: success }[shape]
+  // The headers come after the item in `client.stream`, so a typed-headers call spells out the default item.
+  const callItem = item ?? (headers ? `ServerSentEvent<${success}>` : null)
+  const call = `apiClient.stream<${[responses, 'ThrowOnError', callItem, headers].filter(Boolean).join(', ')}>(${callConfig})`
+  const result = (name: string) => buildResultTypeRef(name, responses, headers, ['ThrowOnError', item])
+  if (returnType === 'plain') return { returnType: `Promise<${result('StreamResult')}>`, statement: `return ${call}` }
+  if (returnType === 'data') {
+    return {
+      returnType: `Promise<${result('UnwrappedStreamResult')}>`,
+      statement: `return unwrapResult(${call}, resolveThrowOnError(config.throwOnError, ${throwOnErrorDefault}))`,
+    }
+  }
+  return { returnType: `Unwrappable<${result('StreamResult')}>`, statement: `return withUnwrap(${call})` }
+}
+
+/**
+ * The stream types an operation file imports from the client for one streamed operation: the result and options types
+ * for `returnType`, their `WithHeaders` form when the response declares headers, and `SuccessOf` with `TypedEvent` or
+ * `ServerSentEvent` for an item type the call spells out.
+ */
+export function buildEventStreamImports({
+  node,
+  types,
+  returnType,
+}: {
+  node: ast.OperationNode
+  types: OperationTypeNames
+  returnType: ReturnTypeOption
+}): Array<string> {
+  const shape = getEventStream(node) ?? 'data'
+  const headers = buildResponseHeadersType({ node, types }) !== null
+  const result = {
+    plain: ['Options', 'StreamResult'],
+    full: ['StreamOptions', 'Unwrappable', 'StreamResult'],
+    data: ['StreamOptions', 'UnwrappedStreamResult'],
+  }[returnType].map((name) => (name.endsWith('Result') ? resultTypeName(name, headers) : name))
+  const item = { event: ['SuccessOf', 'TypedEvent'], data: headers ? ['SuccessOf', 'ServerSentEvent'] : [], line: ['SuccessOf'] }[shape]
+  return [...result, ...item]
+}

package/src/builders/security.ts

@@ -0,0 +1,125 @@
+import { isValidVarName, objectKey, toLiteral } from '@internals/utils'
+import { ast, text } from '@kubb/kit'
+
+/**
+ * A resolved security scheme. The runtime calls the configured `auth` resolver with this object and places the
+ * returned token: `http` bearer/basic on `Authorization`, `apiKey` under `name` in the header/query/cookie, and
+ * `oauth2`/`openIdConnect` as a bearer token.
+ */
+export type Auth = {
+  type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect'
+  scheme?: 'bearer' | 'basic'
+  name?: string
+  in?: 'header' | 'query' | 'cookie'
+  scopes?: Array<string>
+  flows?: Record<string, Omit<ast.OAuthFlow, 'scopes'>>
+  metadataUrl?: string
+  url?: string
+}
+
+/**
+ * One entry of a generated call's `security` array: an OpenAPI security requirement, as one scheme or as the schemes it
+ * needs together. The runtime sends the first requirement whose schemes all resolve a token.
+ */
+export type SecurityRequirement = OperationAuth | Array<OperationAuth>
+
+/**
+ * A scheme of one operation. `ref` names its entry in `securitySchemes`, which the call then points at.
+ */
+type OperationAuth = Auth & { ref?: string }
+
+// The order the keys of an inline scheme are printed in.
+const inlineAuthKeys = ['type', 'scheme', 'name', 'in', 'scopes', 'flows', 'metadataUrl', 'url'] as const
+
+function serializeScheme({ ref, ...auth }: OperationAuth): string {
+  const scopes = auth.scopes?.length ? auth.scopes : undefined
+  if (ref) {
+    const schemeRef = isValidVarName(ref) ? `securitySchemes.${ref}` : `securitySchemes[${text.quote(ref)}]`
+    return scopes ? `{ ...${schemeRef}, scopes: ${toLiteral(scopes)} }` : schemeRef
+  }
+  const entries = inlineAuthKeys.flatMap((key) => {
+    const entryValue = key === 'scopes' ? scopes : auth[key]
+    return entryValue ? [`${key}: ${toLiteral(entryValue)}`] : []
+  })
+  return `{ ${entries.join(', ')} }`
+}
+
+function serializeRequirement(requirement: SecurityRequirement): string {
+  return Array.isArray(requirement) ? `[${requirement.map(serializeScheme).join(', ')}]` : serializeScheme(requirement)
+}
+
+/**
+ * Maps an AST credential to the inline `Auth` object, or `null` for `mutualTLS`, which the runtime cannot send.
+ * `http` schemes other than `basic` are treated as bearer. OAuth2 and OpenID Connect keep their URLs for the `auth` resolver.
+ */
+export function resolveCredential(credential: ast.AuthCredential): Auth | null {
+  if (credential.type === 'apiKey') return { type: 'apiKey', name: credential.name, in: credential.in }
+  if (credential.type === 'http') return { type: 'http', scheme: credential.scheme === 'basic' ? 'basic' : 'bearer' }
+  if (credential.type === 'oauth2') {
+    const flows = Object.fromEntries(Object.entries(credential.flows).map(([name, { scopes: _scopes, ...urls }]) => [name, urls]))
+    return {
+      type: 'oauth2',
+      ...(Object.keys(flows).length ? { flows } : {}),
+      ...(credential.metadataUrl ? { metadataUrl: credential.metadataUrl } : {}),
+    }
+  }
+  if (credential.type === 'openIdConnect') return { type: 'openIdConnect', ...(credential.url ? { url: credential.url } : {}) }
+  return null
+}
+
+/**
+ * Derives the per-operation security metadata from `OperationNode.auth` and the document's `meta.auth` schemes. Each
+ * requirement becomes one entry: its scheme, or an array of its schemes when it needs several together. A requirement
+ * with a scheme the runtime cannot place or that is not declared is left out, since it can never be met, and so is a
+ * repeated one. With `hoist`, each scheme carries its name as `ref`.
+ *
+ * @example
+ * `getOperationSecurity({ auth: [[{ scheme: 'bearerAuth' }]], schemes: meta.auth })`
+ * `// [{ type: 'http', scheme: 'bearer' }]`
+ * @example
+ * `// auth: [[{ scheme: 'api_key' }, { scheme: 'session' }]] gives [[{ type: 'apiKey', ... }, { type: 'apiKey', ... }]]`
+ */
+export function getOperationSecurity({
+  auth,
+  schemes,
+  hoist,
+}: {
+  auth: Array<ast.AuthRequirement> | undefined
+  schemes: Array<ast.AuthScheme> | undefined
+  hoist?: boolean
+}): Array<SecurityRequirement> | undefined {
+  const security = ast.auth.getRequirements({ auth, schemes }).flatMap((requirement): Array<SecurityRequirement> => {
+    const resolved = requirement.map(({ name, credential, scopes }) => {
+      const entry = resolveCredential(credential)
+      return entry && { ...entry, ...(scopes.length ? { scopes } : {}), ...(hoist ? { ref: name } : {}) }
+    })
+    if (!resolved.length || !resolved.every((entry): entry is OperationAuth => entry !== null)) return []
+    return [resolved.length === 1 ? resolved[0]! : resolved]
+  })
+
+  return security.length ? security : undefined
+}
+
+/**
+ * Serializes the per-operation security into the literal emitted on each generated call's `security`
+ * field. The runtime `resolveAuth` helper walks it, calling the configured `auth` resolver per scheme.
+ *
+ * @example
+ * `buildSecurityMetadata({ security: [{ type: 'http', scheme: 'bearer' }] }) // "[{ type: 'http', scheme: 'bearer' }]"`
+ */
+export function buildSecurityMetadata({ security }: { security?: Array<SecurityRequirement> }): string | null {
+  if (!security?.length) return null
+  return `[${security.map(serializeRequirement).join(', ')}]`
+}
+
+/**
+ * The `securitySchemes` const of `.kubb/client.ts`: every scheme the runtime can place, by name, or `null` without one.
+ */
+export function buildSecuritySchemes(schemes: Array<ast.AuthScheme> | undefined): string | null {
+  const entries = (schemes ?? []).flatMap(({ name, credential }) => {
+    const auth = resolveCredential(credential)
+    return auth ? [`${objectKey(name)}: ${serializeScheme(auth)}`] : []
+  })
+  if (!entries.length) return null
+  return `/**\n * The security schemes from the spec by name. A generated call sends one of them to the \`auth\` resolver.\n */\nexport const securitySchemes = { ${entries.join(', ')} } as const`
+}

package/src/builders/signature.ts

@@ -0,0 +1,71 @@
+import type { ast } from '@kubb/kit'
+import { getRequestGroupOptionality } from '@internals/shared'
+import { createFunctionParameter, createFunctionParameters, functionPrinter } from '@kubb/plugin-ts'
+import type { OperationTypeNames } from '@internals/client'
+import type { ReturnTypeOption } from '../types.ts'
+import { buildResultType } from './generics.ts'
+
+const declarationPrinter = functionPrinter({ mode: 'declaration' })
+
+/**
+ * The pieces of a generated operation function's grouped-options signature.
+ */
+export type GroupedOptionsSignature = {
+  /**
+   * The single function parameter: `options: Options<<Name>Options, ThrowOnError>`, or `StreamOptions<...>`
+   * for a `text/event-stream` operation.
+   */
+  paramsSignature: string
+  /**
+   * The function return type: `Unwrappable<RequestResult<<Name>Responses, ThrowOnError>>`.
+   */
+  returnType: string
+  /**
+   * The function generics. One per-call `ThrowOnError` flag, defaulting to the plugin setting.
+   */
+  generics: Array<string>
+}
+
+/**
+ * Builds the grouped-options signature for one operation: a single `options` object whose `TData`
+ * is the `<Name>Options` type, and a `RequestResult` return type keyed to the per-status responses
+ * record. There are no positional arguments.
+ *
+ * The generated file imports `<Name>Options` and `<Name>Responses` and uses them directly, so no
+ * per-operation input type has to be emitted. Both names come from `types`, which is `plugin-ts` or
+ * `plugin-zod`'s inferred types (see `resolveOperationTypes`).
+ */
+export function buildGroupedOptionsSignature({
+  node,
+  types,
+  returnType,
+  throwOnErrorDefault,
+  eventStream = false,
+}: {
+  node: ast.OperationNode
+  types: OperationTypeNames
+  returnType: ReturnTypeOption
+  throwOnErrorDefault: boolean
+  /**
+   * Adds the per-call stream options to the `options` type of a `text/event-stream` operation, except for a plain custom
+   * client, whose own `client.stream` returns a `StreamResult` and types its config itself.
+   */
+  eventStream?: boolean
+}): GroupedOptionsSignature {
+  const optionsName = types.response.options(node)
+  const optionsType = `${eventStream && returnType !== 'plain' ? 'StreamOptions' : 'Options'}<${optionsName}, ThrowOnError>`
+  const { isOptional } = getRequestGroupOptionality(node)
+
+  const paramsSignature =
+    declarationPrinter.print(
+      createFunctionParameters({
+        params: [createFunctionParameter({ name: 'options', type: optionsType, ...(isOptional ? { default: '{}' } : {}) })],
+      }),
+    ) ?? ''
+
+  return {
+    paramsSignature,
+    returnType: buildResultType({ node, types, returnType }),
+    generics: [`ThrowOnError extends boolean = ${throwOnErrorDefault}`],
+  }
+}

package/src/builders/styles.ts

@@ -0,0 +1,94 @@
+import { isValidVarName } from '@internals/utils'
+import { ast, text } from '@kubb/kit'
+
+type StyledLocation = 'path' | 'query' | 'header' | 'cookie'
+
+/**
+ * Renders a parameter name as an object-literal key, quoted when it is not a bare identifier. Every
+ * location keeps the spec name: the runtime looks path styles up by the `{name}` placeholder in the
+ * URL, and the other locations by the key it serializes.
+ */
+function toKey(name: string): string {
+  return isValidVarName(name) ? name : JSON.stringify(name)
+}
+
+/**
+ * Serializes one parameter's metadata into a `{ style, explode, allowReserved, contentType }`
+ * literal, or `null` when the parameter carries none. Path and query carry the serialization
+ * `style`. Header and cookie have a fixed style (`simple` and `form`), so they emit only `explode`,
+ * plus `style: 'cookie'` when a cookie parameter sets the OpenAPI 3.2 `cookie` style.
+ * `allowReserved` only applies to query parameters, and `contentType` to every location except path.
+ */
+function serializeParameter(parameter: ast.ParameterNode): string | null {
+  const parts = [
+    (parameter.in === 'path' || parameter.in === 'query') && parameter.style && `style: '${parameter.style}'`,
+    parameter.in === 'cookie' && parameter.style === 'cookie' && `style: 'cookie'`,
+    parameter.explode !== undefined && `explode: ${parameter.explode}`,
+    parameter.in === 'query' && parameter.allowReserved !== undefined && `allowReserved: ${parameter.allowReserved}`,
+    parameter.in !== 'path' && parameter.contentType && `contentType: ${text.quote(parameter.contentType)}`,
+    parameter.in === 'querystring' && 'querystring: true',
+  ].filter(Boolean)
+  return parts.length > 0 ? `{ ${parts.join(', ')} }` : null
+}
+
+/**
+ * Whether a query parameter of the operation has a style entry, so the call needs the styled query serializer.
+ */
+export function hasQueryStyles(node: ast.OperationNode): boolean {
+  return ast.http.isOperation(node) && ast.http.groupParameters(node).query.some((parameter) => serializeParameter(parameter) !== null)
+}
+
+/**
+ * Serializes the `encoding` of the request body's default content type into `property: { ... }`
+ * entries, empty when it carries none. Only an operation with a single request content type
+ * emits it, because the runtime applies `styles.body` to whichever type the caller selects.
+ */
+function serializeBodyEncoding(node: ast.HttpOperationNode): Array<string> {
+  const content = node.requestBody?.content
+  return Object.entries(content?.length === 1 ? (content[0]?.encoding ?? {}) : {}).map(([property, { contentType, style, explode, allowReserved }]) => {
+    const parts = [
+      style && `style: ${JSON.stringify(style)}`,
+      explode !== undefined && `explode: ${explode}`,
+      allowReserved !== undefined && `allowReserved: ${allowReserved}`,
+      contentType && `contentType: ${JSON.stringify(contentType)}`,
+    ].filter(Boolean)
+    return `${isValidVarName(property) ? property : JSON.stringify(property)}: { ${parts.join(', ')} }`
+  })
+}
+
+/**
+ * Builds the per-operation `styles` literal from the operation's parameters, grouped by location.
+ * Entries are keyed by the spec name of the parameter.
+ * Only parameters whose source defines `style`, `explode`, `allowReserved`, or `contentType` are
+ * emitted, so calls without serialization metadata keep the runtime defaults and existing output
+ * is unchanged. A form request body adds a `body` group keyed by property name from its `encoding`.
+ * Returns `null` when nothing carries metadata.
+ *
+ * With `merge`, the literal spreads `config.styles` per parameter, so a per-call entry overrides the generated one for
+ * that parameter and leaves the others in place.
+ *
+ * @example
+ * ```ts
+ * // a path param with { style: 'matrix', explode: true } and a query param with { explode: false }
+ * buildStyles({ node }) // "{ path: { id: { style: 'matrix', explode: true } }, query: { tags: { explode: false } } }"
+ * ```
+ */
+export function buildStyles({ node, merge }: { node: ast.OperationNode; merge?: boolean }): string | null {
+  if (!ast.http.isOperation(node)) return null
+
+  const groups: Record<StyledLocation | 'body', Array<string>> = { path: [], query: [], header: [], cookie: [], body: serializeBodyEncoding(node) }
+
+  for (const [location, parameters] of Object.entries(ast.http.groupParameters(node)) as Array<[StyledLocation, Array<ast.ParameterNode>]>) {
+    for (const parameter of parameters) {
+      const literal = serializeParameter(parameter)
+      if (literal) groups[location].push(`${toKey(parameter.name)}: ${literal}`)
+    }
+  }
+
+  const entries = Object.entries(groups)
+    .filter(([, items]) => items.length > 0)
+    .map(([location, items]) => `${location}: { ${(merge ? [...items, `...config.styles?.${location}`] : items).join(', ')} }`)
+
+  if (entries.length === 0) return null
+  return `{ ${(merge ? ['...config.styles', ...entries] : entries).join(', ')} }`
+}

package/src/builders/validator.ts

@@ -0,0 +1,84 @@
+import { ast } from '@kubb/kit'
+import type { ResolverZod } from '@kubb/plugin-zod'
+import type { ValidatorOptions } from '../types.ts'
+import { buildZodErrorParse, resolveParamsValidator, resolveRequestValidator, resolveResponseValidator } from './validatorOptions.ts'
+
+/**
+ * The per-call validator references a generated function wires into its request config. Each hook is
+ * the bare schema reference passed to the runtime's `validator.request` / `validator.path` /
+ * `validator.query` / `validator.headers` / `validator.cookies` / `validator.response` / `validator.error` slot. `client.ts`
+ * runs it through `validateStandardSchema`. The response validator only ever sees success (2xx) bodies.
+ */
+export type ValidatorHooks = {
+  /**
+   * Schema reference for the `validator.request` hook, or `null` when request validation is off.
+   */
+  request: string | null
+  /**
+   * Schema references for the `validator.path` / `query` / `headers` / `cookies` hooks (`headers` wrapped in
+   * `toHeadersStandardSchema`), or `null` when params validation is off or the group is empty.
+   */
+  path: string | null
+  query: string | null
+  headers: string | null
+  cookies: string | null
+  /**
+   * Schema reference for the `validator.response` hook, or `null` when response validation is off.
+   */
+  response: string | null
+  /** Per-status schema map for `validator.error`, such as `{ 404: getPetStatus404Schema }`, or `null` when off or absent. */
+  error: string | null
+  /**
+   * Zod schema names the generated file imports from the zod plugin output.
+   */
+  importedZodNames: Array<string>
+}
+
+/**
+ * Builds the validator-hook references for one operation. Request body and params validation run before the send.
+ * Response validation runs on the success body only. Returns `null` references when the matching
+ * direction is disabled or the schema is absent.
+ */
+export function buildValidatorHooks({
+  node,
+  validator,
+  zodResolver,
+}: {
+  node: ast.OperationNode
+  validator: ValidatorOptions | undefined
+  zodResolver: ResolverZod | null | undefined
+}): ValidatorHooks {
+  const hasRequestBody = Boolean(ast.http.requestBody.getSchema(node))
+  const parsesResponse = zodResolver && resolveResponseValidator(validator) === 'zod'
+
+  // Success responses validate with the success-only `<operation>ResponseSchema`; error bodies with the schema of their status.
+  // plugin-zod emits that schema only for an operation with a response body schema.
+  const hasResponseSchema = node.responses.some((res) => res.content?.some((entry) => entry.schema))
+  const response = parsesResponse && hasResponseSchema ? zodResolver.response.response(node) || null : null
+  const errorParse = parsesResponse ? buildZodErrorParse(node, zodResolver) : null
+  const request = zodResolver && resolveRequestValidator(validator) === 'zod' && hasRequestBody ? zodResolver.response.body(node) || null : null
+
+  const paramGroups = ast.http.groupParameters(node)
+  const resolveParamsName = (kind: 'path' | 'query' | 'headers' | 'cookies', params: Array<ast.ParameterNode>): string | null =>
+    zodResolver && resolveParamsValidator(validator) === 'zod' && params.length > 0 ? zodResolver.param[kind](node, params[0]!) : null
+  const path = resolveParamsName('path', paramGroups.path)
+  const query = resolveParamsName('query', paramGroups.query)
+  const headers = resolveParamsName('headers', paramGroups.header)
+  const cookies = resolveParamsName('cookies', paramGroups.cookie)
+
+  // Order is output: the generated file imports the response schema, then the error schemas, then the request body and params schemas.
+  const importedZodNames = [response, ...(errorParse?.names ?? []), request, path, query, headers, cookies].filter((name): name is string => Boolean(name))
+
+  const headersValidator = headers ? `toHeadersStandardSchema(${headers}, ${headers}.shape)` : null
+
+  return { request, path, query, headers: headersValidator, cookies, response, error: errorParse?.literal ?? null, importedZodNames }
+}
+
+/**
+ * Prints the `validator: { … }` entry of a call config from the hooks named in `keys`, or `null` when none is set.
+ * The entry spreads `config.validator` last, so a per-call hook overrides the generated one for its key only.
+ */
+export function buildValidatorLiteral(hooks: ValidatorHooks | null, keys: ReadonlyArray<keyof Omit<ValidatorHooks, 'importedZodNames'>>): string | null {
+  const entries = keys.flatMap((key) => (hooks?.[key] ? [`${key}: ${hooks[key]}`] : []))
+  return entries.length ? `validator: { ${entries.join(', ')}, ...config.validator }` : null
+}