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

package/templates/fetch.ts

@@ -1,33 +1,54 @@
+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.
@@ -37,61 +58,73 @@ 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 = Request, TResponse = Response> = 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 RequestCredentials = 'omit' | 'same-origin' | 'include'
 export type ResponseType = 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream'
 
 /**
- * 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 ContentBodySerializer = (body: unknown, contentType?: string) => BodyInit | undefined
+
+/**
+ * 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 QuerySerializer = (params: Record<string, unknown>) => string
+export type Codec = {
+  serialize?: ContentBodySerializer
+  deserialize?: Deserializer
+}
 
 /**
- * Serializes the request body. JSON by default; `FormData`, `URLSearchParams`, `Blob`,
- * `ArrayBuffer`, and string bodies pass through untouched.
+ * 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 BodySerializer = (body: unknown, contentType?: string) => BodyInit | undefined
+export type ContentType = string | { request?: string; response?: string }
 
 /**
- * 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).
+ * 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 Parser<T = unknown> = (value: T) => T | Promise<T>
+export type Validator<T = unknown> = StandardSchemaValidator<T>
 
 /**
- * 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 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'
@@ -101,20 +134,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.
+ * Extra `fetch` init the transport spreads onto every `Request`, an escape hatch for fields the runtime does not set itself such as `cache`, `redirect`, and Next.js's `next`.
+ */
+export type FetchOptions = RequestInit & { next?: Record<string, unknown> }
+
+/**
+ * The request a generated function hands to the runtime, with `body` / `headers` / `path` / `query` from the grouped options.
  */
 export type RequestConfig<TBody = unknown, TRequest = Request, TResponse = Response> = {
   baseURL?: string
@@ -123,18 +158,21 @@ export type RequestConfig<TBody = unknown, TRequest = Request, TResponse = Respo
   path?: Record<string, unknown>
   query?: unknown
   params?: unknown
+  cookies?: Record<string, unknown>
   body?: TBody
   headers?: HeadersInit
+  styles?: Styles
   signal?: AbortSignal
   credentials?: RequestCredentials
-  contentType?: string
+  options?: FetchOptions
+  contentType?: ContentType
   responseType?: ResponseType
   throwOnError?: boolean
   client?: ClientInstance<TRequest, TResponse>
   transport?: Transport<TRequest, TResponse>
-  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
 }
@@ -153,23 +191,22 @@ 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.
+ * Client-level configuration shared by every call an instance makes, overridden by the per-call `RequestConfig`.
  */
 export type ClientConfig<TRequest = Request, TResponse = Response> = {
   baseURL?: string
   headers?: HeadersInit
   credentials?: RequestCredentials
+  options?: FetchOptions
   throwOnError?: boolean
   transport?: Transport<TRequest, TResponse>
-  querySerializer?: QuerySerializer
-  bodySerializer?: BodySerializer
+  serializer?: Serializers
+  codecs?: Record<string, Codec>
   auth?: AuthResolver
 }
 
 /**
- * The normalized request the transport receives. The shared core does all serialization, auth, and
- * header work; the transport only performs the send.
+ * The normalized request the transport receives, with all serialization, auth, and header work already done.
  */
 export type ResolvedRequest = {
   url: string
@@ -178,25 +215,25 @@ export type ResolvedRequest = {
   body?: BodyInit
   signal?: AbortSignal
   credentials?: RequestCredentials
+  options?: FetchOptions
   responseType?: ResponseType
 }
 
 /**
- * What a transport returns: the parsed body plus the native request/response objects, kept reachable
- * so status, headers, and the raw body never have to grow the result type.
+ * What a transport returns: the parsed body plus the native request and response objects.
  */
 export type TransportResult<TData = unknown, TRequest = Request, TResponse = Response> = {
   data: TData
   status: number
   statusText: string
   headers: Headers
+  contentType?: string
   request: TRequest
   response: TResponse
 }
 
 /**
- * The per-plugin send. plugin-fetch wraps `globalThis.fetch`, plugin-axios an axios instance, and
- * plugin-ky a ky instance. Supplied to `createClientCore` as `defaultTransport`.
+ * The per-plugin send, supplied to `createClientCore` as `defaultTransport`.
  */
 export type Transport<TRequest = Request, TResponse = Response> = (request: ResolvedRequest) => Promise<TransportResult<unknown, TRequest, TResponse>>
 
@@ -207,18 +244,15 @@ export type CallResult<TRequest = Request, TResponse = Response> = {
   status: number
   data: unknown
   error: unknown
+  contentType: string | undefined
   request: TRequest
   response: TResponse
 }
 
-/**
- * A registered interceptor with its ejection id.
- */
 export type InterceptorFn<T> = (value: T) => T | Promise<T>
 
 /**
- * A single interceptor channel — request, response, or error — with a transport-agnostic
- * `use` / `eject` / `update` API.
+ * A single interceptor channel with a transport-agnostic `use` / `eject` / `update` API.
  */
 export type InterceptorStack<T> = {
   use: (fn: InterceptorFn<T>) => number
@@ -250,22 +284,23 @@ export type ClientInstance<TRequest = Request, TResponse = Response> = {
 }
 
 /**
- * Thrown for responses outside the 2xx range, so a resolved call always means success. The parsed
- * error body and the native request/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 = Request, TResponse = Response> extends Error {
   data: TError
   status: number
   statusText: string
+  contentType: string | undefined
   request: TRequest
   response: TResponse
 
-  constructor(config: { data: TError; status: number; statusText: string; 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
   }
@@ -273,74 +308,6 @@ export class ResponseError<TError = unknown, TRequest = Request, TResponse = Res
 
 export type ResponseErrorConfig<TError = unknown> = ResponseError<TError>
 
-function isFormBody(body: unknown): body is BodyInit {
-  return (
-    body instanceof FormData ||
-    body instanceof URLSearchParams ||
-    body instanceof Blob ||
-    body instanceof ArrayBuffer ||
-    ArrayBuffer.isView(body) ||
-    typeof body === 'string'
-  )
-}
-
-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))
-}
-
-/**
- * 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`.
- */
-export const defaultBodySerializer: BodySerializer = (body, contentType) => {
-  if (body === undefined || body === null) return undefined
-  if (isFormBody(body)) return body as BodyInit
-  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)
-    }
-    return formData
-  }
-  if (contentType?.includes('application/x-www-form-urlencoded')) {
-    return new URLSearchParams(body as Record<string, string>)
-  }
-  return JSON.stringify(body)
-}
-
-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))
-}
-
-/**
- * Default query serializer: arrays explode into repeated keys and nested objects use the
- * `deepObject` style (`key[prop]=value`).
- */
-export const defaultQuerySerializer: QuerySerializer = (params) => {
-  const search = new URLSearchParams()
-  for (const [key, value] of Object.entries(params)) {
-    appendQueryValue(search, key, value)
-  }
-  return search.toString()
-}
-
 function serializeHeaders(headers: HeadersInit | undefined): Record<string, string> {
   if (!headers) return {}
   const entries = Array.isArray(headers) ? headers : Object.entries(headers)
@@ -357,21 +324,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. Shared by the send path and `getUrl` so both
- * produce an identical URL.
- */
-function serializeUrl(parts: Array<string | undefined>, pathParams: Record<string, unknown>, search: string): string {
+ * Joins the URL parts, interpolates URL-encoded `{param}` segments, and appends the serialized query, shared by the send path and `getUrl`.
+ */
+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}` : '')
 }
 
 /**
- * Creates a transport-agnostic interceptor channel. Interceptors run in registration order; `eject`
- * removes one by id and `update` swaps its function in place without reordering.
+ * Creates a transport-agnostic interceptor channel that runs interceptors in registration order.
  */
 export function createInterceptorStack<T>(): InterceptorStack<T> {
   let entries: Array<{ id: number; fn: InterceptorFn<T> }> = []
@@ -400,10 +376,7 @@ export function createInterceptorStack<T>(): InterceptorStack<T> {
 }
 
 /**
- * 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
@@ -430,14 +403,38 @@ 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)
+}
+
+/**
+ * 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: Headers | Record<string, string> | undefined): string | undefined {
+  if (!headers) return undefined
+  const value = headers instanceof Headers ? headers.get('Content-Type') : (headers['Content-Type'] ?? headers['content-type'])
+  return baseContentType(value)
 }
 
 /**
- * Builds the shared client core bound to a transport. Each plugin calls this with its
- * `defaultTransport` and exports the resulting instance as `client`, plus a `createClient` factory.
+ * 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 a transport, exported by each plugin as `client` plus a `createClient` factory.
  */
 export function createClientCore<TRequest = Request, TResponse = Response>(
   options: { defaultTransport: Transport<TRequest, TResponse> } & ClientConfig<TRequest, TResponse>,
@@ -453,11 +450,17 @@ export function createClientCore<TRequest = Request, TResponse = Response>(
 
   const client = (async <TBody = unknown>(requestConfig: RequestConfig<TBody, TRequest, TResponse>): Promise<CallResult<TRequest, TResponse>> => {
     const transport = requestConfig.transport ?? config.transport ?? defaultTransport
-    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) }
 
@@ -468,17 +471,34 @@ export function createClientCore<TRequest = Request, TResponse = Response>(
       query,
     })
 
+    if (requestConfig.cookies) {
+      const cookie = serializeCookies(requestConfig.cookies, requestConfig.styles?.cookie)
+      if (cookie) headers.Cookie = [headers.Cookie, cookie].filter(Boolean).join('; ')
+    }
+
     const rawBody = requestConfig.body
-    const validatedBody = await runParser(requestConfig.parser?.request, rawBody)
-    const body = bodySerializer(validatedBody, requestContentType)
+    const validatedBody = await runValidator(requestConfig.validator?.request, rawBody)
+    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 the runtime 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 url = serializeUrl([config.baseURL, requestConfig.baseURL, requestConfig.url], requestConfig.path ?? {}, querySerializer(query))
+    const url = serializeUrl({
+      parts: [config.baseURL, requestConfig.baseURL, requestConfig.url],
+      pathParams: requestConfig.path ?? {},
+      search: querySerializer(query, requestConfig.styles?.query),
+      pathSerializer,
+      pathStyles: requestConfig.styles?.path,
+    })
+
+    const options = config.options || requestConfig.options ? { ...config.options, ...requestConfig.options } : undefined
 
     let resolvedRequest: ResolvedRequest = {
       url,
@@ -487,6 +507,7 @@ export function createClientCore<TRequest = Request, TResponse = Response>(
       body,
       signal: requestConfig.signal,
       credentials: requestConfig.credentials,
+      options,
       responseType: requestConfig.responseType,
     }
     resolvedRequest = await interceptors.request.run(resolvedRequest)
@@ -497,11 +518,21 @@ export function createClientCore<TRequest = Request, TResponse = Response>(
     const isSuccess = result.status >= 200 && result.status < 300
     const throwOnError = requestConfig.throwOnError ?? config.throwOnError ?? true
 
+    const contentType = result.contentType ?? getResponseContentType(result.headers)
+    let decoded = result.data
+    if (contentType) {
+      const codec = codecs[contentType]
+      if (codec?.deserialize) decoded = await codec.deserialize(result.data, contentType)
+    }
+
+    const parsedErrorData = !isSuccess ? await runValidator(requestConfig.validator?.error, decoded) : undefined
+
     if (!isSuccess && throwOnError) {
       const error = new ResponseError({
-        data: result.data,
+        data: parsedErrorData,
         status: result.status,
         statusText: result.statusText,
+        contentType,
         request: result.request,
         response: result.response,
       })
@@ -509,13 +540,14 @@ export function createClientCore<TRequest = Request, TResponse = Response>(
       throw error
     }
 
-    const data = isSuccess ? await runParser(requestConfig.parser?.response, result.data) : undefined
-    const error = isSuccess ? undefined : await runParser(requestConfig.parser?.error, result.data)
+    const data = isSuccess ? await runValidator(requestConfig.validator?.response, decoded) : undefined
+    const error = isSuccess ? undefined : parsedErrorData
 
     return {
       status: result.status,
       data,
       error,
+      contentType,
       request: result.request,
       response: result.response,
     }
@@ -527,9 +559,16 @@ export function createClientCore<TRequest = Request, TResponse = Response>(
     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({ defaultTransport, ...config, ...next })
@@ -542,6 +581,7 @@ export function createClientCore<TRequest = Request, TResponse = Response>(
  */
 function detectResponseType(contentType: string | null): ResponseType | undefined {
   if (!contentType) return undefined
+  if (contentType.includes('text/event-stream')) return 'stream'
   if (contentType.includes('application/json') || contentType.includes('text/json')) return 'json'
   if (contentType.includes('text/')) return 'text'
   if (contentType.includes('image/') || contentType.includes('application/octet-stream')) return 'blob'
@@ -549,9 +589,7 @@ function detectResponseType(contentType: string | null): ResponseType | undefine
 }
 
 /**
- * Parses a `fetch` response body. Empty responses (204/205/304 or no body) resolve to `undefined`.
- * An explicit `responseType`, or one detected from the `Content-Type` header, forces the matching
- * `Response` method; otherwise the body is read as text and `JSON.parse`d, falling back to raw text.
+ * Parses a `fetch` response body using the `responseType` (explicit or detected from the `Content-Type`), falling back to JSON-then-text.
  */
 async function parseResponse(response: Response, responseType?: ResponseType): Promise<unknown> {
   if (response.status === 204 || response.status === 205 || response.status === 304 || !response.body) {
@@ -585,11 +623,113 @@ async function parseResponse(response: Response, responseType?: ResponseType): P
 }
 
 /**
- * The default transport: builds a native `Request` from the resolved request, sends it through
- * `globalThis.fetch`, and returns the parsed body alongside the native request/response objects.
+ * 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
+}
+
+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(() => {})
+  }
+}
+
+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)
+  }
+
+  if (!seen) return undefined
+
+  if (data.length) {
+    const joined = data.join('\n')
+    try {
+      event.data = JSON.parse(joined) as TData
+    } catch {
+      event.data = joined as TData
+    }
+  }
+  return event
+}
+
+/**
+ * Parses a `text/event-stream` body into typed Server-Sent Events, consumed with `for await` and stopped early by breaking the loop.
+ */
+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
+    }
+  }
+
+  const event = parseEvent<TData>(normalize(buffer + decoder.decode()))
+  if (event) yield event
+}
+
+/**
+ * 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 = Response> = {
+  stream: AsyncGenerator<ServerSentEvent<TData>>
+  response: TResponse
+}
+
+/**
+ * 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 async function toEventStream<TData = unknown>(result: Promise<{ data: unknown; response: Response }>): Promise<EventStreamResult<TData>> {
+  const { data, response } = await result
+  return {
+    response,
+    stream: parseEventStream<TData>(data as ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>),
+  }
+}
+
+/**
+ * The default transport that sends the resolved request through `globalThis.fetch` and returns the parsed body with the native request and response.
  */
 const defaultTransport: Transport = async (request: ResolvedRequest): Promise<TransportResult> => {
   const init: RequestInit = {
+    ...request.options, // cache, mode, redirect, keepalive, duplex, next, …
     method: request.method,
     headers: request.headers,
     body: request.body,
@@ -606,6 +746,7 @@ const defaultTransport: Transport = async (request: ResolvedRequest): Promise<Tr
     status: response.status,
     statusText: response.statusText,
     headers: response.headers,
+    contentType: getResponseContentType(response.headers),
     request: nativeRequest,
     response,
   }