@kubb/plugin-fetch 5.0.0-beta.80 → 5.0.0-beta.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-fetch",
-  "version": "5.0.0-beta.80",
+  "version": "5.0.0-beta.81",
   "description": "Generate a slim, type-safe HTTP client with Kubb based on the native Fetch api.",
   "keywords": [
     "api-client",
@@ -49,11 +49,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/ast": "5.0.0-beta.79",
-    "@kubb/core": "5.0.0-beta.79",
-    "@kubb/renderer-jsx": "5.0.0-beta.79",
-    "@kubb/plugin-ts": "5.0.0-beta.80",
-    "@kubb/plugin-zod": "5.0.0-beta.80"
+    "@kubb/ast": "5.0.0-beta.80",
+    "@kubb/core": "5.0.0-beta.80",
+    "@kubb/renderer-jsx": "5.0.0-beta.80",
+    "@kubb/plugin-ts": "5.0.0-beta.81",
+    "@kubb/plugin-zod": "5.0.0-beta.81"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
@@ -62,7 +62,7 @@
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.79"
+    "@kubb/renderer-jsx": "5.0.0-beta.80"
   },
   "engines": {
     "node": ">=22"

package/src/plugin.ts

@@ -80,6 +80,7 @@ export const pluginFetch = definePlugin<PluginFetch>((options) => {
         ctx.addGenerator(...selectedGenerators)
 
         const root = path.resolve(ctx.config.root, ctx.config.output.path)
+        const baseURLExpression = baseURL ? (baseURL.includes('${') ? `\`${baseURL.replaceAll('`', '\\`')}\`` : JSON.stringify(baseURL)) : undefined
 
         ctx.injectFile({
           baseName: 'serializers.ts',
@@ -91,7 +92,7 @@ export const pluginFetch = definePlugin<PluginFetch>((options) => {
           baseName: 'client.ts',
           path: path.resolve(root, '.kubb/client.ts'),
           copy: fetchClientTemplatePath,
-          footer: baseURL ? `client.setConfig({ baseURL: ${JSON.stringify(baseURL)} })` : undefined,
+          footer: baseURLExpression ? `client.setConfig({ baseURL: ${baseURLExpression} })` : undefined,
         })
 
         ctx.injectFile({

package/templates/fetch.ts

@@ -387,16 +387,23 @@ export async function resolveAuth(params: {
   const { security, auth, headers, query } = params
   if (!security?.length || auth === undefined) return
 
+  // An explicit caller-set header wins over the resolved token.
+  const hasHeader = (name: string) => Object.keys(headers).some((key) => key.toLowerCase() === name.toLowerCase())
+
   for (const scheme of security) {
     const token = typeof auth === 'function' ? await auth(scheme) : auth
     if (token === undefined) continue
 
     if (scheme.type === 'apiKey') {
       const name = scheme.name ?? 'Authorization'
-      if (scheme.in === 'query') query[name] = token
-      else if (scheme.in === 'cookie') headers.Cookie = [headers.Cookie, `${name}=${token}`].filter(Boolean).join('; ')
-      else headers[name] = token
-    } else {
+      if (scheme.in === 'query') {
+        if (query[name] === undefined) query[name] = token
+      } else if (scheme.in === 'cookie') {
+        headers.Cookie = [headers.Cookie, `${name}=${token}`].filter(Boolean).join('; ')
+      } else if (!hasHeader(name)) {
+        headers[name] = token
+      }
+    } else if (!hasHeader('Authorization')) {
       headers.Authorization = scheme.scheme === 'basic' ? `Basic ${btoa(token)}` : `Bearer ${token}`
     }
     return
@@ -434,73 +441,80 @@ function resolveContentType(contentType: ContentType | undefined): { request?: s
 }
 
 /**
- * Builds the shared client core bound to a transport, exported by each plugin as `client` plus a `createClient` factory.
+ * The per-concern serializers for a call, the per-call serializer winning over the client's and
+ * falling back to the defaults.
  */
-export function createClientCore<TRequest = Request, TResponse = Response>(
-  options: { defaultTransport: Transport<TRequest, TResponse> } & ClientConfig<TRequest, TResponse>,
-): ClientInstance<TRequest, TResponse> {
-  const { defaultTransport, ...initialConfig } = options
-  let config: ClientConfig<TRequest, TResponse> = { ...initialConfig }
+function resolveSerializers({ config, requestConfig }: { config: { serializer?: Serializers }; requestConfig: { serializer?: Serializers } }) {
+  return {
+    querySerializer: requestConfig.serializer?.query ?? config.serializer?.query ?? defaultQuerySerializer,
+    bodySerializer: requestConfig.serializer?.body ?? config.serializer?.body ?? defaultBodySerializer,
+    pathSerializer: requestConfig.serializer?.path ?? config.serializer?.path ?? defaultPathSerializer,
+  }
+}
 
-  const interceptors: Interceptors<TRequest, TResponse> = {
-    request: createInterceptorStack<ResolvedRequest>(),
-    response: createInterceptorStack<TransportResult<unknown, TRequest, TResponse>>(),
-    error: createInterceptorStack<ResponseError<unknown, TRequest, TResponse>>(),
+/**
+ * Resolves everything a call needs before it touches the transport: merged headers with the
+ * negotiated content type, auth on headers or query, serialized cookies, the validated and
+ * serialized body, and the full URL.
+ */
+async function resolveRequest<TBody, TRequest, TResponse>({
+  config,
+  requestConfig,
+}: {
+  config: ClientConfig<TRequest, TResponse>
+  requestConfig: RequestConfig<TBody, TRequest, TResponse>
+}): Promise<{ request: ResolvedRequest; codecs: Record<string, Codec> }> {
+  const { querySerializer, bodySerializer, pathSerializer } = resolveSerializers({ config, requestConfig })
+  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 client = (async <TBody = unknown>(requestConfig: RequestConfig<TBody, TRequest, TResponse>): Promise<CallResult<TRequest, TResponse>> => {
-    const transport = requestConfig.transport ?? config.transport ?? defaultTransport
-    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) }
 
-    const query: Record<string, unknown> = { ...((requestConfig.query ?? requestConfig.params) as Record<string, unknown> | undefined) }
+  await resolveAuth({
+    security: requestConfig.security,
+    auth: requestConfig.auth ?? config.auth,
+    headers,
+    query,
+  })
 
-    await resolveAuth({
-      security: requestConfig.security,
-      auth: requestConfig.auth ?? config.auth,
-      headers,
-      query,
-    })
+  if (requestConfig.cookies) {
+    const cookie = serializeCookies(requestConfig.cookies, requestConfig.styles?.cookie)
+    if (cookie) headers.Cookie = [headers.Cookie, cookie].filter(Boolean).join('; ')
+  }
 
-    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 the runtime appends the multipart boundary.
+  if (body instanceof FormData) {
+    delete headers['Content-Type']
+    delete headers['content-type']
+  } else if (requestContentTypeOption) {
+    headers['Content-Type'] = requestContentTypeOption
+  }
 
-    const rawBody = requestConfig.body
-    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 (requestContentTypeOption) {
-      headers['Content-Type'] = requestContentTypeOption
-    }
-    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 url = serializeUrl({
+    parts: [requestConfig.baseURL ?? config.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
+  const options = config.options || requestConfig.options ? { ...config.options, ...requestConfig.options } : undefined
 
-    let resolvedRequest: ResolvedRequest = {
+  return {
+    codecs,
+    request: {
       url,
       method: (requestConfig.method ?? 'GET').toUpperCase(),
       headers,
@@ -509,48 +523,86 @@ export function createClientCore<TRequest = Request, TResponse = Response>(
       credentials: requestConfig.credentials,
       options,
       responseType: requestConfig.responseType,
-    }
-    resolvedRequest = await interceptors.request.run(resolvedRequest)
-
-    let result = await transport(resolvedRequest)
-    result = await interceptors.response.run(result)
-
-    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: parsedErrorData,
-        status: result.status,
-        statusText: result.statusText,
-        contentType,
-        request: result.request,
-        response: result.response,
-      })
-      await interceptors.error.run(error)
-      throw error
-    }
+/**
+ * Turns a transport result into the call result: decodes the body through the matching codec,
+ * validates it, and throws a `ResponseError` (after running the error interceptors) for a non-2xx
+ * response under `throwOnError`.
+ */
+async function settleResult<TRequest, TResponse>({
+  result,
+  codecs,
+  throwOnError,
+  validator,
+  errorInterceptors,
+}: {
+  result: TransportResult<unknown, TRequest, TResponse>
+  codecs: Record<string, Codec>
+  throwOnError: boolean
+  validator: { response?: Validator; error?: Validator } | undefined
+  errorInterceptors: InterceptorStack<ResponseError<unknown, TRequest, TResponse>>
+}): Promise<CallResult<TRequest, TResponse>> {
+  const isSuccess = result.status >= 200 && result.status < 300
+  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 data = isSuccess ? await runValidator(requestConfig.validator?.response, decoded) : undefined
-    const error = isSuccess ? undefined : parsedErrorData
+  if (isSuccess) {
+    const data = await runValidator(validator?.response, decoded)
+    return { status: result.status, data, error: undefined, contentType, request: result.request, response: result.response }
+  }
 
-    return {
+  const error = await runValidator(validator?.error, decoded)
+  if (throwOnError) {
+    const responseError = new ResponseError({
+      data: error,
       status: result.status,
-      data,
-      error,
+      statusText: result.statusText,
       contentType,
       request: result.request,
       response: result.response,
-    }
+    })
+    await errorInterceptors.run(responseError)
+    throw responseError
+  }
+  return { status: result.status, data: undefined, error, contentType, request: result.request, response: result.response }
+}
+
+/**
+ * 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>,
+): ClientInstance<TRequest, TResponse> {
+  const { defaultTransport, ...initialConfig } = options
+  let config: ClientConfig<TRequest, TResponse> = { ...initialConfig }
+
+  const interceptors: Interceptors<TRequest, TResponse> = {
+    request: createInterceptorStack<ResolvedRequest>(),
+    response: createInterceptorStack<TransportResult<unknown, TRequest, TResponse>>(),
+    error: createInterceptorStack<ResponseError<unknown, TRequest, TResponse>>(),
+  }
+
+  const client = (async <TBody = unknown>(requestConfig: RequestConfig<TBody, TRequest, TResponse>): Promise<CallResult<TRequest, TResponse>> => {
+    const transport = requestConfig.transport ?? config.transport ?? defaultTransport
+    const { request, codecs } = await resolveRequest({ config, requestConfig })
+
+    const resolvedRequest = await interceptors.request.run(request)
+    const result = await interceptors.response.run(await transport(resolvedRequest))
+
+    return settleResult({
+      result,
+      codecs,
+      throwOnError: requestConfig.throwOnError ?? config.throwOnError ?? true,
+      validator: requestConfig.validator,
+      errorInterceptors: interceptors.error,
+    })
   }) as ClientInstance<TRequest, TResponse>
 
   client.getConfig = () => config
@@ -559,11 +611,10 @@ export function createClientCore<TRequest = Request, TResponse = Response>(
     return config
   }
   client.getUrl = (requestConfig) => {
-    const querySerializer = requestConfig.serializer?.query ?? config.serializer?.query ?? defaultQuerySerializer
-    const pathSerializer = requestConfig.serializer?.path ?? config.serializer?.path ?? defaultPathSerializer
+    const { querySerializer, pathSerializer } = resolveSerializers({ config, requestConfig })
     const query: Record<string, unknown> = { ...((requestConfig.query ?? requestConfig.params) as Record<string, unknown> | undefined) }
     return serializeUrl({
-      parts: [config.baseURL, requestConfig.baseURL, requestConfig.url],
+      parts: [requestConfig.baseURL ?? config.baseURL, requestConfig.url],
       pathParams: requestConfig.path ?? {},
       search: querySerializer(query, requestConfig.styles?.query),
       pathSerializer,
@@ -607,7 +658,7 @@ async function parseResponse(response: Response, responseType?: ResponseType): P
     case 'stream':
       return response.body ?? undefined
     case 'json': {
-      // An empty body with a JSON content-type would make response.json() throw; treat it as no data.
+      // An empty body with a JSON content-type would make response.json() throw, so treat it as no data.
       const body = await response.text()
       return body ? JSON.parse(body) : undefined
     }
@@ -622,6 +673,34 @@ async function parseResponse(response: Response, responseType?: ResponseType): P
   }
 }
 
+/**
+ * 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,
+    signal: request.signal,
+  }
+  if (request.credentials) init.credentials = request.credentials
+
+  const nativeRequest = new Request(request.url, init)
+  const response = await globalThis.fetch(nativeRequest)
+  const data = await parseResponse(response, request.responseType)
+
+  return {
+    data,
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+    contentType: getResponseContentType(response.headers),
+    request: nativeRequest,
+    response,
+  }
+}
+
 /**
  * One decoded Server-Sent Event, with `data` parsed as JSON when valid and kept as the raw string otherwise.
  */
@@ -724,34 +803,6 @@ export async function toEventStream<TData = unknown>(result: Promise<{ data: unk
   }
 }
 
-/**
- * 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,
-    signal: request.signal,
-  }
-  if (request.credentials) init.credentials = request.credentials
-
-  const nativeRequest = new Request(request.url, init)
-  const response = await globalThis.fetch(nativeRequest)
-  const data = await parseResponse(response, request.responseType)
-
-  return {
-    data,
-    status: response.status,
-    statusText: response.statusText,
-    headers: response.headers,
-    contentType: getResponseContentType(response.headers),
-    request: nativeRequest,
-    response,
-  }
-}
-
 export const client = createClientCore({ defaultTransport })
 
 export const createClient = (config?: Parameters<typeof client.createClient>[0]) => client.createClient(config)