@kubb/plugin-fetch 5.9.0-canary.20261024T172532 → 5.9.0

package/dist/templates/fetch.d.ts

@@ -162,16 +162,19 @@ export type ContentType = string | {
  * 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).
+ * non-2xx call does not throw), and `validator.path` / `validator.query` / `validator.headers` for the
+ * request params.
  */
 export type Validator<T = unknown> = StandardSchemaValidator<T>;
 /**
- * The failing body and the call it came from, handed to `onValidationError` alongside the `ParseError`.
- * `direction` says which slot rejected it: the request body, the success body, or the error body.
+ * The failing value and the call it came from, handed to `onValidationError` alongside the `ParseError`.
+ * `direction` says which side rejected it: the request, the success body, or the error body. `source`
+ * says which part of it: the body, or one of the request param groups.
  */
 export type ValidationErrorContext = {
   value: unknown;
   direction: 'request' | 'response' | 'error';
+  source: 'body' | 'path' | 'query' | 'headers';
   method?: string;
   url?: string;
   status?: number;
@@ -194,6 +197,7 @@ export type Auth = {
   scheme?: 'bearer' | 'basic';
   name?: string;
   in?: 'header' | 'query' | 'cookie';
+  scopes?: Array<string>;
 };
 /**
  * The raw token a consumer returns for a scheme (or `user:password` for basic), or `undefined` to skip it.
@@ -235,6 +239,9 @@ export type RequestConfig<TBody = unknown, TRequest = Request, TResponse = Respo
   codecs?: Record<string, Codec>;
   validator?: {
     request?: Validator;
+    path?: Validator;
+    query?: Validator;
+    headers?: Validator;
     response?: Validator;
     error?: Validator;
   };
@@ -323,6 +330,7 @@ export type Interceptors<TRequest = Request, TResponse = Response> = {
   response: InterceptorStack<TransportResult<unknown, TRequest, TResponse>, RequestConfig<unknown, TRequest, TResponse>>;
   error: InterceptorStack<ResponseError<unknown, TRequest, TResponse>, RequestConfig<unknown, TRequest, TResponse>>;
 };
+export type UrlConfig = Pick<RequestConfig, 'baseURL' | 'url' | 'path' | 'query' | 'params' | 'serializer' | 'styles'>;
 /**
  * A client instance: the callable send plus configuration, interceptors, and an isolated
  * `createClient` factory bound to the same transport.
@@ -331,7 +339,7 @@ export type ClientInstance<TRequest = Request, TResponse = Response> = {
   <TBody = unknown>(config: RequestConfig<TBody, TRequest, TResponse>): Promise<CallResult<TRequest, TResponse>>;
   getConfig: () => ClientConfig<TRequest, TResponse>;
   setConfig: (config: ClientConfig<TRequest, TResponse>) => ClientConfig<TRequest, TResponse>;
-  getUrl: <TBody = unknown>(config: RequestConfig<TBody, TRequest, TResponse>) => string;
+  getUrl: (config: UrlConfig) => string;
   interceptors: Interceptors<TRequest, TResponse>;
   createClient: (config?: ClientConfig<TRequest, TResponse>) => ClientInstance<TRequest, TResponse>;
 };

package/dist/templates/standardSchema.d.ts

@@ -48,4 +48,18 @@ export declare class ParseError extends Error {
  * const pet = await validateStandardSchema(PetSchema, rawData)
  */
 export declare function validateStandardSchema<TOutput>(schema: StandardSchemaValidator<TOutput>, value: unknown): Promise<TOutput>;
+/**
+ * Wraps an object schema so its keys match case-insensitively.
+ * Keys the schema does not declare pass through untouched.
+ * The declared keys are validated with `schema` under their declared names.
+ * Every key, and every issue path, keeps the casing the caller used.
+ *
+ * @param schema Standard Schema-compatible object schema.
+ * @param entries The record of keys the passed object schema validates.
+ * @example
+ * ```ts
+ * validator: { headers: toHeadersStandardSchema(putEventHeadersSchema, putEventHeadersSchema.shape) }
+ * ```
+ */
+export declare function toHeadersStandardSchema(schema: StandardSchemaValidator, entries: Record<string, unknown>): StandardSchemaValidator;
 //#endregion

package/docs/options.md

@@ -10,7 +10,7 @@ Pass these options to `pluginFetch()`. Shared options link to [Shared plugin opt
 | [`group`](https://kubb.dev/docs/5.x/reference/plugin-options#group)       | Split output by tag or path: `type`, `name`.                           | None                                             |
 | [`baseURL`](#baseurl)                                                     | Base URL prepended to every request.                                   | None                                             |
 | [`throwOnErrorDefault`](#throwonerrordefault)                             | Default error behavior and return type for generated operations.       | `true`                                           |
-| [`validator`](#validator)                                                 | Validate request and response bodies with Zod.                         | `false`                                          |
+| [`validator`](#validator)                                                 | Validate request bodies, params, and responses with Zod.               | `false`                                          |
 | [`sdk`](#sdk)                                                             | Generate a class-based SDK instead of functions.                       | None                                             |
 | [`returnType`](#returntype)                                               | Shape of the value a generated call resolves to.                       | `'full'`                                         |
 | [`include`](https://kubb.dev/docs/5.x/reference/plugin-options#include)   | Keep only operations that match.                                       | None                                             |
@@ -48,13 +48,13 @@ if (result.status !== 200) console.error(result.status, result.error)
 
 ### validator
 
-Validates request and response bodies with schemas from `@kubb/plugin-zod`, so add `pluginZod()` too. An invalid body makes the generated function throw a `ParseError`.
+Validates request bodies, path, query, and header params, and response bodies with schemas from `@kubb/plugin-zod`, so add `pluginZod()` too. An invalid value makes the generated function throw a `ParseError`.
 
-|          |                                                           |
-| -------- | --------------------------------------------------------- |
-| Type     | `false \| 'zod' \| { request?: 'zod'; response?: 'zod' }` |
-| Required | `false`                                                   |
-| Default  | `false`                                                   |
+|          |                                                                           |
+| -------- | ------------------------------------------------------------------------- |
+| Type     | `false \| 'zod' \| { request?: 'zod'; params?: 'zod'; response?: 'zod' }` |
+| Required | `false`                                                                   |
+| Default  | `false`                                                                   |
 
 ::field-group
 
@@ -66,8 +66,8 @@ Default value. Does no validation and returns the response cast to the generated
 Validates the success response body, and the error body when a non-2xx call does not throw.
 :::
 
-:::field{name="{ request?: 'zod', response?: 'zod' }"}
-Opts in per direction. `request` validates the request body before the call, and `response` validates the response body after it.
+:::field{name="{ request?: 'zod', params?: 'zod', response?: 'zod' }"}
+Opts in per direction. `request` validates the request body and `params` validates the path, query, and header params before the call. `response` validates the response body after it.
 :::
 
 ::
@@ -84,11 +84,17 @@ export default defineConfig({
   plugins: [
     pluginTs(),
     pluginZod(),
-    pluginFetch({ validator: { request: 'zod', response: 'zod' } }),
+    pluginFetch({ validator: { request: 'zod', params: 'zod', response: 'zod' } }),
   ],
 })
 ```
 
+`params` runs each group through its generated `<operation>PathSchema`, `QuerySchema`, or `HeadersSchema`, and sends what the schema returns. A codec param such as a `Date` goes out in its wire form, and an invalid param fails before the request. Values added by `auth` are not validated.
+
+Only the params your OpenAPI spec declares are sent. Path and query keys the spec does not declare are stripped, so a key such as an undocumented filter or a cache-buster never reaches the URL. Declare it in the spec, or leave `params` off. Headers are the exception: client-level `headers` (such as `Authorization` or tracing headers) are merged with the call's headers before validation, so headers the spec does not declare pass through unchanged, and declared header params match in any casing.
+
+Pair `request` and `params` with `pluginZod({ inferred: 'direction' })` when the schemas use codecs, so the request types accept the domain values (such as a `Date`) that the validators encode. See [`inferred`](https://kubb.dev/extensions/kubb-labs/plugin-zod/options#inferred).
+
 ### sdk
 
 Generates a class-based SDK. Each instance takes its own client config, so environments can use separate clients. Leave `sdk` unset to keep the standalone functions that query plugins call.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-fetch",
-  "version": "5.9.0-canary.20261024T172532",
+  "version": "5.9.0",
   "description": "Generate a slim, type-safe HTTP client with Kubb based on the native Fetch api.",
   "keywords": [
     "api-client",
@@ -80,12 +80,12 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/plugin-ts": "^5.2.0-canary.20261024T172532",
-    "@kubb/plugin-zod": "^5.7.0-canary.20261024T172532"
+    "@kubb/plugin-ts": "^5.1.0",
+    "@kubb/plugin-zod": "^5.7.0"
   },
   "devDependencies": {
-    "@internals/client": "0.1.0-canary.20261024T172532",
-    "@internals/shared": "0.1.0-canary.20261024T172532",
+    "@internals/client": "0.0.0",
+    "@internals/shared": "0.0.0",
     "kubb": "^5.13.0",
     "typescript": "^7.0.2"
   },

package/templates/fetch.ts

@@ -161,17 +161,20 @@ export type ContentType = string | { request?: string; response?: string }
  * 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).
+ * non-2xx call does not throw), and `validator.path` / `validator.query` / `validator.headers` for the
+ * request params.
  */
 export type Validator<T = unknown> = StandardSchemaValidator<T>
 
 /**
- * The failing body and the call it came from, handed to `onValidationError` alongside the `ParseError`.
- * `direction` says which slot rejected it: the request body, the success body, or the error body.
+ * The failing value and the call it came from, handed to `onValidationError` alongside the `ParseError`.
+ * `direction` says which side rejected it: the request, the success body, or the error body. `source`
+ * says which part of it: the body, or one of the request param groups.
  */
 export type ValidationErrorContext = {
   value: unknown
   direction: 'request' | 'response' | 'error'
+  source: 'body' | 'path' | 'query' | 'headers'
   method?: string
   url?: string
   status?: number
@@ -192,6 +195,7 @@ export type Auth = {
   scheme?: 'bearer' | 'basic'
   name?: string
   in?: 'header' | 'query' | 'cookie'
+  scopes?: Array<string>
 }
 
 /**
@@ -233,7 +237,7 @@ export type RequestConfig<TBody = unknown, TRequest = Request, TResponse = Respo
   transport?: Transport<TRequest, TResponse>
   serializer?: Serializers
   codecs?: Record<string, Codec>
-  validator?: { request?: Validator; response?: Validator; error?: Validator }
+  validator?: { request?: Validator; path?: Validator; query?: Validator; headers?: Validator; response?: Validator; error?: Validator }
   onValidationError?: ValidationErrorHandler
   security?: Array<Auth>
   auth?: AuthResolver
@@ -333,6 +337,8 @@ export type Interceptors<TRequest = Request, TResponse = Response> = {
   error: InterceptorStack<ResponseError<unknown, TRequest, TResponse>, RequestConfig<unknown, TRequest, TResponse>>
 }
 
+export type UrlConfig = Pick<RequestConfig, 'baseURL' | 'url' | 'path' | 'query' | 'params' | 'serializer' | 'styles'>
+
 /**
  * A client instance: the callable send plus configuration, interceptors, and an isolated
  * `createClient` factory bound to the same transport.
@@ -341,7 +347,7 @@ export type ClientInstance<TRequest = Request, TResponse = Response> = {
   <TBody = unknown>(config: RequestConfig<TBody, TRequest, TResponse>): Promise<CallResult<TRequest, TResponse>>
   getConfig: () => ClientConfig<TRequest, TResponse>
   setConfig: (config: ClientConfig<TRequest, TResponse>) => ClientConfig<TRequest, TResponse>
-  getUrl: <TBody = unknown>(config: RequestConfig<TBody, TRequest, TResponse>) => string
+  getUrl: (config: UrlConfig) => string
   interceptors: Interceptors<TRequest, TResponse>
   createClient: (config?: ClientConfig<TRequest, TResponse>) => ClientInstance<TRequest, TResponse>
 }
@@ -391,9 +397,14 @@ export class ResponseError<TError = unknown, TRequest = Request, TResponse = Res
 
 export type ResponseErrorConfig<TError = unknown> = ResponseError<TError>
 
+function headerEntries(headers: object): Array<[string, unknown]> {
+  if (Array.isArray(headers)) return headers
+  return headers instanceof Headers ? [...headers] : Object.entries(headers)
+}
+
 function serializeHeaders(headers: HeadersInit | undefined): Record<string, string> {
   if (!headers) return {}
-  const entries = Array.isArray(headers) ? headers : Object.entries(headers)
+  const entries = headerEntries(headers)
   const result: Record<string, string> = {}
   for (const [key, value] of entries) {
     if (value === undefined || value === null) continue
@@ -402,8 +413,22 @@ function serializeHeaders(headers: HeadersInit | undefined): Record<string, stri
   return result
 }
 
-function mergeHeaders(...sources: Array<HeadersInit | undefined>): Record<string, string> {
-  return Object.assign({}, ...sources.map(serializeHeaders))
+function collectHeadersCaseInsensitive(...sources: Array<unknown>): Record<string, unknown> {
+  const keys = new Map<string, string>()
+  const result: Record<string, unknown> = {}
+  for (const source of sources) {
+    if (!source) continue
+    const entries = headerEntries(source)
+    for (const [key, value] of entries) {
+      if (value === undefined || value === null) continue
+      const lowerCase = key.toLowerCase()
+      const previous = keys.get(lowerCase)
+      if (previous !== undefined) delete result[previous]
+      keys.set(lowerCase, key)
+      result[key] = value
+    }
+  }
+  return result
 }
 
 function getHeader(headers: Record<string, string>, name: string): string | undefined {
@@ -572,15 +597,29 @@ async function resolveRequest<TBody, TRequest, TResponse>({
 }): Promise<{ request: ResolvedRequest; codecs: Record<string, Codec> }> {
   const { querySerializer, bodySerializer, pathSerializer } = resolveSerializers({ config, requestConfig })
   const codecs = { ...config.codecs, ...requestConfig.codecs }
+  const onValidationError = requestConfig.onValidationError ?? config.onValidationError
+  const validationContext = { direction: 'request', method: requestConfig.method, url: requestConfig.url } as const
+
+  // Params are encoded before anything reads them: headers before styling, query before auth adds its values.
+  const paramValues = {
+    path: { ...(requestConfig.path as Record<string, unknown> | undefined) },
+    query: { ...((requestConfig.query ?? requestConfig.params) as Record<string, unknown> | undefined) },
+    headers: collectHeadersCaseInsensitive(config.headers, requestConfig.headers),
+  }
+  const [validatedPath, validatedQuery, validatedHeaders] = await Promise.all(
+    (['path', 'query', 'headers'] as const).map((source) =>
+      runValidator({ validator: requestConfig.validator?.[source], value: paramValues[source], context: { ...validationContext, source }, onValidationError }),
+    ),
+  )
 
-  const headers = mergeHeaders(config.headers, applyHeaderStyles(requestConfig.headers as HeadersInit | undefined, requestConfig.styles?.header))
+  const headers = serializeHeaders(applyHeaderStyles(validatedHeaders as HeadersInit | undefined, requestConfig.styles?.header))
   const { request: requestContentTypeOption, response: responseContentType } = resolveContentType(requestConfig.contentType)
   const requestContentType = requestContentTypeOption ?? getHeader(headers, 'content-type')
   if (responseContentType && !hasHeader(headers, 'accept')) {
     headers['Accept'] = responseContentType
   }
 
-  const query: Record<string, unknown> = { ...((requestConfig.query ?? requestConfig.params) as Record<string, unknown> | undefined) }
+  const query: Record<string, unknown> = { ...(validatedQuery as Record<string, unknown> | undefined) }
 
   await resolveAuth({
     security: requestConfig.security,
@@ -597,8 +636,8 @@ async function resolveRequest<TBody, TRequest, TResponse>({
   const validatedBody = await runValidator({
     validator: requestConfig.validator?.request,
     value: requestConfig.body,
-    context: { direction: 'request', method: requestConfig.method, url: requestConfig.url },
-    onValidationError: requestConfig.onValidationError ?? config.onValidationError,
+    context: { ...validationContext, source: 'body' },
+    onValidationError,
   })
   const requestContentTypeBase = baseContentType(requestContentType)
   const contentCodec = requestContentTypeBase ? codecs[requestContentTypeBase] : undefined
@@ -619,7 +658,7 @@ async function resolveRequest<TBody, TRequest, TResponse>({
 
   const url = serializeUrl({
     parts: [requestConfig.baseURL ?? config.baseURL, requestConfig.url],
-    pathParams: (requestConfig.path ?? {}) as Record<string, unknown>,
+    pathParams: (validatedPath ?? {}) as Record<string, unknown>,
     search: querySerializer(query, requestConfig.styles?.query),
     pathSerializer,
     pathStyles: requestConfig.styles?.path,
@@ -680,7 +719,7 @@ async function settleResult<TRequest, TResponse>({
     const data = await runValidator({
       validator: validator?.response,
       value: decoded,
-      context: { direction: 'response', ...validationContext },
+      context: { direction: 'response', source: 'body', ...validationContext },
       onValidationError,
     })
     return { status: result.status, data, error: undefined, contentType, request: result.request, response: result.response }
@@ -689,7 +728,7 @@ async function settleResult<TRequest, TResponse>({
   const error = await runValidator({
     validator: validator?.error,
     value: decoded,
-    context: { direction: 'error', ...validationContext },
+    context: { direction: 'error', source: 'body', ...validationContext },
     onValidationError,
   })
   if (throwOnError) {

package/templates/standardSchema.ts

@@ -52,3 +52,58 @@ export async function validateStandardSchema<TOutput>(schema: StandardSchemaVali
   }
   return (result as { value: TOutput }).value
 }
+
+/**
+ * Wraps an object schema so its keys match case-insensitively.
+ * Keys the schema does not declare pass through untouched.
+ * The declared keys are validated with `schema` under their declared names.
+ * Every key, and every issue path, keeps the casing the caller used.
+ *
+ * @param schema Standard Schema-compatible object schema.
+ * @param entries The record of keys the passed object schema validates.
+ * @example
+ * ```ts
+ * validator: { headers: toHeadersStandardSchema(putEventHeadersSchema, putEventHeadersSchema.shape) }
+ * ```
+ */
+export function toHeadersStandardSchema(schema: StandardSchemaValidator, entries: Record<string, unknown>): StandardSchemaValidator {
+  const declared = new Map(Object.keys(entries).map((name) => [name.toLowerCase(), name]))
+
+  function validate(value: unknown): StandardSchemaResult<unknown> | Promise<StandardSchemaResult<unknown>> {
+    if (typeof value !== 'object' || value === null) {
+      return { issues: [{ message: 'Expected an object' }] }
+    }
+
+    const originalKeys = new Map<string, string>()
+    const declaredValues: Record<string, unknown> = {}
+    const undeclaredValues: Record<string, unknown> = {}
+    for (const [key, entry] of Object.entries(value)) {
+      const name = declared.get(key.toLowerCase())
+      if (name === undefined) {
+        undeclaredValues[key] = entry
+        continue
+      }
+      originalKeys.set(name, key)
+      declaredValues[name] = entry
+    }
+
+    const toOriginal = (key: string) => originalKeys.get(key) ?? key
+    const settle = (result: StandardSchemaResult<unknown>): StandardSchemaResult<unknown> => {
+      if (result.issues) {
+        return {
+          issues: result.issues.map((issue): StandardSchemaIssue => ({
+            ...issue,
+            path: issue.path?.map((segment, index) => (index === 0 && typeof segment === 'string' ? toOriginal(segment) : segment)),
+          })),
+        }
+      }
+      const validated = Object.entries((result.value ?? {}) as Record<string, unknown>).map(([key, entry]) => [toOriginal(key), entry])
+      return { value: { ...undeclaredValues, ...Object.fromEntries(validated) } }
+    }
+
+    const result = schema['~standard'].validate(declaredValues)
+    return result instanceof Promise ? result.then(settle) : settle(result)
+  }
+
+  return { '~standard': { validate } }
+}