stitchkit 0.72.5 → 0.74.0

package/dist/index.js

@@ -86,617 +86,633 @@ function cancellationError(cause) {
   return new RequestCancellationError(cause);
 }
 
-// src/browser/client-multipart.ts
-function isFileDescriptor(value) {
-  return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
-}
-function isMultipartFile(value) {
-  return value instanceof Blob || isFileDescriptor(value);
+// src/browser/http.ts
+import ky, {
+  isHTTPError,
+  isNetworkError,
+  isTimeoutError
+} from "ky";
+
+// src/internal/random-hex.ts
+function randomHex(bytes) {
+  const arr = new Uint8Array(bytes);
+  crypto.getRandomValues(arr);
+  let hex = "";
+  for (const byte of arr)
+    hex += byte.toString(16).padStart(2, "0");
+  return hex;
 }
-function appendMultipartFile(form, field, file) {
-  const sink = form;
-  sink.append(field, file);
+
+// src/observability/trace.ts
+var TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(.*)$/i;
+function createTraceContext() {
+  return { traceId: randomHex(16), spanId: randomHex(8) };
 }
-function appendFormFields(formData, values, skipKeys) {
-  for (const [key, value] of Object.entries(values)) {
-    if (skipKeys.has(key) || value === undefined || value === null)
-      continue;
-    formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+function parseTraceparent(header) {
+  if (!header)
+    return null;
+  const match = TRACEPARENT_RE.exec(header.trim());
+  if (!match?.[1] || !match[2] || !match[3] || !match[4] || match[5] === undefined)
+    return null;
+  const version = match[1].toLowerCase();
+  if (version === "ff")
+    return null;
+  const suffix = match[5];
+  if (version === "00" ? suffix !== "" : suffix !== "" && !/^(?:-[0-9a-f]{2,})+$/i.test(suffix)) {
+    return null;
   }
+  const traceId = match[2].toLowerCase();
+  const parentSpanId = match[3].toLowerCase();
+  const traceFlags = match[4].toLowerCase();
+  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
+    return null;
+  return { traceId, spanId: randomHex(8), parentSpanId, traceFlags };
 }
-function buildMultipartForm(descriptor, values) {
-  const formData = new FormData;
-  const fileFields = new Set(Object.keys(descriptor.files));
-  for (const [field, policy] of Object.entries(descriptor.files)) {
-    const value = values[field];
-    if (value === undefined) {
-      if (policy.required !== false)
-        throw new Error(`Missing multipart file field: ${field}`);
-      continue;
-    }
-    if (policy.multiple === true) {
-      if (!Array.isArray(value) || value.length === 0) {
-        throw new Error(`Multipart file field "${field}" must be a non-empty array`);
-      }
-      for (const file of value) {
-        if (!isMultipartFile(file)) {
-          throw new Error(`Invalid multipart file field: ${field}`);
-        }
-        appendMultipartFile(formData, field, file);
-      }
-      continue;
-    }
-    if (!isMultipartFile(value))
-      throw new Error(`Invalid multipart file field: ${field}`);
-    appendMultipartFile(formData, field, value);
-  }
-  appendFormFields(formData, values, fileFields);
-  return formData;
+function formatTraceparent(ctx) {
+  return `00-${ctx.traceId}-${ctx.spanId}-${ctx.traceFlags ?? "01"}`;
 }
-
-// src/internal/http-input.ts
-function inputIsQuery(method) {
-  return method === "GET" || method === "DELETE";
+function childSpan(parent) {
+  return {
+    traceId: parent.traceId,
+    spanId: randomHex(8),
+    parentSpanId: parent.spanId,
+    ...parent.tracestate !== undefined && { tracestate: parent.tracestate },
+    ...parent.baggage !== undefined && { baggage: parent.baggage },
+    ...parent.traceFlags !== undefined && { traceFlags: parent.traceFlags }
+  };
 }
+var encoder = new TextEncoder;
 
-// src/browser/client-url.ts
-function isParamArray(value) {
-  return Array.isArray(value) && value.every((item) => typeof item === "string" || typeof item === "number");
+// src/browser/request-id.ts
+var REQUEST_ID_HEADER = "x-request-id";
+function responseTraceId(response) {
+  return response?.headers.get(REQUEST_ID_HEADER) ?? undefined;
 }
-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;
+
+// src/browser/http.ts
+var API_ERROR_BRAND = Symbol.for("stitchkit.ApiError");
+function messageForCode(code, message) {
+  return message !== undefined && message.length > 0 ? message : `${code} (no message supplied)`;
 }
-function hasStringKeys(args, keys) {
-  for (const key of keys) {
-    if (typeof args[key] !== "string")
-      return false;
+
+class ApiError extends Error {
+  code;
+  status;
+  details;
+  hint;
+  traceId;
+  constructor(code, status = 0, details, message, hint, traceId, options) {
+    super(messageForCode(code, message), options);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.hint = hint;
+    this.traceId = traceId;
+    this.name = "ApiError";
+    Object.defineProperty(this, API_ERROR_BRAND, { value: true });
   }
-  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}`);
+  static is(error) {
+    return typeof error === "object" && error !== null && API_ERROR_BRAND in error;
   }
-  return config.pathPrefix(args);
 }
-function escapeRegex(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function refuseLocally(path, message) {
+  return new ApiError("VALIDATION_ERROR", 0, { issues: [{ path, code: "invalid_type", message }] }, message);
 }
-function decodePathSegment(value) {
-  try {
-    return decodeURIComponent(value);
-  } catch {
-    return value;
+function shouldRetryBunNetworkError(error) {
+  if (ApiError.is(error) || isHTTPError(error) || isNetworkError(error) || isTimeoutError(error) || error instanceof RequestCancellationError || error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError")) {
+    return;
   }
+  if (!(error instanceof Error))
+    return;
+  const code = Object.getOwnPropertyDescriptor(error, "code");
+  return code && "value" in code && code.value === "ConnectionRefused" ? true : undefined;
 }
-function createClientRouteMatcher(endpoint, contractPrefix, config) {
-  if (typeof config?.pathPrefix === "function" && (!config.stripPrefixKeys || config.stripPrefixKeys.length === 0)) {
-    throw new Error("Dynamic pathPrefix matchers require stripPrefixKeys");
-  }
-  const markerByKey = {};
-  for (const [index, key] of (config?.stripPrefixKeys ?? []).entries()) {
-    markerByKey[key] = `__stitch_scope_${index}__`;
-  }
-  const pathPrefix = resolvePathPrefix(config, markerByKey);
-  const route = [pathPrefix, contractPrefix, endpoint.path === "/" ? "" : endpoint.path].filter(Boolean).join("/");
-  const patternSegments = route.split("/").filter(Boolean);
-  const wildcard = patternSegments.at(-1)?.startsWith("*") === true;
-  const fixedCount = wildcard ? patternSegments.length - 1 : patternSegments.length;
-  const markers = Object.values(markerByKey);
-  return (pathname) => {
-    const actualSegments = pathname.split("/").filter(Boolean).map(decodePathSegment);
-    if (wildcard ? actualSegments.length < fixedCount : actualSegments.length !== fixedCount) {
-      return false;
+function parseApiErrorBody(body) {
+  if (!isRecord(body) || !isRecord(body.error))
+    return null;
+  const error = body.error;
+  if (typeof error.code !== "string")
+    return null;
+  return {
+    code: error.code,
+    message: typeof error.message === "string" ? error.message : undefined,
+    details: error.details,
+    hint: typeof error.hint === "string" ? error.hint : undefined
+  };
+}
+function createRetryAwareFetch(transportFetch, unix) {
+  const runtimeFetch = transportFetch;
+  let attempt = 0;
+  return (input, init) => {
+    attempt += 1;
+    if (unix === undefined && attempt === 1) {
+      return runtimeFetch(input, init);
     }
-    for (let index = 0;index < fixedCount; index += 1) {
-      const pattern = patternSegments[index];
-      const actual = actualSegments[index];
-      if (!pattern || actual === undefined)
-        return false;
-      if (pattern.startsWith(":"))
-        continue;
-      let source = escapeRegex(pattern);
-      for (const marker of markers) {
-        source = source.replaceAll(escapeRegex(marker), "[^/]+");
-      }
-      if (!new RegExp(`^${source}$`).test(actual))
-        return false;
+    if (!(input instanceof Request)) {
+      if (unix === undefined)
+        return runtimeFetch(input, init);
+      const unixInit = { ...init, unix };
+      return runtimeFetch(input, unixInit);
     }
-    return true;
+    const streamedBody = input.body ? { body: input.body, duplex: "half" } : {};
+    const materialized = {
+      ...init,
+      ...unix !== undefined && { unix },
+      method: input.method,
+      headers: input.headers,
+      ...streamedBody,
+      cache: input.cache,
+      credentials: input.credentials,
+      integrity: input.integrity,
+      keepalive: input.keepalive,
+      mode: input.mode,
+      redirect: input.redirect,
+      referrer: input.referrer,
+      referrerPolicy: input.referrerPolicy,
+      signal: input.signal
+    };
+    return runtimeFetch(input.url, materialized);
   };
 }
-function extractParamNames(path) {
-  const matches = path.match(/:(\w+)/g);
-  const names = matches ? matches.map((match) => match.slice(1)) : [];
-  const wildcard = parseTrailingWildcard(path);
-  if (wildcard)
-    names.push(wildcard.name);
-  return names;
-}
-function fillPathParams(path, args) {
-  const wildcard = parseTrailingWildcard(path);
-  let filled = path.replace(/:(\w+)/g, (_, key) => {
-    const value = args[key];
-    if (value === undefined || value === null) {
-      throw new Error(`Missing path param: ${key}`);
+function createHttpClient(config) {
+  if (config.fetch && config.unix) {
+    throw new TypeError("HttpClientConfig.fetch and unix are mutually exclusive");
+  }
+  if (config.unix !== undefined) {
+    if (!config.unix.startsWith("/") || config.unix.includes("\x00")) {
+      throw new TypeError("HttpClientConfig.unix must be an absolute Unix socket path");
     }
-    return encodeURIComponent(String(value));
-  });
-  if (!wildcard)
-    return filled;
-  const wildcardValue = args[wildcard.name];
-  if (wildcardValue === undefined || wildcardValue === null) {
-    throw new Error(`Missing path param: ${wildcard.name}`);
-  }
-  const remainder = String(wildcardValue).split("/").map((segment) => encodeURIComponent(segment)).join("/");
-  filled = `${filled.slice(0, -(wildcard.name.length + 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));
+    if (typeof Reflect.get(globalThis, "Bun") !== "object") {
+      throw new TypeError("HttpClientConfig.unix requires Bun; on Bun or Node use createUnixClientTransport().fetch for an explicit portable transport");
     }
   }
-  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/internal/bounded-lines.ts
-var DEFAULT_STREAM_LINE_BYTES = 1024 * 1024;
-function lineLimit(value) {
-  const resolved = value ?? DEFAULT_STREAM_LINE_BYTES;
-  if (!Number.isSafeInteger(resolved) || resolved <= 0) {
-    throw new TypeError("maxLineBytes must be a positive safe integer");
+  let ssrCookies = null;
+  let isLoggedOut = false;
+  const listeners = new Set;
+  const suppressUnauthorizedFor = config.suppressUnauthorizedFor ?? [];
+  const parseError = config.parseError ?? parseApiErrorBody;
+  function emit(event) {
+    for (const fn of listeners) {
+      try {
+        fn(event);
+      } catch {}
+    }
   }
-  return resolved;
-}
-function joinBytes(left, right) {
-  if (left.byteLength === 0)
-    return right.slice();
-  const result = new Uint8Array(left.byteLength + right.byteLength);
-  result.set(left);
-  result.set(right, left.byteLength);
-  return result;
-}
-async function* readBoundedUtf8Lines(response, maxLineBytes, requireFinalNewline = false) {
-  const reader = response.body?.getReader();
-  if (!reader)
-    return;
-  const limit = lineLimit(maxLineBytes);
-  const decoder = new TextDecoder("utf-8", { fatal: true });
-  let pending = new Uint8Array;
-  try {
-    for (;; ) {
-      const chunk = await reader.read();
-      if (chunk.done)
-        break;
-      let start = 0;
-      for (let index = 0;index < chunk.value.byteLength; index += 1) {
-        if (chunk.value[index] !== 10)
+  const client = ky.create({
+    prefix: config.baseUrl,
+    credentials: config.credentials ?? "include",
+    timeout: false,
+    retry: {
+      limit: config.retry?.limit ?? 2,
+      methods: config.retry?.methods ?? ["get"],
+      statusCodes: config.retry?.statusCodes ?? [],
+      shouldRetry: ({ error }) => shouldRetryBunNetworkError(error)
+    },
+    hooks: {
+      beforeRequest: [
+        ({ request: request2 }) => {
+          if (ssrCookies) {
+            request2.headers.set("Cookie", ssrCookies);
+          }
+          const extra = typeof config.headers === "function" ? config.headers() : config.headers;
+          if (extra) {
+            for (const [key, value] of Object.entries(extra)) {
+              request2.headers.set(key, value);
+            }
+          }
+          if (config.trace && !request2.headers.has("traceparent")) {
+            request2.headers.set("traceparent", formatTraceparent(createTraceContext()));
+          }
+        }
+      ],
+      afterResponse: [
+        async ({ request: request2, response }) => {
+          if (response.status === 401) {
+            const url = new URL(request2.url).pathname;
+            if (!isLoggedOut && !suppressUnauthorizedFor.some((matches) => matches(url))) {
+              isLoggedOut = true;
+              emit({ type: "unauthorized" });
+            }
+          }
+          if (!response.ok) {
+            const body = await response.clone().json().catch(() => null);
+            if (body) {
+              const parsed = parseError(body);
+              if (parsed) {
+                throw new ApiError(parsed.code, response.status, parsed.details, parsed.message, parsed.hint, responseTraceId(response));
+              }
+            }
+          }
+        }
+      ]
+    }
+  });
+  async function request(method, url, data, options = {}) {
+    const cancellation = createRequestCancellation(options.signal, options.timeout ?? config.timeout ?? 30000);
+    const kyOptions = {
+      fetch: createRetryAwareFetch(config.fetch ?? globalThis.fetch.bind(globalThis), config.unix),
+      timeout: false,
+      signal: cancellation.signal
+    };
+    if (options.params) {
+      const searchParams = new URLSearchParams;
+      for (const [key, value] of Object.entries(options.params)) {
+        if (value === undefined)
           continue;
-        const lineBytes = joinBytes(pending, chunk.value.slice(start, index));
-        if (lineBytes.byteLength > limit) {
-          throw new RangeError(`Stream line exceeds the ${limit} byte limit`);
+        if (Array.isArray(value)) {
+          for (const item of value)
+            searchParams.append(key, String(item));
+        } else {
+          searchParams.set(key, String(value));
         }
-        yield decoder.decode(lineBytes);
-        pending = new Uint8Array;
-        start = index + 1;
       }
-      pending = joinBytes(pending, chunk.value.slice(start));
-      if (pending.byteLength > limit) {
-        throw new RangeError(`Stream line exceeds the ${limit} byte limit`);
+      if (searchParams.size > 0) {
+        kyOptions.searchParams = searchParams;
       }
     }
-    if (pending.byteLength > 0) {
-      if (requireFinalNewline) {
-        throw new SyntaxError("Stream ended with an unterminated final line");
+    if (data instanceof FormData) {
+      kyOptions.body = data;
+    } else if (data !== undefined) {
+      kyOptions.json = data;
+    }
+    try {
+      return await cancellation.run(async () => {
+        if (options.responseType === "blob") {
+          return transportResult(await client[method](url, kyOptions).blob());
+        }
+        if (options.responseType === "response") {
+          return transportResult(await client[method](url, kyOptions));
+        }
+        const response = await client[method](url, kyOptions);
+        if (options.responseType === "void") {
+          const text = await response.text();
+          if (text.length > 0) {
+            throw new Error("Server returned data for an endpoint with no output contract");
+          }
+        }
+        if (options.responseType === "void" || response.status === 204 || response.headers.get("content-length") === "0") {
+          return transportResult(undefined);
+        }
+        return await response.json();
+      });
+    } catch (error) {
+      if (error instanceof RequestCancellationError) {
+        throw new ApiError(error.cause === "caller" ? "REQUEST_ABORTED" : "REQUEST_TIMEOUT", 0, undefined, error.message);
       }
-      yield decoder.decode(pending);
+      if (ApiError.is(error))
+        throw error;
+      emit({ type: "network_error" });
+      const response = isHTTPError(error) ? error.response : undefined;
+      const status = response?.status ?? 0;
+      const msg = error instanceof Error ? error.message : undefined;
+      throw new ApiError("UNKNOWN_ERROR", status, msg ? { message: msg } : undefined, msg, undefined, responseTraceId(response), { cause: error });
     }
-  } finally {
-    await reader.cancel().catch(() => {
-      return;
-    });
-    reader.releaseLock();
   }
+  return {
+    baseUrl: config.baseUrl,
+    get: (url, options) => request("get", url, undefined, options),
+    head: (url, options) => request("head", url, undefined, options),
+    post: (url, data, options) => request("post", url, data, options),
+    put: (url, data, options) => request("put", url, data, options),
+    patch: (url, data, options) => request("patch", url, data, options),
+    delete: (url, options) => request("delete", url, undefined, options),
+    setServerContext(cookies) {
+      ssrCookies = cookies;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    logout() {
+      isLoggedOut = true;
+      emit({ type: "logout" });
+    },
+    resetLogoutState() {
+      isLoggedOut = false;
+    }
+  };
 }
 
-// src/internal/errors.ts
-import { z } from "zod";
-function issuePath(path) {
-  return path.length > 0 ? path.map(String).join(".") : "(root)";
+// src/browser/client-multipart.ts
+function isFileDescriptor(value) {
+  return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
 }
-function zodIssues(error) {
-  return error.issues.map((issue) => ({
-    path: issuePath(issue.path),
-    code: issue.code,
-    message: issue.message
-  }));
+function isMultipartFile(value) {
+  return value instanceof Blob || isFileDescriptor(value);
 }
-
-// src/server/stream.ts
-async function* parseSSE(response, options) {
-  try {
-    for await (const rawLine of readBoundedUtf8Lines(response, options?.maxLineBytes ?? DEFAULT_STREAM_LINE_BYTES)) {
-      const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
-      if (!line.startsWith("data:"))
-        continue;
-      const data = line.slice(5).replace(/^ /, "");
-      if (data === "[DONE]")
-        return;
-      try {
-        yield JSON.parse(data);
-      } catch (error) {
-        const failure = error instanceof Error ? error : new Error(String(error));
-        if (!options?.onParseError)
-          throw failure;
-        options.onParseError(data, failure);
+function appendMultipartFile(form, field, file) {
+  const sink = form;
+  sink.append(field, file);
+}
+function appendFormFields(formData, values, skipKeys) {
+  for (const [key, value] of Object.entries(values)) {
+    if (skipKeys.has(key) || value === undefined || value === null)
+      continue;
+    formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+  }
+}
+function buildMultipartForm(descriptor, values) {
+  const formData = new FormData;
+  const fileFields = new Set(Object.keys(descriptor.files));
+  for (const [field, policy] of Object.entries(descriptor.files)) {
+    const value = values[field];
+    if (value === undefined) {
+      if (policy.required !== false) {
+        throw refuseLocally(field, `Missing multipart file field: ${field}`);
       }
+      continue;
     }
-  } catch (error) {
-    const failure = error instanceof Error ? error : new Error(String(error));
-    if (!options?.onParseError)
-      throw failure;
-    options.onParseError("", failure);
+    if (policy.multiple === true) {
+      if (!Array.isArray(value) || value.length === 0) {
+        throw refuseLocally(field, `Multipart file field "${field}" must be a non-empty array`);
+      }
+      for (const file of value) {
+        if (!isMultipartFile(file)) {
+          throw refuseLocally(field, `Invalid multipart file field: ${field}`);
+        }
+        appendMultipartFile(formData, field, file);
+      }
+      continue;
+    }
+    if (!isMultipartFile(value)) {
+      throw refuseLocally(field, `Invalid multipart file field: ${field}`);
+    }
+    appendMultipartFile(formData, field, value);
   }
+  appendFormFields(formData, values, fileFields);
+  return formData;
 }
 
-// src/browser/http.ts
-import ky, {
-  isHTTPError,
-  isNetworkError,
-  isTimeoutError
-} from "ky";
-
-// src/internal/random-hex.ts
-function randomHex(bytes) {
-  const arr = new Uint8Array(bytes);
-  crypto.getRandomValues(arr);
-  let hex = "";
-  for (const byte of arr)
-    hex += byte.toString(16).padStart(2, "0");
-  return hex;
+// src/internal/http-input.ts
+function inputIsQuery(method) {
+  return method === "GET" || method === "DELETE";
 }
 
-// src/observability/trace.ts
-var TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(.*)$/i;
-function createTraceContext() {
-  return { traceId: randomHex(16), spanId: randomHex(8) };
+// src/browser/client-url.ts
+function isParamArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" || typeof item === "number");
 }
-function parseTraceparent(header) {
-  if (!header)
-    return null;
-  const match = TRACEPARENT_RE.exec(header.trim());
-  if (!match?.[1] || !match[2] || !match[3] || !match[4] || match[5] === undefined)
-    return null;
-  const version = match[1].toLowerCase();
-  if (version === "ff")
-    return null;
-  const suffix = match[5];
-  if (version === "00" ? suffix !== "" : suffix !== "" && !/^(?:-[0-9a-f]{2,})+$/i.test(suffix)) {
-    return null;
+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 refuseLocally(key, `${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).");
   }
-  const traceId = match[2].toLowerCase();
-  const parentSpanId = match[3].toLowerCase();
-  const traceFlags = match[4].toLowerCase();
-  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
-    return null;
-  return { traceId, spanId: randomHex(8), parentSpanId, traceFlags };
+  return hasParams ? params : undefined;
 }
-function formatTraceparent(ctx) {
-  return `00-${ctx.traceId}-${ctx.spanId}-${ctx.traceFlags ?? "01"}`;
+function hasStringKeys(args, keys) {
+  for (const key of keys) {
+    if (typeof args[key] !== "string")
+      return false;
+  }
+  return true;
 }
-function childSpan(parent) {
-  return {
-    traceId: parent.traceId,
-    spanId: randomHex(8),
-    parentSpanId: parent.spanId,
-    ...parent.tracestate !== undefined && { tracestate: parent.tracestate },
-    ...parent.baggage !== undefined && { baggage: parent.baggage },
-    ...parent.traceFlags !== undefined && { traceFlags: parent.traceFlags }
-  };
+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 refuseLocally(String(missing), `Missing path prefix key: ${missing}`);
+  }
+  return config.pathPrefix(args);
 }
-var encoder = new TextEncoder;
-
-// src/browser/request-id.ts
-var REQUEST_ID_HEADER = "x-request-id";
-function responseTraceId(response) {
-  return response?.headers.get(REQUEST_ID_HEADER) ?? undefined;
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-
-// src/browser/http.ts
-var API_ERROR_BRAND = Symbol.for("stitchkit.ApiError");
-
-class ApiError extends Error {
-  code;
-  status;
-  details;
-  hint;
-  traceId;
-  constructor(code, status = 0, details, message, hint, traceId, options) {
-    super(message ?? `API Error: ${code}`, options);
-    this.code = code;
-    this.status = status;
-    this.details = details;
-    this.hint = hint;
-    this.traceId = traceId;
-    this.name = "ApiError";
-    Object.defineProperty(this, API_ERROR_BRAND, { value: true });
-  }
-  static is(error) {
-    return typeof error === "object" && error !== null && API_ERROR_BRAND in error;
+function decodePathSegment(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
   }
 }
-function shouldRetryBunNetworkError(error) {
-  if (ApiError.is(error) || isHTTPError(error) || isNetworkError(error) || isTimeoutError(error) || error instanceof RequestCancellationError || error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError")) {
-    return;
+function createClientRouteMatcher(endpoint, contractPrefix, config) {
+  if (typeof config?.pathPrefix === "function" && (!config.stripPrefixKeys || config.stripPrefixKeys.length === 0)) {
+    throw new Error("Dynamic pathPrefix matchers require stripPrefixKeys");
   }
-  if (!(error instanceof Error))
-    return;
-  const code = Object.getOwnPropertyDescriptor(error, "code");
-  return code && "value" in code && code.value === "ConnectionRefused" ? true : undefined;
-}
-function parseApiErrorBody(body) {
-  if (!isRecord(body) || !isRecord(body.error))
-    return null;
-  const error = body.error;
-  if (typeof error.code !== "string")
-    return null;
-  return {
-    code: error.code,
-    message: typeof error.message === "string" ? error.message : undefined,
-    details: error.details,
-    hint: typeof error.hint === "string" ? error.hint : undefined
-  };
-}
-function createRetryAwareFetch(transportFetch, unix) {
-  const runtimeFetch = transportFetch;
-  let attempt = 0;
-  return (input, init) => {
-    attempt += 1;
-    if (unix === undefined && attempt === 1) {
-      return runtimeFetch(input, init);
+  const markerByKey = {};
+  for (const [index, key] of (config?.stripPrefixKeys ?? []).entries()) {
+    markerByKey[key] = `__stitch_scope_${index}__`;
+  }
+  const pathPrefix = resolvePathPrefix(config, markerByKey);
+  const route = [pathPrefix, contractPrefix, endpoint.path === "/" ? "" : endpoint.path].filter(Boolean).join("/");
+  const patternSegments = route.split("/").filter(Boolean);
+  const wildcard = patternSegments.at(-1)?.startsWith("*") === true;
+  const fixedCount = wildcard ? patternSegments.length - 1 : patternSegments.length;
+  const markers = Object.values(markerByKey);
+  return (pathname) => {
+    const actualSegments = pathname.split("/").filter(Boolean).map(decodePathSegment);
+    if (wildcard ? actualSegments.length < fixedCount : actualSegments.length !== fixedCount) {
+      return false;
     }
-    if (!(input instanceof Request)) {
-      if (unix === undefined)
-        return runtimeFetch(input, init);
-      const unixInit = { ...init, unix };
-      return runtimeFetch(input, unixInit);
+    for (let index = 0;index < fixedCount; index += 1) {
+      const pattern = patternSegments[index];
+      const actual = actualSegments[index];
+      if (!pattern || actual === undefined)
+        return false;
+      if (pattern.startsWith(":"))
+        continue;
+      let source = escapeRegex(pattern);
+      for (const marker of markers) {
+        source = source.replaceAll(escapeRegex(marker), "[^/]+");
+      }
+      if (!new RegExp(`^${source}$`).test(actual))
+        return false;
     }
-    const streamedBody = input.body ? { body: input.body, duplex: "half" } : {};
-    const materialized = {
-      ...init,
-      ...unix !== undefined && { unix },
-      method: input.method,
-      headers: input.headers,
-      ...streamedBody,
-      cache: input.cache,
-      credentials: input.credentials,
-      integrity: input.integrity,
-      keepalive: input.keepalive,
-      mode: input.mode,
-      redirect: input.redirect,
-      referrer: input.referrer,
-      referrerPolicy: input.referrerPolicy,
-      signal: input.signal
-    };
-    return runtimeFetch(input.url, materialized);
+    return true;
   };
 }
-function createHttpClient(config) {
-  if (config.fetch && config.unix) {
-    throw new TypeError("HttpClientConfig.fetch and unix are mutually exclusive");
-  }
-  if (config.unix !== undefined) {
-    if (!config.unix.startsWith("/") || config.unix.includes("\x00")) {
-      throw new TypeError("HttpClientConfig.unix must be an absolute Unix socket path");
+function extractParamNames(path) {
+  const matches = path.match(/:(\w+)/g);
+  const names = matches ? matches.map((match) => match.slice(1)) : [];
+  const wildcard = parseTrailingWildcard(path);
+  if (wildcard)
+    names.push(wildcard.name);
+  return names;
+}
+function fillPathParams(path, args) {
+  const wildcard = parseTrailingWildcard(path);
+  let filled = path.replace(/:(\w+)/g, (_, key) => {
+    const value = args[key];
+    if (value === undefined || value === null) {
+      throw refuseLocally(String(key), `Missing path param: ${key}`);
     }
-    if (typeof Reflect.get(globalThis, "Bun") !== "object") {
-      throw new TypeError("HttpClientConfig.unix requires Bun; on Bun or Node use createUnixClientTransport().fetch for an explicit portable transport");
+    return encodeURIComponent(String(value));
+  });
+  if (!wildcard)
+    return filled;
+  const wildcardValue = args[wildcard.name];
+  if (wildcardValue === undefined || wildcardValue === null) {
+    throw refuseLocally(wildcard.name, `Missing path param: ${wildcard.name}`);
+  }
+  const remainder = String(wildcardValue).split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  filled = `${filled.slice(0, -(wildcard.name.length + 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));
     }
   }
-  let ssrCookies = null;
-  let isLoggedOut = false;
-  const listeners = new Set;
-  const suppressUnauthorizedFor = config.suppressUnauthorizedFor ?? [];
-  const parseError = config.parseError ?? parseApiErrorBody;
-  function emit(event) {
-    for (const fn of listeners) {
-      try {
-        fn(event);
-      } catch {}
-    }
+  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));
   }
-  const client = ky.create({
-    prefix: config.baseUrl,
-    credentials: config.credentials ?? "include",
-    timeout: false,
-    retry: {
-      limit: config.retry?.limit ?? 2,
-      methods: config.retry?.methods ?? ["get"],
-      statusCodes: config.retry?.statusCodes ?? [],
-      shouldRetry: ({ error }) => shouldRetryBunNetworkError(error)
-    },
-    hooks: {
-      beforeRequest: [
-        ({ request: request2 }) => {
-          if (ssrCookies) {
-            request2.headers.set("Cookie", ssrCookies);
-          }
-          const extra = typeof config.headers === "function" ? config.headers() : config.headers;
-          if (extra) {
-            for (const [key, value] of Object.entries(extra)) {
-              request2.headers.set(key, value);
-            }
-          }
-          if (config.trace && !request2.headers.has("traceparent")) {
-            request2.headers.set("traceparent", formatTraceparent(createTraceContext()));
-          }
-        }
-      ],
-      afterResponse: [
-        async ({ request: request2, response }) => {
-          if (response.status === 401) {
-            const url = new URL(request2.url).pathname;
-            if (!isLoggedOut && !suppressUnauthorizedFor.some((matches) => matches(url))) {
-              isLoggedOut = true;
-              emit({ type: "unauthorized" });
-            }
-          }
-          if (!response.ok) {
-            const body = await response.clone().json().catch(() => null);
-            if (body) {
-              const parsed = parseError(body);
-              if (parsed) {
-                throw new ApiError(parsed.code, response.status, parsed.details, parsed.message, parsed.hint, responseTraceId(response));
-              }
-            }
-          }
-        }
-      ]
-    }
-  });
-  async function request(method, url, data, options = {}) {
-    const cancellation = createRequestCancellation(options.signal, options.timeout ?? config.timeout ?? 30000);
-    const kyOptions = {
-      fetch: createRetryAwareFetch(config.fetch ?? globalThis.fetch.bind(globalThis), config.unix),
-      timeout: false,
-      signal: cancellation.signal
-    };
-    if (options.params) {
-      const searchParams = new URLSearchParams;
-      for (const [key, value] of Object.entries(options.params)) {
-        if (value === undefined)
+  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/internal/bounded-lines.ts
+var DEFAULT_STREAM_LINE_BYTES = 1024 * 1024;
+function lineLimit(value) {
+  const resolved = value ?? DEFAULT_STREAM_LINE_BYTES;
+  if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+    throw new TypeError("maxLineBytes must be a positive safe integer");
+  }
+  return resolved;
+}
+function joinBytes(left, right) {
+  if (left.byteLength === 0)
+    return right.slice();
+  const result = new Uint8Array(left.byteLength + right.byteLength);
+  result.set(left);
+  result.set(right, left.byteLength);
+  return result;
+}
+async function* readBoundedUtf8Lines(response, maxLineBytes, requireFinalNewline = false) {
+  const reader = response.body?.getReader();
+  if (!reader)
+    return;
+  const limit = lineLimit(maxLineBytes);
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let pending = new Uint8Array;
+  try {
+    for (;; ) {
+      const chunk = await reader.read();
+      if (chunk.done)
+        break;
+      let start = 0;
+      for (let index = 0;index < chunk.value.byteLength; index += 1) {
+        if (chunk.value[index] !== 10)
           continue;
-        if (Array.isArray(value)) {
-          for (const item of value)
-            searchParams.append(key, String(item));
-        } else {
-          searchParams.set(key, String(value));
+        const lineBytes = joinBytes(pending, chunk.value.slice(start, index));
+        if (lineBytes.byteLength > limit) {
+          throw new RangeError(`Stream line exceeds the ${limit} byte limit`);
         }
+        yield decoder.decode(lineBytes);
+        pending = new Uint8Array;
+        start = index + 1;
       }
-      if (searchParams.size > 0) {
-        kyOptions.searchParams = searchParams;
+      pending = joinBytes(pending, chunk.value.slice(start));
+      if (pending.byteLength > limit) {
+        throw new RangeError(`Stream line exceeds the ${limit} byte limit`);
       }
     }
-    if (data instanceof FormData) {
-      kyOptions.body = data;
-    } else if (data !== undefined) {
-      kyOptions.json = data;
-    }
-    try {
-      return await cancellation.run(async () => {
-        if (options.responseType === "blob") {
-          return transportResult(await client[method](url, kyOptions).blob());
-        }
-        if (options.responseType === "response") {
-          return transportResult(await client[method](url, kyOptions));
-        }
-        const response = await client[method](url, kyOptions);
-        if (options.responseType === "void") {
-          const text = await response.text();
-          if (text.length > 0) {
-            throw new Error("Server returned data for an endpoint with no output contract");
-          }
-        }
-        if (options.responseType === "void" || response.status === 204 || response.headers.get("content-length") === "0") {
-          return transportResult(undefined);
-        }
-        return await response.json();
-      });
-    } catch (error) {
-      if (error instanceof RequestCancellationError) {
-        throw new ApiError(error.cause === "caller" ? "REQUEST_ABORTED" : "REQUEST_TIMEOUT", 0, undefined, error.message);
+    if (pending.byteLength > 0) {
+      if (requireFinalNewline) {
+        throw new SyntaxError("Stream ended with an unterminated final line");
       }
-      if (ApiError.is(error))
-        throw error;
-      emit({ type: "network_error" });
-      const response = isHTTPError(error) ? error.response : undefined;
-      const status = response?.status ?? 0;
-      const msg = error instanceof Error ? error.message : undefined;
-      throw new ApiError("UNKNOWN_ERROR", status, msg ? { message: msg } : undefined, undefined, undefined, responseTraceId(response));
+      yield decoder.decode(pending);
     }
+  } finally {
+    await reader.cancel().catch(() => {
+      return;
+    });
+    reader.releaseLock();
   }
-  return {
-    baseUrl: config.baseUrl,
-    get: (url, options) => request("get", url, undefined, options),
-    head: (url, options) => request("head", url, undefined, options),
-    post: (url, data, options) => request("post", url, data, options),
-    put: (url, data, options) => request("put", url, data, options),
-    patch: (url, data, options) => request("patch", url, data, options),
-    delete: (url, options) => request("delete", url, undefined, options),
-    setServerContext(cookies) {
-      ssrCookies = cookies;
-    },
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => listeners.delete(listener);
-    },
-    logout() {
-      isLoggedOut = true;
-      emit({ type: "logout" });
-    },
-    resetLogoutState() {
-      isLoggedOut = false;
+}
+
+// src/internal/errors.ts
+import { z } from "zod";
+function issuePath(path) {
+  return path.length > 0 ? path.map(String).join(".") : "(root)";
+}
+function formatZodError(error) {
+  const issues = error.issues.slice(0, 5);
+  const lines = issues.map((issue) => `${issuePath(issue.path)}: ${issue.message}`);
+  const suffix = error.issues.length > 5 ? `
+...and ${error.issues.length - 5} more issues` : "";
+  return lines.join(`
+`) + suffix;
+}
+function zodIssues(error) {
+  return error.issues.map((issue) => ({
+    path: issuePath(issue.path),
+    code: issue.code,
+    message: issue.message
+  }));
+}
+
+// src/server/stream.ts
+async function* parseSSE(response, options) {
+  try {
+    for await (const rawLine of readBoundedUtf8Lines(response, options?.maxLineBytes ?? DEFAULT_STREAM_LINE_BYTES)) {
+      const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+      if (!line.startsWith("data:"))
+        continue;
+      const data = line.slice(5).replace(/^ /, "");
+      if (data === "[DONE]")
+        return;
+      try {
+        yield JSON.parse(data);
+      } catch (error) {
+        const failure = error instanceof Error ? error : new Error(String(error));
+        if (!options?.onParseError)
+          throw failure;
+        options.onParseError(data, failure);
+      }
     }
-  };
+  } catch (error) {
+    const failure = error instanceof Error ? error : new Error(String(error));
+    if (!options?.onParseError)
+      throw failure;
+    options.onParseError("", failure);
+  }
 }
 // src/browser/stream.ts
 function parseFailure(raw, error, onParseError) {
@@ -925,16 +941,35 @@ function setClientMethod(target, key, method) {
 function createEndpointMethod(endpoint, execute, contractConfig) {
   const hasScopedArguments = (contractConfig?.stripPrefixKeys?.length ?? 0) > 0;
   if (endpointHasArguments(endpoint) || hasScopedArguments) {
-    const method2 = (requestArgs) => execute(readClientRequestArgs(requestArgs), undefined);
+    const method2 = (requestArgs) => settle(execute, readClientRequestArgs(requestArgs), undefined);
     return Object.assign(method2, {
-      withOptions: (requestArgs, options) => execute(readClientRequestArgs(requestArgs), readClientRequestOptions(options))
+      withOptions: (...args) => {
+        refuseExtraWithOptionsArguments(endpoint, args.length, 2);
+        return settle(execute, readClientRequestArgs(args[0]), readClientRequestOptions(args[1]));
+      }
     });
   }
-  const method = () => execute({}, undefined);
+  const method = () => settle(execute, {}, undefined);
   return Object.assign(method, {
-    withOptions: (options) => execute({}, readClientRequestOptions(options))
+    withOptions: (...args) => {
+      refuseExtraWithOptionsArguments(endpoint, args.length, 1);
+      return settle(execute, {}, readClientRequestOptions(args[0]));
+    }
   });
 }
+function settle(execute, requestArgs, options) {
+  try {
+    return execute(requestArgs, options);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+function refuseExtraWithOptionsArguments(endpoint, received, expected) {
+  if (received <= expected)
+    return;
+  const shape = expected === 1 ? "withOptions(options)" : "withOptions(args, options)";
+  throw new TypeError(`${endpoint.method} ${endpoint.path}: this endpoint declares ${expected === 1 ? "no input" : "an input"}, so its method is ${shape} — it received ${received} arguments. ` + "An extra argument here is dropped, and a request options object in the dropped position " + "sends the request without them: an abort signal placed there never reaches the server.");
+}
 function createHttpExecutor(endpoint, prefix, client, config) {
   const httpMethod = endpoint.method.toLowerCase();
   return (requestArgs, options) => {
@@ -2638,6 +2673,7 @@ var RealtimeRejectReasonSchema = z7.enum([
 ]);
 var RealtimeRejectFaultSchema = z7.enum(["peer", "local"]);
 export {
+  zodIssues,
   unauthorized,
   resumableIterator,
   rateLimited,
@@ -2647,6 +2683,7 @@ export {
   paginatedSchema,
   notFound,
   isStitchErrorCode,
+  formatZodError,
   formatTraceparent,
   forbidden,
   encodeCursor,