@kubb/plugin-axios 5.0.0-beta.76 → 5.0.0-beta.79

package/templates/axios.ts

@@ -1,36 +1,56 @@
 import axios from 'axios'
 import type { AxiosError, AxiosInstance, AxiosRequestConfig, AxiosResponse, InternalAxiosRequestConfig } from 'axios'
+import { applyHeaderStyles, defaultBodySerializer, defaultPathSerializer, defaultQuerySerializer, serializeCookies } from './serializers'
+import type { HeadersInit, PathParamStyle, PathSerializer, Serializers, Styles } from './serializers'
+import { type StandardSchemaValidator, validateStandardSchema } from './standardSchema.ts'
 
 /**
- * HTTP status codes treated as a success. A resolved call only ever carries a body from one of
- * these; everything else is an error (thrown by default, or surfaced on `error`).
+ * HTTP status codes treated as a success, everything else is an error.
  */
 export type SuccessStatusCode = '200' | '201' | '202' | '203' | '204' | '205' | '206' | '207' | '208' | '226'
 
 /**
- * The success members of a per-status responses record (`{ '200': ...; '404': ... }`).
+ * The success members of a per-status responses record.
  */
 export type SuccessOf<TResponses> = TResponses[Extract<keyof TResponses, SuccessStatusCode>]
 
 /**
- * The error members of a per-status responses record — every documented status that is not a 2xx.
+ * The error members of a per-status responses record, every documented status that is not a 2xx.
  */
 export type ErrorOf<TResponses> = TResponses[Exclude<keyof TResponses, SuccessStatusCode>]
 
 /**
- * Converts a response record's string status key to its numeric literal (`'200'` becomes `200`).
- * Non-numeric keys such as the OpenAPI `default` response stay `number`.
+ * Converts a response record's string status key to its numeric literal, leaving non-numeric keys like `default` as `number`.
  */
 export type ToStatusNumber<TStatus> = TStatus extends `${infer TNumber extends number}` ? TNumber : number
 
 /**
- * One result variant for a single documented status. `status` is the numeric literal at the top
- * level, so a `switch (result.status)` narrows `data` (a 2xx status) or `error` (everything else) to
- * that status's payload.
+ * The plain body of a per-status response, unwrapping the `{ contentType; data }` union so an error result keeps the bare body union on `error`.
+ */
+export type DataOf<T> = T extends { contentType: string; data: infer TData } ? TData : T
+
+/**
+ * The success variant for a single status, flattened so the negotiated `contentType` sits next to `data` and `switch (result.contentType)` narrows it.
+ */
+export type SuccessVariant<TStatus, TEntry, TRequest, TResponse> = TEntry extends { contentType: string; data: unknown }
+  ? TEntry extends { contentType: infer TContentType; data: infer TData }
+    ? { status: ToStatusNumber<TStatus>; data: TData; error: undefined; contentType: TContentType; request: TRequest; response: TResponse }
+    : never
+  : { status: ToStatusNumber<TStatus>; data: TEntry; error: undefined; contentType: string | undefined; request: TRequest; response: TResponse }
+
+/**
+ * One result variant for a single documented status, keyed by the numeric `status` so a `switch (result.status)` narrows `data` or `error`.
  */
 export type ResultByStatus<TResponses, TStatus extends keyof TResponses, TRequest, TResponse> = TStatus extends SuccessStatusCode
-  ? { status: ToStatusNumber<TStatus>; data: TResponses[TStatus]; error: undefined; request: TRequest; response: TResponse }
-  : { status: ToStatusNumber<TStatus>; data: undefined; error: TResponses[TStatus]; request: TRequest; response: TResponse }
+  ? SuccessVariant<TStatus, TResponses[TStatus], TRequest, TResponse>
+  : {
+      status: ToStatusNumber<TStatus>
+      data: undefined
+      error: DataOf<TResponses[TStatus]>
+      contentType: string | undefined
+      request: TRequest
+      response: TResponse
+    }
 
 /**
  * The union of every documented status' result variant.
@@ -40,60 +60,72 @@ export type ResultUnion<TResponses, TRequest, TResponse> = {
 }[keyof TResponses]
 
 /**
- * The union of just the success (2xx) status variants. Selected by status code, not by `error`, so an
- * untyped (`any`) error payload can never widen a success result's `data`.
+ * The union of just the success (2xx) status variants, selected by status code so an untyped error payload can never widen `data`.
  */
 export type SuccessResultUnion<TResponses, TRequest, TResponse> = {
   [TStatus in Extract<keyof TResponses, SuccessStatusCode>]: ResultByStatus<TResponses, TStatus, TRequest, TResponse>
 }[Extract<keyof TResponses, SuccessStatusCode>]
 
 /**
- * The shape every generated function returns, discriminated by the top-level `status`. With
- * `throwOnError` (the default) a resolved call always means success, so the result is the union of the
- * 2xx variants and `error` is `undefined`; without it every documented status is a variant, so a
- * `switch (result.status)` (or narrowing on `error`) narrows `data` and `error` to that status's
- * payload. Operations with no typed responses fall back to a `status`/`request`/`response`-only result.
+ * The shape every generated function returns, discriminated by the top-level `status`, narrowing to the 2xx variants under `throwOnError` and to every documented status without it.
  */
 export type RequestResult<TResponses, ThrowOnError extends boolean = true, TRequest = AxiosRequestConfig, TResponse = AxiosResponse> = ThrowOnError extends true
   ? [SuccessResultUnion<TResponses, TRequest, TResponse>] extends [never]
-    ? { status: number; data: SuccessOf<TResponses>; error: undefined; request: TRequest; response: TResponse }
+    ? {
+        status: number
+        data: SuccessOf<TResponses>
+        error: undefined
+        contentType: string | undefined
+        request: TRequest
+        response: TResponse
+      }
     : SuccessResultUnion<TResponses, TRequest, TResponse>
   : [ResultUnion<TResponses, TRequest, TResponse>] extends [never]
-    ? { status: number; data: undefined; error: undefined; request: TRequest; response: TResponse }
+    ? { status: number; data: undefined; error: undefined; contentType: string | undefined; request: TRequest; response: TResponse }
     : ResultUnion<TResponses, TRequest, TResponse>
 
 /**
- * The data-shaped keys of the grouped options object. `Options` subtracts these from the runtime
- * `RequestConfig` and adds them back, typed per operation, from the generated `<Name>Request` type.
+ * The data-shaped keys of the grouped options object, which `Options` re-adds typed per operation.
  */
-export type DataShape = { body?: unknown; headers?: unknown; path?: unknown; query?: unknown }
+export type DataShape = { body?: unknown; cookies?: unknown; headers?: unknown; path?: unknown; query?: unknown }
 
-export type HeaderValue = string | number | boolean | null | undefined | object
-export type HeadersInit = Array<[string, HeaderValue]> | Record<string, HeaderValue>
 export type ResponseType = 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream' | 'formdata'
 
 /**
- * Serializes the query object into a search string. Array and object members follow the configured
- * style (`form` with `explode` by default; `deepObject` for nested objects).
+ * Turns a raw response body into a parsed value, registered per media type as a codec's `deserialize` to handle formats the runtime does not decode itself.
+ */
+export type Deserializer<T = unknown> = (raw: unknown, contentType: string) => T | Promise<T>
+
+/**
+ * Serializes a request body for a single media type, registered per content type as a codec's `serialize` to encode formats the default serializer does not handle.
  */
-export type QuerySerializer = (params: Record<string, unknown>) => string
+export type ContentBodySerializer = (body: unknown, contentType?: string) => unknown
 
 /**
- * Serializes the request body. JSON by default; `FormData`, `URLSearchParams`, `Blob`,
- * `ArrayBuffer`, and string bodies pass through untouched.
+ * A per-content-type codec registered on `codecs`, keyed by content type. `serialize` encodes the
+ * request body for that media type and `deserialize` decodes the response body. Either half is
+ * optional, so a codec can handle one direction.
  */
-export type BodySerializer = (body: unknown, contentType?: string) => unknown
+export type Codec = {
+  serialize?: ContentBodySerializer
+  deserialize?: Deserializer
+}
 
 /**
- * Parses a value before it is sent or after it is received, returning the parsed (and optionally
- * transformed) value. Wires zod parsing through the per-call `parser.request` / `parser.response` /
- * `parser.error` hooks (`error` runs on the error body when a non-2xx call does not throw).
+ * The per-call content type selection, where a bare string sets the request content type and the object form also sets the response format sent as `Accept`.
  */
-export type Parser<T = unknown> = (value: T) => T | Promise<T>
+export type ContentType = string | { request?: string; response?: string }
 
 /**
- * A resolved security scheme carried on each generated call's `security` array. The runtime passes it
- * to the configured `auth` resolver and places the returned token accordingly.
+ * A Standard Schema validator (zod, valibot, arktype) that parses a value before it is sent or after
+ * it is received. `runValidator` runs it through `validateStandardSchema`. Wired through the per-call
+ * `validator.request` / `validator.response` / `validator.error` hooks (`error` runs on the error body when a
+ * non-2xx call does not throw).
+ */
+export type Validator<T = unknown> = StandardSchemaValidator<T>
+
+/**
+ * A resolved security scheme carried on each generated call's `security` array and passed to the `auth` resolver.
  */
 export type Auth = {
   type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect'
@@ -103,21 +135,22 @@ export type Auth = {
 }
 
 /**
- * The token a consumer returns for a scheme, or `undefined` to skip it. Bearer and basic schemes are
- * prefixed by the runtime (basic is base64-encoded), so return the raw token or `user:password`.
+ * The raw token a consumer returns for a scheme (or `user:password` for basic), or `undefined` to skip it.
  */
 export type AuthToken = string | undefined
 
 /**
- * Resolves the token for a security scheme: either a static token used for every scheme, or a
- * callback called once per scheme on a guarded operation until one returns a token.
+ * Resolves the token for a security scheme, either a static token or a callback called per scheme until one returns a token.
  */
 export type AuthResolver = AuthToken | ((auth: Auth) => AuthToken | Promise<AuthToken>)
 
 /**
- * The request a generated function hands to the runtime. `body` / `headers` / `path` / `query` come
- * from the grouped options; everything else is plain request configuration. `transport` carries an
- * axios instance and `validateStatus` rides axios's own contract.
+ * Extra axios config the runtime spreads onto every request, an escape hatch for per-call fields it does not set itself such as `timeout`, `proxy`, and the progress callbacks.
+ */
+export type AxiosOptions = AxiosRequestConfig
+
+/**
+ * The request a generated function hands to the runtime, with `body` / `headers` / `path` / `query` from the grouped options.
  */
 export type RequestConfig<TBody = unknown, TRequest = AxiosRequestConfig, TResponse = AxiosResponse> = {
   baseURL?: string
@@ -126,18 +159,21 @@ export type RequestConfig<TBody = unknown, TRequest = AxiosRequestConfig, TRespo
   path?: Record<string, unknown>
   query?: unknown
   params?: unknown
+  cookies?: Record<string, unknown>
   body?: TBody
   headers?: HeadersInit
+  styles?: Styles
   signal?: AbortSignal
-  contentType?: string
+  options?: AxiosOptions
+  contentType?: ContentType
   responseType?: ResponseType
   throwOnError?: boolean
   validateStatus?: (status: number) => boolean
   client?: ClientInstance<TRequest, TResponse>
   transport?: AxiosInstance
-  querySerializer?: QuerySerializer
-  bodySerializer?: BodySerializer
-  parser?: { request?: Parser; response?: Parser; error?: Parser }
+  serializer?: Serializers
+  codecs?: Record<string, Codec>
+  validator?: { request?: Validator; response?: Validator; error?: Validator }
   security?: Array<Auth>
   auth?: AuthResolver
 }
@@ -156,17 +192,17 @@ export type Options<TData extends DataShape, ThrowOnError extends boolean = true
   }
 
 /**
- * Client-level configuration shared by every call an instance makes. Per-call `RequestConfig`
- * overrides these. `transport` is the axios instance the client sends through.
+ * Client-level configuration shared by every call an instance makes, overridden by the per-call `RequestConfig`.
  */
 export type ClientConfig = {
   baseURL?: string
   headers?: HeadersInit
+  options?: AxiosOptions
   throwOnError?: boolean
   validateStatus?: (status: number) => boolean
   transport?: AxiosInstance
-  querySerializer?: QuerySerializer
-  bodySerializer?: BodySerializer
+  serializer?: Serializers
+  codecs?: Record<string, Codec>
   auth?: AuthResolver
 }
 
@@ -177,18 +213,15 @@ export type CallResult<TRequest = AxiosRequestConfig, TResponse = AxiosResponse>
   status: number
   data: unknown
   error: unknown
+  contentType: string | undefined
   request: TRequest
   response: TResponse
 }
 
-/**
- * An interceptor function for a channel value.
- */
 export type InterceptorFn<T> = (value: T) => T | Promise<T>
 
 /**
- * A single interceptor channel (request, response, or error) exposing the `use` / `eject` / `update`
- * API shared with the fetch and ky runtimes, backed by axios's native interceptor managers.
+ * A single interceptor channel with a transport-agnostic `use` / `eject` / `update` API, backed by axios's native interceptor managers.
  */
 export type InterceptorChannel<T> = {
   use: (fn: InterceptorFn<T>) => number
@@ -197,9 +230,7 @@ export type InterceptorChannel<T> = {
 }
 
 /**
- * The three interceptor channels every client instance exposes, wrapping axios's native
- * `interceptors.request` / `interceptors.response`. The `error` channel maps onto the response
- * manager's rejection handler.
+ * The three interceptor channels every client instance exposes, wrapping axios's native managers with `error` mapped onto the response rejection handler.
  */
 export type Interceptors = {
   request: InterceptorChannel<InternalAxiosRequestConfig>
@@ -221,97 +252,132 @@ export type ClientInstance<TRequest = AxiosRequestConfig, TResponse = AxiosRespo
 }
 
 /**
- * Thrown for responses outside the 2xx range, so a resolved call always means success. The parsed
- * error body and the native request config / response stay reachable on the error.
+ * Thrown for a non-2xx response, so a resolved call always means success.
  */
-export class ResponseError<TError = unknown, TRequest = AxiosRequestConfig, TResponse = AxiosResponse> extends Error {
-  data: TError
-  status: number
-  statusText: string
-  request: TRequest
-  response: TResponse
+/**
+ * One decoded Server-Sent Event, with `data` parsed as JSON when valid and kept as the raw string otherwise.
+ */
+export type ServerSentEvent<TData = unknown> = {
+  data: TData
+  event?: string
+  id?: string
+  retry?: number
+}
 
-  constructor(config: { data: TError; status: number; statusText: string; request: TRequest; response: TResponse }) {
-    super(`Request failed with status ${config.status}${config.statusText ? ` ${config.statusText}` : ''}`)
-    this.name = 'ResponseError'
-    this.data = config.data
-    this.status = config.status
-    this.statusText = config.statusText
-    this.request = config.request
-    this.response = config.response
+async function* readBytes(stream: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array> {
+  if (!('getReader' in stream)) {
+    yield* stream
+    return
+  }
+
+  const reader = stream.getReader()
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) return
+      yield value
+    }
+  } finally {
+    await reader.cancel().catch(() => {})
   }
 }
 
-export type ResponseErrorConfig<TError = unknown> = ResponseError<TError>
+function parseEvent<TData>(raw: string): ServerSentEvent<TData> | undefined {
+  const data: Array<string> = []
+  const event: ServerSentEvent<TData> = { data: undefined as TData }
+  let seen = false
+
+  for (const line of raw.split('\n')) {
+    if (!line || line.startsWith(':')) continue
+    seen = true
+    const index = line.indexOf(':')
+    const field = index === -1 ? line : line.slice(0, index)
+    const value = index === -1 ? '' : line.slice(index + 1).replace(/^ /, '')
+    if (field === 'data') data.push(value)
+    else if (field === 'event') event.event = value
+    else if (field === 'id') event.id = value
+    else if (field === 'retry' && Number.isFinite(Number(value))) event.retry = Number(value)
+  }
 
-function isFormBody(body: unknown): boolean {
-  return (
-    body instanceof FormData ||
-    body instanceof URLSearchParams ||
-    body instanceof Blob ||
-    body instanceof ArrayBuffer ||
-    ArrayBuffer.isView(body) ||
-    typeof body === 'string'
-  )
-}
+  if (!seen) return undefined
 
-function appendFormDataValue(formData: FormData, key: string, value: unknown): void {
-  if (value === undefined || value === null) return
-  if (value instanceof Blob) formData.append(key, value)
-  else if (value instanceof Date) formData.append(key, value.toISOString())
-  else if (typeof value === 'object') formData.append(key, JSON.stringify(value))
-  else formData.append(key, String(value))
+  if (data.length) {
+    const joined = data.join('\n')
+    try {
+      event.data = JSON.parse(joined) as TData
+    } catch {
+      event.data = joined as TData
+    }
+  }
+  return event
 }
 
 /**
- * Default body serializer: passes binary/form bodies through and JSON-serializes everything else.
- * For `multipart/form-data` plain objects become `FormData` and for
- * `application/x-www-form-urlencoded` they become `URLSearchParams`.
+ * Parses a `text/event-stream` body into typed Server-Sent Events, consumed with `for await` and stopped early by breaking the loop.
  */
-export const defaultBodySerializer: BodySerializer = (body, contentType) => {
-  if (body === undefined || body === null) return undefined
-  if (isFormBody(body)) return body
-  if (contentType?.includes('multipart/form-data')) {
-    const formData = new FormData()
-    for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
-      if (Array.isArray(value)) for (const item of value) appendFormDataValue(formData, key, item)
-      else appendFormDataValue(formData, key, value)
+export async function* parseEventStream<TData = unknown>(
+  stream: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>,
+): AsyncGenerator<ServerSentEvent<TData>> {
+  const decoder = new TextDecoder()
+  const normalize = (text: string) => text.replace(/\r\n|\r/g, '\n')
+  let buffer = ''
+
+  for await (const chunk of readBytes(stream)) {
+    const blocks = normalize(buffer + decoder.decode(chunk, { stream: true })).split('\n\n')
+    buffer = blocks.pop() ?? ''
+    for (const block of blocks) {
+      const event = parseEvent<TData>(block)
+      if (event) yield event
     }
-    return formData
   }
-  if (contentType?.includes('application/x-www-form-urlencoded')) {
-    return new URLSearchParams(body as Record<string, string>)
-  }
-  return JSON.stringify(body)
+
+  const event = parseEvent<TData>(normalize(buffer + decoder.decode()))
+  if (event) yield event
 }
 
-function appendQueryValue(search: URLSearchParams, key: string, value: unknown): void {
-  if (value === undefined || value === null) return
-  if (Array.isArray(value)) {
-    for (const item of value) appendQueryValue(search, key, item)
-    return
-  }
-  if (typeof value === 'object') {
-    for (const [prop, propValue] of Object.entries(value as Record<string, unknown>)) {
-      appendQueryValue(search, `${key}[${prop}]`, propValue)
-    }
-    return
-  }
-  search.append(key, String(value))
+/**
+ * The resolved shape returned by a generated `text/event-stream` operation: the typed event
+ * `stream` plus the native `response`.
+ */
+export type EventStreamResult<TData = unknown, TResponse = AxiosResponse> = {
+  stream: AsyncGenerator<ServerSentEvent<TData>>
+  response: TResponse
 }
 
 /**
- * Default query serializer: arrays explode into repeated keys and nested objects use the
- * `deepObject` style (`key[prop]=value`).
+ * Wraps a transport result whose `data` is a streaming body into an `EventStreamResult`, exposing
+ * the parsed events as a typed async iterator. Generated SSE operations call this.
  */
-export const defaultQuerySerializer: QuerySerializer = (params) => {
-  const search = new URLSearchParams()
-  for (const [key, value] of Object.entries(params)) {
-    appendQueryValue(search, key, value)
+export async function toEventStream<TData = unknown>(result: Promise<{ data: unknown; response: AxiosResponse }>): Promise<EventStreamResult<TData>> {
+  const { data, response } = await result
+  return {
+    response,
+    stream: parseEventStream<TData>(data as ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>),
+  }
+}
+
+export class ResponseError<TError = unknown, TRequest = AxiosRequestConfig, TResponse = AxiosResponse> extends Error {
+  data: TError
+  status: number
+  statusText: string
+  contentType: string | undefined
+  request: TRequest
+  response: TResponse
+
+  constructor(config: { data: TError; status: number; statusText: string; contentType?: string; request: TRequest; response: TResponse }) {
+    super(`Request failed with status ${config.status}${config.statusText ? ` ${config.statusText}` : ''}`)
+    this.name = 'ResponseError'
+    this.data = config.data
+    this.status = config.status
+    this.statusText = config.statusText
+    this.contentType = config.contentType
+    this.request = config.request
+    this.response = config.response
   }
-  return search.toString()
 }
 
+export type ResponseErrorConfig<TError = unknown> = ResponseError<TError>
+
 function serializeHeaders(headers: HeadersInit | undefined): Record<string, string> {
   if (!headers) return {}
   const entries = Array.isArray(headers) ? headers : Object.entries(headers)
@@ -328,23 +394,30 @@ function mergeHeaders(...sources: Array<HeadersInit | undefined>): Record<string
 }
 
 /**
- * Joins the base and request URL parts, interpolates `{param}` segments from the path params
- * (URL-encoded), and appends the serialized query. Backs `getUrl` so a URL can be constructed
- * without sending the request.
+ * Joins the URL parts, interpolates URL-encoded `{param}` segments, and appends the serialized query, backing `getUrl`.
  */
-function serializeUrl(parts: Array<string | undefined>, pathParams: Record<string, unknown>, search: string): string {
+function serializeUrl({
+  parts,
+  pathParams,
+  search,
+  pathSerializer = defaultPathSerializer,
+  pathStyles,
+}: {
+  parts: Array<string | undefined>
+  pathParams: Record<string, unknown>
+  search: string
+  pathSerializer?: PathSerializer
+  pathStyles?: Record<string, PathParamStyle>
+}): string {
   const path = parts
     .filter(Boolean)
     .join('')
-    .replace(/\{([^{}]+)\}/g, (_, key: string) => encodeURIComponent(String(pathParams[key] ?? '')))
+    .replace(/\{([^{}]+)\}/g, (_, key: string) => pathSerializer({ name: key, value: pathParams[key], options: pathStyles?.[key] }))
   return path + (search ? `?${search}` : '')
 }
 
 /**
- * Walks the per-operation security in order and places the first resolved token on the request,
- * mutating `headers` / `query` in place. Bearer (and oauth2 / openIdConnect) tokens become a `Bearer`
- * Authorization header, basic credentials are base64-encoded, and an apiKey is placed under its
- * `name` in the header, query, or cookie.
+ * Walks the per-operation security in order and places the first resolved token on the request, mutating `headers` / `query` in place.
  */
 export async function resolveAuth(params: {
   security: Array<Auth> | undefined
@@ -371,15 +444,13 @@ export async function resolveAuth(params: {
   }
 }
 
-async function runParser<T>(parser: Parser | undefined, value: T): Promise<T> {
-  if (!parser) return value
-  return (await parser(value)) as T
+async function runValidator<T>(validator: Validator<T> | undefined, value: T): Promise<T> {
+  if (!validator) return value
+  return validateStandardSchema(validator, value)
 }
 
 /**
- * Wraps an axios interceptor registration behind the shared `use` / `eject` / `update` API. A stable
- * external id is mapped onto axios's own id so `update` can swap a handler in place even though axios
- * has no native update.
+ * Wraps an axios interceptor registration behind the shared `use` / `eject` / `update` API, mapping a stable external id onto axios's own so `update` can swap a handler in place.
  */
 function createInterceptorChannel<T>(register: (fn: InterceptorFn<T>) => number, ejectNative: (id: number) => void): InterceptorChannel<T> {
   const ids = new Map<number, number>()
@@ -405,13 +476,32 @@ function createInterceptorChannel<T>(register: (fn: InterceptorFn<T>) => number,
 }
 
 /**
- * Builds the shared client core bound to an axios instance (defaulting to `axios.create()`). The
- * interceptor channels delegate to the instance's native managers, and `querySerializer` /
- * `bodySerializer` map onto `paramsSerializer` / `transformRequest`.
- *
- * `throwOnError` rides `validateStatus`. With it on, axios rejects a non-2xx status and the runtime
- * normalizes the error to `ResponseError`. With it off, an internal `validateStatus: () => true`
- * resolves every status into `{ data, error, request, response }`.
+ * The base media type of a `Content-Type` value, lowercased and stripped of any `; charset=...` parameters.
+ */
+function baseContentType(value: string | null | undefined): string | undefined {
+  if (!value) return undefined
+  return value.split(';')[0]!.trim().toLowerCase() || undefined
+}
+
+/**
+ * Reads the negotiated response content type from the response headers as a base media type.
+ */
+function getResponseContentType(headers: Record<string, unknown> | undefined): string | undefined {
+  if (!headers) return undefined
+  const value = headers['content-type'] ?? headers['Content-Type']
+  return baseContentType(typeof value === 'string' ? value : undefined)
+}
+
+/**
+ * Normalizes the `contentType` option to its `{ request, response }` form, treating a bare string as the request content type.
+ */
+function resolveContentType(contentType: ContentType | undefined): { request?: string; response?: string } {
+  if (typeof contentType === 'string') return { request: contentType }
+  return contentType ?? {}
+}
+
+/**
+ * Builds the shared client core bound to an axios instance (defaulting to `axios.create()`), with `throwOnError` riding axios's `validateStatus`.
  */
 export function createClientCore<TRequest = AxiosRequestConfig, TResponse = AxiosResponse>(options: ClientConfig = {}): ClientInstance<TRequest, TResponse> {
   let config: ClientConfig = { ...options }
@@ -440,11 +530,17 @@ export function createClientCore<TRequest = AxiosRequestConfig, TResponse = Axio
 
   const client = (async <TBody = unknown>(requestConfig: RequestConfig<TBody, TRequest, TResponse>): Promise<CallResult<TRequest, TResponse>> => {
     const activeInstance = requestConfig.transport ?? config.transport ?? instance
-    const querySerializer = requestConfig.querySerializer ?? config.querySerializer ?? defaultQuerySerializer
-    const bodySerializer = requestConfig.bodySerializer ?? config.bodySerializer ?? defaultBodySerializer
-
-    const headers = mergeHeaders(config.headers, requestConfig.headers)
-    const requestContentType = requestConfig.contentType ?? headers['Content-Type'] ?? headers['content-type']
+    const querySerializer = requestConfig.serializer?.query ?? config.serializer?.query ?? defaultQuerySerializer
+    const bodySerializer = requestConfig.serializer?.body ?? config.serializer?.body ?? defaultBodySerializer
+    const pathSerializer = requestConfig.serializer?.path ?? config.serializer?.path ?? defaultPathSerializer
+    const codecs = { ...config.codecs, ...requestConfig.codecs }
+
+    const headers = mergeHeaders(config.headers, applyHeaderStyles(requestConfig.headers, requestConfig.styles?.header))
+    const { request: requestContentTypeOption, response: responseContentType } = resolveContentType(requestConfig.contentType)
+    const requestContentType = requestContentTypeOption ?? headers['Content-Type'] ?? headers['content-type']
+    if (responseContentType && headers['Accept'] === undefined && headers['accept'] === undefined) {
+      headers['Accept'] = responseContentType
+    }
 
     const query: Record<string, unknown> = { ...((requestConfig.query ?? requestConfig.params) as Record<string, unknown> | undefined) }
 
@@ -455,29 +551,43 @@ export function createClientCore<TRequest = AxiosRequestConfig, TResponse = Axio
       query,
     })
 
-    const validatedBody = await runParser(requestConfig.parser?.request, requestConfig.body)
-    const body = bodySerializer(validatedBody, requestContentType)
+    if (requestConfig.cookies) {
+      const cookie = serializeCookies(requestConfig.cookies, requestConfig.styles?.cookie)
+      if (cookie) headers.Cookie = [headers.Cookie, cookie].filter(Boolean).join('; ')
+    }
+
+    const validatedBody = await runValidator(requestConfig.validator?.request, requestConfig.body)
+    const requestContentTypeBase = baseContentType(requestContentType)
+    const contentCodec = requestContentTypeBase ? codecs[requestContentTypeBase] : undefined
+    const body = contentCodec?.serialize
+      ? contentCodec.serialize(validatedBody, requestContentType)
+      : bodySerializer({ body: validatedBody, contentType: requestContentType, encoding: requestConfig.styles?.body })
     // A FormData body must keep its Content-Type unset so axios appends the multipart boundary.
     if (body instanceof FormData) {
       delete headers['Content-Type']
       delete headers['content-type']
-    } else if (requestConfig.contentType) {
-      headers['Content-Type'] = requestConfig.contentType
+    } else if (requestContentTypeOption) {
+      headers['Content-Type'] = requestContentTypeOption
     }
     const pathParams = requestConfig.path ?? {}
-    const url = (requestConfig.url ?? '').replace(/\{([^{}]+)\}/g, (_, key: string) => encodeURIComponent(String(pathParams[key] ?? '')))
+    const url = (requestConfig.url ?? '').replace(/\{([^{}]+)\}/g, (_, key: string) =>
+      pathSerializer({ name: key, value: pathParams[key], options: requestConfig.styles?.path?.[key] }),
+    )
     const baseURL = [config.baseURL, requestConfig.baseURL].filter(Boolean).join('') || undefined
 
     const throwOnError = requestConfig.throwOnError ?? config.throwOnError ?? true
     const validateStatus = requestConfig.validateStatus ?? config.validateStatus ?? (throwOnError ? undefined : () => true)
 
+    const options = config.options || requestConfig.options ? { ...config.options, ...requestConfig.options } : undefined
+
     const axiosConfig: AxiosRequestConfig = {
+      ...options, // timeout, proxy, maxRedirects, decompress, onUploadProgress, …
       url,
       baseURL,
       method: requestConfig.method ?? 'GET',
       headers,
       params: query,
-      paramsSerializer: (params) => querySerializer(params as Record<string, unknown>),
+      paramsSerializer: (params) => querySerializer(params as Record<string, unknown>, requestConfig.styles?.query),
       data: body,
       transformRequest: (data) => data,
       signal: requestConfig.signal,
@@ -485,15 +595,28 @@ export function createClientCore<TRequest = AxiosRequestConfig, TResponse = Axio
       validateStatus,
     }
 
+    // Only the fetch adapter exposes a streaming `response.data` (a ReadableStream) in the browser;
+    // the default XHR adapter buffers the whole body. Default streams to it, but respect an explicit adapter.
+    if (requestConfig.responseType === 'stream' && !axiosConfig.adapter) {
+      axiosConfig.adapter = 'fetch'
+    }
+
     try {
       const response = await activeInstance.request<unknown, AxiosResponse>(axiosConfig)
       const isSuccess = response.status >= 200 && response.status < 300
-      const data = isSuccess ? await runParser(requestConfig.parser?.response, response.data) : undefined
-      const error = isSuccess ? undefined : await runParser(requestConfig.parser?.error, response.data)
+      const contentType = getResponseContentType(response.headers as Record<string, unknown>)
+      let decoded: unknown = response.data
+      if (contentType) {
+        const codec = codecs[contentType]
+        if (codec?.deserialize) decoded = await codec.deserialize(response.data, contentType)
+      }
+      const data = isSuccess ? await runValidator(requestConfig.validator?.response, decoded) : undefined
+      const error = isSuccess ? undefined : await runValidator(requestConfig.validator?.error, decoded)
       return {
         status: response.status,
         data,
         error,
+        contentType,
         request: response.config as TRequest,
         response: response as TResponse,
       }
@@ -504,6 +627,7 @@ export function createClientCore<TRequest = AxiosRequestConfig, TResponse = Axio
           data: axiosError.response.data,
           status: axiosError.response.status,
           statusText: axiosError.response.statusText,
+          contentType: getResponseContentType(axiosError.response.headers as Record<string, unknown>),
           request: axiosError.config as TRequest,
           response: axiosError.response as TResponse,
         })
@@ -518,9 +642,16 @@ export function createClientCore<TRequest = AxiosRequestConfig, TResponse = Axio
     return config
   }
   client.getUrl = (requestConfig) => {
-    const querySerializer = requestConfig.querySerializer ?? config.querySerializer ?? defaultQuerySerializer
+    const querySerializer = requestConfig.serializer?.query ?? config.serializer?.query ?? defaultQuerySerializer
+    const pathSerializer = requestConfig.serializer?.path ?? config.serializer?.path ?? defaultPathSerializer
     const query: Record<string, unknown> = { ...((requestConfig.query ?? requestConfig.params) as Record<string, unknown> | undefined) }
-    return serializeUrl([config.baseURL, requestConfig.baseURL, requestConfig.url], requestConfig.path ?? {}, querySerializer(query))
+    return serializeUrl({
+      parts: [config.baseURL, requestConfig.baseURL, requestConfig.url],
+      pathParams: requestConfig.path ?? {},
+      search: querySerializer(query, requestConfig.styles?.query),
+      pathSerializer,
+      pathStyles: requestConfig.styles?.path,
+    })
   }
   client.interceptors = interceptors
   client.createClient = (next) => createClientCore<TRequest, TResponse>({ ...config, ...next })