stitchkit 0.37.0 → 0.38.0

package/dist/tools.js

@@ -2,7 +2,7 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-xq45akyd.js";
+} from "./index-bgdd42pt.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS
 } from "./index-czmqks7r.js";
@@ -24,7 +24,7 @@ import {
   readCapped,
   toolResultFromError,
   writeDownload
-} from "./index-s6yhmg1k.js";
+} from "./index-n5t4gnfz.js";
 import {
   toJsonSchema
 } from "./index-frfyw9fa.js";
@@ -38,7 +38,7 @@ import {
   isRecord,
   mergeMeta,
   typedEntries
-} from "./index-e497hxcy.js";
+} from "./index-mzx0an0s.js";
 
 // src/tools/agent.ts
 import { jsonSchema, tool } from "ai";
@@ -1235,6 +1235,117 @@ function appendFormFields(formData, values, skipKeys) {
   }
 }
 
+// src/browser/client-url.ts
+function isParamArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" || typeof item === "number");
+}
+function collectQueryParams(args, endpoint) {
+  const params = {};
+  let hasParams = false;
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined || value === null)
+      continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isParamArray(value)) {
+      params[key] = value;
+      hasParams = true;
+      continue;
+    }
+    const what = Array.isArray(value) ? "an array with non-primitive items" : typeof value === "object" ? "a nested object" : `a ${typeof value}`;
+    throw new Error(`${endpoint.method} ${endpoint.path}: input field "${key}" is ${what} — it cannot ` + "travel as a query parameter. GET / DELETE input must be flat (string / number / " + "boolean, or an array of string / number); flatten the field or move the " + "operation to a body verb (POST).");
+  }
+  return hasParams ? params : undefined;
+}
+function hasStringKeys(args, keys) {
+  for (const key of keys) {
+    if (typeof args[key] !== "string")
+      return false;
+  }
+  return true;
+}
+function resolvePathPrefix(config, args) {
+  if (!config?.pathPrefix)
+    return "";
+  if (typeof config.pathPrefix === "string")
+    return config.pathPrefix;
+  const keys = config.stripPrefixKeys ?? [];
+  if (!hasStringKeys(args, keys)) {
+    const missing = keys.find((key) => typeof args[key] !== "string");
+    throw new Error(`Missing path prefix key: ${missing}`);
+  }
+  return config.pathPrefix(args);
+}
+function extractParamNames(path) {
+  const matches = path.match(/:(\w+)/g);
+  const names = matches ? matches.map((match) => match.slice(1)) : [];
+  if (path.endsWith("/*"))
+    names.push("*");
+  return names;
+}
+function fillPathParams(path, args) {
+  let filled = path.replace(/:(\w+)/g, (_, key) => {
+    const value = args[key];
+    if (value === undefined || value === null) {
+      throw new Error(`Missing path param: ${key}`);
+    }
+    return encodeURIComponent(String(value));
+  });
+  if (!filled.endsWith("/*"))
+    return filled;
+  const wildcard = args["*"];
+  if (wildcard === undefined || wildcard === null) {
+    throw new Error("Missing path param: *");
+  }
+  const remainder = String(wildcard).split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  filled = `${filled.slice(0, -1)}${remainder}`;
+  return filled;
+}
+function stripConsumedArgs(args, path, scopeKeys) {
+  const consumed = new Set(scopeKeys);
+  for (const name of extractParamNames(path))
+    consumed.add(name);
+  const remaining = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (!consumed.has(key) && value !== undefined)
+      remaining[key] = value;
+  }
+  return remaining;
+}
+function appendQuery(relativeUrl, params) {
+  if (!params)
+    return relativeUrl;
+  const search = new URLSearchParams;
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      for (const item of value)
+        search.append(key, String(item));
+    } else {
+      search.set(key, String(value));
+    }
+  }
+  return search.size > 0 ? `${relativeUrl}?${search}` : relativeUrl;
+}
+function planClientRequest(endpoint, contractPrefix, args, config) {
+  let pathPrefix = resolvePathPrefix(config, args);
+  if (pathPrefix && !pathPrefix.endsWith("/"))
+    pathPrefix += "/";
+  if (pathPrefix.startsWith("/"))
+    pathPrefix = pathPrefix.slice(1);
+  const endpointPath = endpoint.path === "/" ? "" : endpoint.path;
+  let relativeUrl = fillPathParams(`${pathPrefix}${contractPrefix}${endpointPath}`, args);
+  if (relativeUrl.endsWith("/"))
+    relativeUrl = relativeUrl.slice(0, -1);
+  const remainingArgs = stripConsumedArgs(args, endpoint.path, config?.stripPrefixKeys ?? []);
+  if (inputIsQuery(endpoint.method)) {
+    relativeUrl = appendQuery(relativeUrl, collectQueryParams(remainingArgs, endpoint));
+  }
+  return { relativeUrl, remainingArgs };
+}
+function joinClientBaseUrl(baseUrl, relativeUrl) {
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const path = relativeUrl.startsWith("/") ? relativeUrl : `/${relativeUrl}`;
+  return `${base}${path}`;
+}
+
 // src/browser/http.ts
 import ky, { isHTTPError } from "ky";
 class ApiError extends Error {
@@ -1285,25 +1396,6 @@ function withOutput(endpoint, result) {
     return result;
   return result.then((value) => value === undefined ? undefined : schema.parse(value));
 }
-function isParamArray(value) {
-  return Array.isArray(value) && value.every((v) => typeof v === "string" || typeof v === "number");
-}
-function collectQueryParams(args, skipKeys, endpoint) {
-  const params = {};
-  let hasParams = false;
-  for (const [key, value] of Object.entries(args)) {
-    if (skipKeys.has(key) || value === undefined || value === null)
-      continue;
-    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isParamArray(value)) {
-      params[key] = value;
-      hasParams = true;
-      continue;
-    }
-    const what = Array.isArray(value) ? "an array with non-primitive items" : typeof value === "object" ? "a nested object" : `a ${typeof value}`;
-    throw new Error(`${endpoint.method} ${endpoint.path}: input field "${key}" is ${what} — it cannot ` + "travel as a query parameter. GET / DELETE input must be flat (string / number / " + "boolean, or an array of string / number); flatten the field or move the " + "operation to a body verb (POST).");
-  }
-  return hasParams ? params : undefined;
-}
 function createClient(contract, configOrClient, contractConfig) {
   const client = {};
   const makeMethod = isHttpAdapter(configOrClient) ? (endpoint) => createHttpMethod(endpoint, contract.meta.prefix, configOrClient, contractConfig) : (endpoint) => createFetchMethod(endpoint, contract.meta.prefix, configOrClient, contractConfig);
@@ -1322,27 +1414,9 @@ function setClientMethod(target, key, method) {
 }
 function createHttpMethod(endpoint, prefix, client, config) {
   const httpMethod = endpoint.method.toLowerCase();
-  const isGet = httpMethod === "get";
-  const paramNames = extractParamNames(endpoint.path);
-  const prefixKeys = new Set([...config?.stripPrefixKeys ?? [], ...paramNames]);
   return (...args) => {
     const firstArg = args[0] ?? {};
-    let pathPrefixStr = "";
-    if (config?.pathPrefix) {
-      pathPrefixStr = typeof config.pathPrefix === "function" ? config.pathPrefix(firstArg) : config.pathPrefix;
-      if (pathPrefixStr && !pathPrefixStr.endsWith("/"))
-        pathPrefixStr += "/";
-    }
-    let url = `${pathPrefixStr}${prefix}${endpoint.path}`;
-    for (const name of paramNames) {
-      const value = firstArg[name];
-      if (value === undefined || value === null) {
-        throw new Error(`Missing path param: ${name}`);
-      }
-      url = url.replace(`:${name}`, encodeURIComponent(String(value)));
-    }
-    if (url.endsWith("/"))
-      url = url.slice(0, -1);
+    const plan = planClientRequest(endpoint, prefix, firstArg, config);
     if (endpoint.multipart) {
       const file = firstArg[endpoint.multipart];
       if (!isMultipartFile(file)) {
@@ -1353,59 +1427,28 @@ function createHttpMethod(endpoint, prefix, client, config) {
       }
       const formData = new FormData;
       appendMultipartFile(formData, endpoint.multipart, file);
-      appendFormFields(formData, firstArg, new Set([...prefixKeys, endpoint.multipart]));
-      return withOutput(endpoint, client[httpMethod](url, formData, withTimeout(undefined, endpoint)));
+      appendFormFields(formData, plan.remainingArgs, new Set([endpoint.multipart]));
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, formData, withTimeout(undefined, endpoint)));
     }
-    if (isGet) {
-      const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return withOutput(endpoint, client.get(url, withTimeout(params ? { params } : undefined, endpoint)));
+    if (httpMethod === "get") {
+      return withOutput(endpoint, client.get(plan.relativeUrl, withTimeout(undefined, endpoint)));
     }
     if (httpMethod === "delete") {
-      const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return withOutput(endpoint, client.delete(url, withTimeout(params ? { params } : undefined, endpoint)));
-    }
-    const payload = {};
-    for (const [key, value] of Object.entries(firstArg)) {
-      if (!prefixKeys.has(key) && value !== undefined) {
-        payload[key] = value;
-      }
+      return withOutput(endpoint, client.delete(plan.relativeUrl, withTimeout(undefined, endpoint)));
     }
-    return withOutput(endpoint, client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint)));
+    return withOutput(endpoint, client[httpMethod](plan.relativeUrl, Object.keys(plan.remainingArgs).length > 0 ? plan.remainingArgs : undefined, withTimeout(undefined, endpoint)));
   };
 }
 function createFetchMethod(endpoint, prefix, config, contractConfig) {
-  const prefixKeys = new Set(contractConfig?.stripPrefixKeys ?? []);
   return async (args) => {
-    let pathPrefixStr = "";
-    if (contractConfig?.pathPrefix) {
-      pathPrefixStr = typeof contractConfig.pathPrefix === "function" ? contractConfig.pathPrefix(args ?? {}) : contractConfig.pathPrefix;
-      if (pathPrefixStr && !pathPrefixStr.endsWith("/"))
-        pathPrefixStr += "/";
-    }
-    let url = buildFetchUrl(config.baseUrl, prefix, endpoint.path, args, pathPrefixStr);
+    const plan = planClientRequest(endpoint, prefix, args ?? {}, contractConfig);
+    const url = joinClientBaseUrl(config.baseUrl, plan.relativeUrl);
     const headers = {
       Accept: "application/json",
       ...typeof config.headers === "function" ? config.headers() : config.headers
     };
     const signal = endpoint.timeout !== undefined ? AbortSignal.timeout(endpoint.timeout) : undefined;
-    const isQuery = inputIsQuery(endpoint.method);
-    const hasBody = !isQuery && !endpoint.multipart && endpoint.input && args;
-    if (isQuery && args) {
-      const remaining = stripParams(args, endpoint.path, prefixKeys);
-      const params = collectQueryParams(remaining, new Set, endpoint);
-      if (params) {
-        const searchParams = new URLSearchParams;
-        for (const [k, v] of Object.entries(params)) {
-          if (Array.isArray(v)) {
-            for (const item of v)
-              searchParams.append(k, String(item));
-          } else {
-            searchParams.set(k, String(v));
-          }
-        }
-        url += `?${searchParams}`;
-      }
-    }
+    const hasBody = endpoint.method !== "GET" && endpoint.method !== "DELETE" && !endpoint.multipart && endpoint.input && args;
     if (hasBody)
       headers["Content-Type"] = "application/json";
     if (endpoint.multipart && args) {
@@ -1415,7 +1458,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       }
       const formData = new FormData;
       appendMultipartFile(formData, endpoint.multipart, file);
-      appendFormFields(formData, stripParams(args, endpoint.path, prefixKeys), new Set([endpoint.multipart]));
+      appendFormFields(formData, plan.remainingArgs, new Set([endpoint.multipart]));
       const res2 = await fetch(url, {
         method: endpoint.method,
         headers,
@@ -1439,7 +1482,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       credentials: config.credentials,
       signal,
       ...hasBody && {
-        body: JSON.stringify(stripParams(hasBody, endpoint.path, prefixKeys))
+        body: JSON.stringify(plan.remainingArgs)
       }
     });
     if (!res.ok) {
@@ -1462,36 +1505,6 @@ async function throwForErrorResponse(res, config, fallbackBody) {
   }
   throw new ApiError("HTTP_ERROR", res.status, { body });
 }
-function extractParamNames(path) {
-  const matches = path.match(/:(\w+)/g);
-  return matches ? matches.map((m) => m.slice(1)) : [];
-}
-function buildFetchUrl(baseUrl, prefix, path, args, pathPrefix = "") {
-  let fullPath = `/${pathPrefix}${prefix}${path === "/" ? "" : path}`;
-  if (args) {
-    fullPath = fullPath.replace(/:(\w+)/g, (_, key) => {
-      const val = args[key];
-      if (val === undefined || val === null) {
-        throw new Error(`Missing path param: ${key}`);
-      }
-      return encodeURIComponent(String(val));
-    });
-  }
-  return `${baseUrl}${fullPath}`;
-}
-function stripParams(args, path, extra) {
-  const skip = new Set(extra);
-  for (const match of path.matchAll(/:(\w+)/g)) {
-    if (match[1])
-      skip.add(match[1]);
-  }
-  const result = {};
-  for (const [k, v] of Object.entries(args)) {
-    if (!skip.has(k))
-      result[k] = v;
-  }
-  return result;
-}
 
 // src/tools/remote.ts
 var HTTP_ONLY = Object.freeze(["HTTP"]);
@@ -1514,7 +1527,7 @@ function implementRemote(contract, http, options) {
       serviceName: contract.meta.prefix,
       key,
       toolName: "toolName" in endpoint ? endpoint.toolName : undefined,
-      expose: endpoint.rawResponse || endpoint.rawBody ? HTTP_ONLY : endpoint.expose,
+      expose: endpoint.rawResponse || endpoint.rawBody || endpoint.responseMeta ? HTTP_ONLY : endpoint.expose,
       ui: "ui" in endpoint ? endpoint.ui : undefined,
       annotations: "annotations" in endpoint ? endpoint.annotations : undefined,
       meta: mergeMeta(contract.meta.meta, endpoint.meta),
@@ -1527,6 +1540,7 @@ function implementRemote(contract, http, options) {
       idempotent: endpoint.idempotent,
       rawResponse: endpoint.rawResponse,
       rawBody: endpoint.rawBody,
+      responseMeta: endpoint.responseMeta,
       contentType: "contentType" in endpoint ? endpoint.contentType : undefined,
       handler: async (ctx) => {
         const call = client[key];

package/llms-full.txt

@@ -230,7 +230,7 @@ export const users = defineContract({ prefix: 'users' }, {
 | Field | Required | Purpose |
 |-------|----------|---------|
 | `method` | yes | `GET` · `POST` · `PUT` · `PATCH` · `DELETE` |
-| `path` | yes | route path under the contract `prefix`; `:name` marks a path param |
+| `path` | yes | route path under the contract `prefix`; `:name` marks a path param and a terminal `/*` captures the remaining path |
 | `desc` | yes | human description — also the MCP / agent tool description |
 | `params` | no | Zod schema for **path params** (`:id`, …) |
 | `input` | no | Zod schema for the **request body** (or query, for GET/DELETE) |
@@ -245,6 +245,7 @@ export const users = defineContract({ prefix: 'users' }, {
 | `meta` | no | opaque app metadata — read in hooks / on tool mounts, never in OpenAPI ([below](#endpoint-metadata-meta)) |
 | `rawResponse` | no | the handler returns the `Response` itself — a download, a file, an SSE stream. HTTP-only, never a tool, no `output`. See [Raw-response endpoints](./server.md#raw-response-endpoints) |
 | `rawBody` | no | retain original JSON text for a signed HTTP webhook. See [Signed JSON webhooks](./server.md#signed-json-webhooks) |
+| `responseMeta` | no | make a typed-data endpoint HTTP-only, optionally declare its success status and expose `ctx.response.headers` — [Typed JSON response metadata](./server.md#typed-json-response-metadata) |
 | `contentType` | no | documented response media type of a `rawResponse` endpoint (OpenAPI only) |
 
 ## `params` vs `input` vs `output`
@@ -253,7 +254,10 @@ The three schemas are distinct on purpose:
 
 - **`params`** — values in the URL path. `path: '/:id'` ⇒
   `params: z.object({ id: z.string() })`. The client takes them from the call
-  argument and substitutes them into the URL.
+  argument and substitutes them into the URL. A terminal wildcard is the
+  quoted `'*'` field: `path: '/:slug/*'` with
+  `params: z.object({ slug: z.string(), '*': z.string() })` matches both
+  `/foo/page` and `/foo/a/b`; the handler receives `'page'` or `'a/b'`.
 - **`input`** — the request payload. For `POST` / `PUT` / `PATCH` it is the JSON
   body; for `GET` / `DELETE` it is the query string. The handler reads it as
   `ctx.input`.
@@ -267,6 +271,9 @@ the body.
 ```ts
 // path: '/:id', params: { id }, input: { text }
 await api.update({ id: '1', text: 'new' })   // PUT /users/1  body: { text: 'new' }
+
+// path: '/:slug/*', params: { slug, '*': remainder }
+await api.app({ slug: 'foo', '*': 'a/b' })   // GET /apps/foo/a/b
 ```
 
 ### Input vs. output types
@@ -317,10 +324,12 @@ tools. Narrow it with `expose`:
 - `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
 - omit `expose` — all transports.
 
-Tool transports (`MCP`, `AGENT`) skip two kinds of endpoint automatically:
+Tool transports (`MCP`, `AGENT`) skip three kinds of endpoint automatically:
 `multipart` (a file upload is not a tool call) and
 [`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
-a tool result cannot carry — it would serialize to `{}`).
+a tool result cannot carry — it would serialize to `{}`), plus
+[`responseMeta`](./server.md#typed-json-response-metadata) (outbound HTTP
+headers have no meaning on a tool call).
 
 ## `toolName`
 
@@ -764,6 +773,17 @@ prefix param in the schema, use a non-strict `z.object` (extra keys are dropped
 from `ctx.params`, but `ctx.tenantId` still works), or read the param off the
 context root.
 
+**Trailing wildcard.** A contract path may end in `/*`. `/app/:slug/*` matches
+both `/app/foo` and nested paths such as `/app/foo/a/b`; the collected params are
+`{ slug: 'foo', '*': '' }` and `{ slug: 'foo', '*': 'a/b' }` respectively. Put
+the quoted `'*'` field in the endpoint's `params` schema to keep it in typed
+`ctx.params`. Each captured segment is URL-decoded before the remainder is
+joined, so encoded spaces and reserved characters reach the handler as their
+semantic values while `/` remains the segment boundary. Static and named-param
+routes are matched before a catch-all, so a
+more specific endpoint wins regardless of declaration order. The same matcher
+drives `405 Allow` resolution.
+
 ### Scope-driven mounting (`scopePrefixes`)
 
 With several scopes, hand-partitioning services into `groups` duplicates the
@@ -796,7 +816,7 @@ createServer({
   hooks: {
     onRequest(req)               { /* logging, global rate limit — may return a Response to short-circuit */ },
     beforeHandle(ctx, endpoint)  { /* auth, scope checks — throw to reject */ },
-    afterHandle(ctx, result, ep) { /* transform the result, set cache headers */ },
+    afterHandle(ctx, result, ep) { /* transform the result data */ },
     onError(ctx, error, ep)      { /* custom error response — return a Response */ },
   },
 })
@@ -849,6 +869,46 @@ not retain the text. `maxJsonBodyBytes` may also be set once on `createServer` /
 `createHandler`; a route value wins. Both limits are opt-in and abort an
 oversized stream before it is fully buffered. → ADR 0051
 
+## Typed JSON response metadata
+
+A JSON endpoint that must attach dynamic HTTP headers while preserving typed
+output declares `responseMeta`. The handler still returns ordinary data:
+
+```ts
+const auth = defineContract({ prefix: 'auth' }, {
+  complete: {
+    method: 'POST', path: '/complete', desc: 'Complete authentication',
+    input: CompleteAuthSchema,
+    output: AuthUserSchema,
+    responseMeta: { status: 200 },
+  },
+})
+
+complete: async ({ input, response }) => {
+  const result = await authenticate(input.token)
+  response.headers.append('Set-Cookie', session.set(result.sessionId))
+  response.headers.append('Set-Cookie', preferences.set(result.preferencesId))
+  return result.user
+}
+```
+
+`ctx.response.headers` is a fresh Web Fetch `Headers` bag per request. `append`
+preserves repeated `Set-Cookie` values on Bun and Node. The endpoint is
+HTTP-only, but its typed client method still resolves to `AuthUser` — not
+`Response` — and the final data still passes group/global `afterHandle` and the
+declared `output` schema exactly once.
+
+`responseMeta.status` is static contract metadata and OpenAPI publishes the same
+2xx code. Without it, data keeps status `200` and no-data keeps `204`. Bodyless
+`204`/`205` cannot be combined with `output`. Redirects, streams, files and
+handler-owned status/body logic remain [`rawResponse: true`](#raw-response-endpoints).
+
+Collected headers are merged only after the complete success pipeline. A
+handler, hook or output-validation failure discards them. `Content-Type`,
+`Content-Length`, `x-request-id` and every `Access-Control-*` header remain
+framework-owned; trying to set one fails loudly with the endpoint identity.
+→ [ADR 0052](../decisions/0052-typed-json-response-metadata.md)
+
 ## Raw-response endpoints
 
 An endpoint that answers with **bytes rather than data** — a PDF download, a
@@ -891,6 +951,10 @@ const name = res.headers.get('Content-Disposition')
 const blob = await res.blob()
 ```
 
+When the browser should navigate or assign the endpoint directly to `src`, use
+[`createUrlBuilder`](./client.md#contract-url-builders). Raw-response GET methods
+are included, while mutation and multipart methods are intentionally absent.
+
 Cross-origin, remember that those headers are readable only because CORS exposes
 them — see [`cors.exposeHeaders`](#serving-files--range-requests).
 
@@ -902,6 +966,11 @@ client — which is what you want for an OAuth redirect or a non-JSON webhook. A
 signed JSON webhook can stay validated through
 [`rawBody: true`](#signed-json-webhooks).
 
+If an endpoint returns typed JSON and only needs an additional status/header,
+use [`responseMeta`](#typed-json-response-metadata), not `rawResponse`: the raw
+variant deliberately transfers response ownership and changes the client result
+to `Response`.
+
 ⚠️ **Delete the old raw route when you move an endpoint into the contract.** Raw
 routes are matched **first**, so a leftover one keeps serving the bytes and the
 contract endpoint — with its auth gate — never runs. stitchkit warns at startup
@@ -1135,6 +1204,14 @@ createServer({ services: [users, orders], rawRoutes: [openApiRoute('/openapi.jso
 
 Only HTTP-exposed methods appear (an MCP/agent-only tool is skipped).
 
+OpenAPI 3.1 has no standard multi-segment path parameter. For a contract path
+ending in `/*`, Stitchkit keeps the literal runtime path, omits `*` from the
+standard `in: path` parameter list, and emits
+`x-stitchkit-trailing-wildcard` on the operation with its parameter name,
+schema and semantics. A generic OpenAPI client therefore cannot invent
+catch-all expansion; use Stitchkit's typed client or teach the generator that
+extension.
+
 ### Curating the spec — `includeMethod`
 
 To publish a **subset** — a public spec that advertises only some methods
@@ -1194,6 +1271,10 @@ import { createHttpClient } from 'stitchkit'
 const http = createHttpClient({ baseUrl: '/api' })
 ```
 
+The returned `ConfiguredHttpClient` keeps that `baseUrl` as a readonly public
+field. Besides executing requests, it can therefore seed contract URL builders
+without repeating transport configuration.
+
 ### `HttpClientConfig`
 
 | Field | Default | Purpose |
@@ -1239,6 +1320,8 @@ Each call takes one argument object. The client routes each field by the
 contract:
 
 - a **path param** (`:id`) is substituted into the URL,
+- a terminal wildcard (`/*`) consumes the `'*'` field and preserves its path
+  segments (`{ '*': 'a/b' }` → `/a/b`, not `/%2Fa%2Fb` or a query field),
 - for `GET` / `DELETE`, the remaining fields become the **query string**
   (arrays become repeated keys),
 - for `POST` / `PUT` / `PATCH`, they become the **JSON body**,
@@ -1258,7 +1341,53 @@ await api.posts.create({ title: 'Hi' })
 ```
 
 `createClients` builds one typed client per contract from a registry — list the
-contracts once, get the whole API typed.
+contracts once, get the whole API typed. It accepts the same optional scoped
+config as `createClient`, so a whole registry can share one resource prefix:
+
+```ts
+const tenantApi = createClients({ users, posts }, http, {
+  stripPrefixKeys: ['tenantId'],
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}`,
+})
+```
+
+Every method now requires `tenantId`, and the callback sees it as a `string`.
+The batch form delegates to the same single-contract client runtime, including
+HTTP exposure filtering, multipart, raw responses and output validation.
+
+## Contract URL builders
+
+Browser-native consumers such as `<img src>`, downloads and navigation need a
+URL, not a fetched response. `createUrlBuilder` derives those URLs from the same
+contract path planner used by both typed-client transports:
+
+```ts
+import { createUrlBuilder, createUrlBuilders } from 'stitchkit'
+
+const mediaUrls = createUrlBuilder(media, http, {
+  stripPrefixKeys: ['tenantId'],
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}`,
+})
+
+const src = mediaUrls.file({
+  tenantId: 't_123',
+  fileId: 'f_456',
+  thumbnail: true,
+})
+
+const urls = createUrlBuilders({ media, exports }, http)
+```
+
+Only HTTP-exposed, non-multipart `GET` endpoints appear on a URL builder. Raw
+response GET endpoints are included, so downloads and streams stay
+contract-driven. Path and scoped-prefix keys are consumed by the path; remaining
+GET input becomes the query string, including repeated keys for arrays.
+
+Building a URL is synchronous and performs no request, auth event, header
+resolution or output validation. A `ConfiguredHttpClient` created by
+`createHttpClient` supplies its base URL; custom transports can pass an explicit
+`{ baseUrl: 'https://api.example.com' }` instead. Relative bases produce relative
+URLs.
 
 ## `ApiError`
 
@@ -1329,7 +1458,7 @@ segment to every URL — the client half of a multi-tenant API
 interface ContractClientConfig {
   /** Prepended to every request URL. A function is called per request with the
    *  call's argument object, so the prefix can depend on the arguments. */
-  pathPrefix?: string | ((args: Record<string, unknown>) => string)
+  pathPrefix?: string | ((args: { [K in ConsumedKey]: string }) => string)
   /** Argument keys consumed by `pathPrefix` — stripped from the query/body so
    *  they are not also sent there (the endpoint's own path `:params` are
    *  stripped automatically; list any *extra* keys here). */
@@ -1341,8 +1470,8 @@ A per-tenant client — `tenantId` goes into the URL, not the body:
 
 ```ts
 const widgets = createClient(widgetsContract, http, {
-  pathPrefix: (args) => `tenants/${args.tenantId}/`,
   stripPrefixKeys: ['tenantId'],
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}/`,
 })
 
 widgets.list({ tenantId: 't_123' })            // GET  /tenants/t_123/widgets
@@ -2744,6 +2873,20 @@ session.clear()         // → a Set-Cookie value that expires it
 config is not repeated at every call site. `parseCookies(header)` and
 `serializeCookie(name, value, opts)` are the lower-level primitives.
 
+To set a cookie from a schema-validated JSON endpoint without losing its typed
+client result, declare [`responseMeta`](./server.md#typed-json-response-metadata)
+and append the generated value:
+
+```ts
+complete: async ({ response }) => {
+  response.headers.append('Set-Cookie', session.set('abc123'))
+  return authenticatedUser
+}
+```
+
+Append once per cookie; Stitchkit preserves separate `Set-Cookie` fields through
+both Bun and Node. Cookie/session policy remains application logic.
+
 ## The error model
 
 One error type, `AppError`, is shared by the contract, the server and the
@@ -3609,7 +3752,7 @@ keeps `tenantId` out of the body/query
 
 ```ts
 const widgetsApi = createClient(widgets, http, {
-  pathPrefix: (args) => `tenants/${args.tenantId}/`,
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}/`,
   stripPrefixKeys: ['tenantId'],
 })
 
@@ -3908,12 +4051,17 @@ The browser-and-server entrypoint. Re-exports everything from
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createClient` | function | build a typed client from a contract — [guide](../guide/client.md#createclient) |
-| `createClients` | function | build one typed client per contract from a registry |
+| `createClients` | function | build one exact typed client per contract from a registry; accepts the same scoped config and transports as `createClient` |
+| `createUrlBuilder` | function | build synchronous browser-native URLs for one contract's HTTP GET endpoints — [guide](../guide/client.md#contract-url-builders) |
+| `createUrlBuilders` | function | build one exact URL builder per contract in a registry |
+| `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
 | `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
 | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
+| `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
 | `createHttpClient` | function | the Ky-based HTTP transport — [guide](../guide/client.md#createhttpclient) |
 | `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` |
 | `HttpClient` | _type_ | the transport interface `createClient` builds on |
+| `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
 | `HttpClientConfig` | _type_ | config for `createHttpClient` |
 | `RequestOptions` | _type_ | per-call options — params, timeout, response type |
 | `HeaderProvider` | _type_ | static or per-request headers |
@@ -3965,6 +4113,10 @@ from the root `stitchkit`.
 | `ContractDef` | _type_ | a defined contract |
 | `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
 | `EndpointDef` | _type_ | a single endpoint definition |
+| `EndpointResponseMeta` | _type_ | static success metadata declared by an HTTP-only typed-data endpoint |
+| `ResponseMetadata` | _type_ | per-request outbound collector exposed as `ctx.response` only for a `responseMeta` endpoint |
+| `HttpSuccessStatus` | _type_ | supported declared 2xx success statuses |
+| `BodyHttpSuccessStatus` | _type_ | supported 2xx statuses excluding bodyless 204/205 |
 | `HttpMethod` | _type_ | `GET \| POST \| PUT \| PATCH \| DELETE` |
 | `Transport` | _type_ | `HTTP \| MCP \| AGENT \| CLI` |
 | `TransportSource` | _type_ | `http \| mcp \| agent \| cli` — the value of `ctx.source` |
@@ -3975,6 +4127,9 @@ from the root `stitchkit`.
 | `TypedHttpClient` | _type_ | the typed client, HTTP endpoints only (`= ScopedHttpClient<C, unknown>`) |
 | `ScopedHttpClient` | _type_ | a client whose `stripPrefixKeys` become required args ([guide](../guide/multi-tenant.md)) |
 | `ScopedEndpointFn` | _type_ | one method's signature with the consumed keys folded in |
+| `TypedUrlBuilder` | _type_ | one contract's HTTP, non-multipart GET endpoints as synchronous URL functions |
+| `ScopedUrlBuilder` | _type_ | a URL builder whose scoped-prefix keys are required method arguments |
+| `ScopedUrlFn` | _type_ | one URL method's signature with scoped-prefix keys folded in |
 | `MultipartFile` | _type_ | a `multipart` file field — `Blob \| FileDescriptor` |
 | `FileDescriptor` | _type_ | a React Native / Expo file — `{ uri, name, type }` |
 | `EndpointToolAnnotations` | _type_ | MCP behavioural hints on an endpoint (`readOnlyHint` / `destructiveHint` / `title`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",