stitchkit 0.80.1 → 0.81.0

package/dist/{index-y01f4223.js → index-2bxcmqkb.js}

@@ -1,77 +1,104 @@
 import {
-  AppError
+  AppError,
+  STITCH_ERROR_STATUS,
+  isStitchErrorCode
 } from "./index-0w9abg87.js";
 import {
   isUnsafeKey
 } from "./index-kzfs85xp.js";
 import {
-  mapObjectTypeBoundary
+  mapObjectTypeBoundary,
+  transportResult,
+  typedEntries
 } from "./index-77fekveh.js";
 
-// src/contract/define.ts
-import { z } from "zod";
-
 // src/internal/route-pattern.ts
+import { z } from "zod";
 var PARAM_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function joinRoutePath(...parts) {
   const joined = parts.filter((part) => Boolean(part)).map((part) => part.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
   return `/${joined}`;
 }
-function parseTrailingWildcard(path) {
+function parseRoutePattern(path) {
   const segments = path.split("/").filter(Boolean);
-  const paramNames = new Set;
-  let wildcard = null;
+  const parameters = [];
+  const names = new Set;
   for (const [segmentIndex, segment] of segments.entries()) {
-    if (segment.startsWith(":")) {
-      const name2 = segment.slice(1);
-      if (!PARAM_IDENTIFIER.test(name2)) {
-        throw new Error(`Invalid route parameter name "${name2}" in path "${path}"`);
-      }
-      if (paramNames.has(name2)) {
-        throw new Error(`Duplicate route parameter name "${name2}" in path "${path}"`);
-      }
-      paramNames.add(name2);
-      continue;
-    }
-    if (!segment.startsWith("*")) {
+    const marker = segment.at(0);
+    if (marker !== ":" && marker !== "*") {
       if (segment.includes("*")) {
         throw new Error(`Wildcard must occupy its own segment in path "${path}"`);
       }
       continue;
     }
     const name = segment.slice(1);
-    if (!PARAM_IDENTIFIER.test(name)) {
+    if (marker === "*" && name === "") {
       throw new Error(`Trailing wildcard in path "${path}" must be named, for example "/*filePath"`);
     }
-    if (segmentIndex !== segments.length - 1) {
+    if (!PARAM_IDENTIFIER.test(name) || isUnsafeKey(name)) {
+      const label = marker === "*" ? "wildcard" : "route parameter";
+      throw new Error(`Invalid ${label} name "${name}" in path "${path}"`);
+    }
+    if (names.has(name)) {
+      throw new Error(`Duplicate route parameter name "${name}" in path "${path}"`);
+    }
+    if (marker === "*" && segmentIndex !== segments.length - 1) {
       throw new Error(`Wildcard "*${name}" must be the final segment in path "${path}"`);
     }
-    if (wildcard) {
-      throw new Error(`Path "${path}" contains more than one wildcard`);
+    names.add(name);
+    parameters.push({
+      name,
+      kind: marker === "*" ? "wildcard" : "segment",
+      segmentIndex
+    });
+  }
+  return parameters;
+}
+function resolveRouteParamsSchema(path, schema) {
+  const parameters = parseRoutePattern(path);
+  if (parameters.length === 0)
+    return schema;
+  if (!schema) {
+    const shape = {};
+    for (const parameter of parameters)
+      shape[parameter.name] = z.string();
+    return z.object(shape);
+  }
+  const jsonSchema = z.toJSONSchema(schema, { io: "input", unrepresentable: "any" });
+  const properties = jsonSchema.properties;
+  if (!properties) {
+    throw new Error(`Route params schema for path "${path}" must be an object schema with a property per path field`);
+  }
+  for (const parameter of parameters) {
+    if (!(parameter.name in properties)) {
+      const kind = parameter.kind === "wildcard" ? "wildcard" : "path";
+      throw new Error(`Route params schema for path "${path}" is missing ${kind} field "${parameter.name}"`);
     }
-    if (paramNames.has(name)) {
-      throw new Error(`Duplicate route parameter name "${name}" in path "${path}"`);
+  }
+  const names = new Set(parameters.map((parameter) => parameter.name));
+  const required = Array.isArray(jsonSchema.required) ? jsonSchema.required : [];
+  for (const field of required) {
+    if (typeof field === "string" && !names.has(field)) {
+      throw new Error(`Route params schema for path "${path}" requires field "${field}" that the path does not carry`);
     }
-    wildcard = { name, segmentIndex };
   }
-  return wildcard;
+  return schema;
+}
+function parseTrailingWildcard(path) {
+  const wildcard = parseRoutePattern(path).find((parameter) => parameter.kind === "wildcard");
+  return wildcard ? { name: wildcard.name, segmentIndex: wildcard.segmentIndex } : null;
 }
 
 // src/contract/define.ts
 var ALL_TRANSPORTS = ["HTTP", "MCP", "AGENT", "CLI"];
 function defineContract(meta, endpoints) {
+  const materializedEndpoints = {};
+  for (const [key, endpoint] of Object.entries(endpoints)) {
+    const params = resolveRouteParamsSchema(endpoint.path, endpoint.params);
+    materializedEndpoints[key] = params === endpoint.params ? endpoint : { ...endpoint, params };
+  }
   const toolTransports = new Map;
-  for (const [key, ep] of Object.entries(endpoints)) {
-    const wildcard = parseTrailingWildcard(ep.path);
-    if (wildcard) {
-      if (!ep.params) {
-        throw new Error(`Contract "${meta.prefix}": endpoint "${key}" wildcard "${wildcard.name}" requires a params schema field`);
-      }
-      const paramsJson = z.toJSONSchema(ep.params, { io: "input" });
-      if (!paramsJson.properties || !(wildcard.name in paramsJson.properties)) {
-        throw new Error(`Contract "${meta.prefix}": endpoint "${key}" params schema is missing wildcard field "${wildcard.name}"`);
-      }
-    }
+  for (const [key, ep] of Object.entries(materializedEndpoints)) {
     if (ep.desc.trim() === "") {
       throw new Error(`Contract "${meta.prefix}": endpoint "${key}" has an empty desc`);
     }
@@ -88,6 +115,8 @@ function defineContract(meta, endpoints) {
       assertHeadEndpoint(meta.prefix, key, ep);
     if (ep.rawBody)
       assertRawBodyEndpoint(meta.prefix, key, ep);
+    if (ep.safelistedBody)
+      assertSafelistedBodyEndpoint(meta.prefix, key, ep);
     if ("responseMeta" in ep)
       assertResponseMetaEndpoint(meta.prefix, key, ep);
     if (!("toolName" in ep) || !ep.toolName)
@@ -108,7 +137,7 @@ function defineContract(meta, endpoints) {
       toolTransports.set(ep.toolName, { key, transports });
     }
   }
-  return { meta, endpoints };
+  return { meta, endpoints: materializedEndpoints };
 }
 function assertPositiveLimit(where, name, value) {
   if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
@@ -238,6 +267,17 @@ function assertRawBodyEndpoint(prefix, key, ep) {
     throw new Error(`${where} is HTTP-only — remove ${nonHttp.join(", ")} from expose`);
   }
 }
+function assertSafelistedBodyEndpoint(prefix, key, ep) {
+  const where = `Contract "${prefix}": safelistedBody endpoint "${key}"`;
+  if (ep.method !== "POST")
+    throw new Error(`${where} must use POST`);
+  if (!ep.input)
+    throw new Error(`${where} must declare an input schema`);
+  if (ep.multipart)
+    throw new Error(`${where} cannot be multipart`);
+  if ("stream" in ep && ep.stream)
+    throw new Error(`${where} cannot be a streaming response`);
+}
 function assertResponseMetaEndpoint(prefix, key, ep) {
   const where = `Contract "${prefix}": responseMeta endpoint "${key}"`;
   if (!ep.responseMeta || typeof ep.responseMeta !== "object") {
@@ -287,7 +327,7 @@ function validateDefinition(code, definition) {
     throw new Error(`[stitchkit] Error "${code}" message must be a non-empty string`);
   }
 }
-function defineErrors(source) {
+function defineErrors(source, mapping) {
   const definitions = mapObjectTypeBoundary(source, (code, definition) => {
     const name = String(code);
     validateDefinition(name, definition);
@@ -312,11 +352,55 @@ function defineErrors(source) {
   const codes = mapObjectTypeBoundary(definitions, (code) => String(code));
   Object.freeze(codes);
   const known = new Set(Object.keys(definitions));
+  for (const [code, target] of Object.entries(mapping?.map ?? {})) {
+    if (!isStitchErrorCode(code)) {
+      throw new Error(`[stitchkit] Error vocabulary contains unknown framework code "${code}"`);
+    }
+    if (typeof target !== "string" || !known.has(target)) {
+      throw new Error(`[stitchkit] Error vocabulary maps "${code}" to undeclared code "${String(target)}"`);
+    }
+    const status = STITCH_ERROR_STATUS[code];
+    if (definitions[target]?.status !== status) {
+      throw new Error(`[stitchkit] Error vocabulary maps "${code}" (${status}) to "${target}", declared with status ${String(definitions[target]?.status)}`);
+    }
+  }
+  for (const [statusText, target] of Object.entries(mapping?.fallback ?? {})) {
+    const status = Number(statusText);
+    if (!Number.isInteger(status) || status < 400 || status > 599) {
+      throw new Error(`[stitchkit] Error vocabulary fallback status "${statusText}" must be an integer from 400 to 599`);
+    }
+    if (typeof target !== "string" || !known.has(target)) {
+      throw new Error(`[stitchkit] Error vocabulary fallback ${status} names undeclared code "${String(target)}"`);
+    }
+    if (definitions[target]?.status !== status) {
+      throw new Error(`[stitchkit] Error vocabulary fallback ${status} must name a code with status ${status}`);
+    }
+  }
+  if (mapping?.exhaustive === true) {
+    for (const code of Object.keys(STITCH_ERROR_STATUS)) {
+      if (!Object.hasOwn(mapping.map, code)) {
+        throw new Error(`[stitchkit] Exhaustive error vocabulary is missing "${code}"`);
+      }
+    }
+  }
+  const codeMap = {};
+  for (const [stitchCode, status] of typedEntries(STITCH_ERROR_STATUS)) {
+    const code = mapping?.map?.[stitchCode] ?? mapping?.fallback?.[status];
+    if (code === undefined)
+      continue;
+    if (!known.has(code)) {
+      throw new Error(`[stitchkit] Error vocabulary maps "${stitchCode}" to undeclared code "${code}"`);
+    }
+    codeMap[stitchCode] = code;
+  }
+  Object.freeze(codeMap);
+  const vocabularyCodeMap = transportResult(codeMap);
   return Object.freeze({
     errors,
     codes,
     definitions,
-    isCode: (code) => known.has(code)
+    isCode: (code) => known.has(code),
+    codeMap: vocabularyCodeMap
   });
 }
 // src/contract/factory.ts
@@ -397,4 +481,4 @@ var ContractStreamFrameSchema = z4.discriminatedUnion("type", [
   }).strict(),
   z4.object({ type: z4.literal("end") }).strict()
 ]);
-export { joinRoutePath, parseTrailingWildcard, ALL_TRANSPORTS, defineContract, mergeMeta, defineErrors, createContractFactory, bytesToBase64Url, base64UrlToBytes, paginatedSchema, encodeCursor, decodeCursor, DEFAULT_CONTRACT_STREAM_FRAME_BYTES, ContractStreamFrameSchema };
+export { joinRoutePath, resolveRouteParamsSchema, parseTrailingWildcard, ALL_TRANSPORTS, defineContract, mergeMeta, defineErrors, createContractFactory, bytesToBase64Url, base64UrlToBytes, paginatedSchema, encodeCursor, decodeCursor, DEFAULT_CONTRACT_STREAM_FRAME_BYTES, ContractStreamFrameSchema };

package/dist/{index-dxesg10d.js → index-3ds42w1w.js}

@@ -3,15 +3,15 @@ import {
 } from "./index-3xnq72rz.js";
 import {
   collectToolSurface
-} from "./index-2rwwmr7v.js";
+} from "./index-s4ckmrac.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-5mtc969c.js";
+} from "./index-fwbkp2jn.js";
 import {
   isToolExecutionControlError,
   toolResultFromError
-} from "./index-758zx2ha.js";
+} from "./index-dggwnnjv.js";
 import {
   isRecord
 } from "./index-77fekveh.js";

package/dist/index-3xwxfj4z.js

@@ -0,0 +1,334 @@
+import {
+  createTraceContext,
+  formatTraceparent
+} from "./index-zcgf3gqf.js";
+import {
+  isRecord,
+  transportResult
+} from "./index-77fekveh.js";
+
+// src/browser/http.ts
+import ky, {
+  isHTTPError,
+  isNetworkError,
+  isTimeoutError
+} from "ky";
+
+// src/browser/cancellation.ts
+class RequestCancellationError extends Error {
+  cause;
+  constructor(cause) {
+    super(cause === "caller" ? "Request was aborted" : "Request timed out");
+    this.cause = cause;
+    this.name = "RequestCancellationError";
+  }
+}
+function createRequestCancellation(caller, timeoutMs) {
+  if (!caller && timeoutMs === undefined) {
+    return { signal: undefined, run: (operation) => operation() };
+  }
+  const timeoutController = timeoutMs === undefined ? undefined : new AbortController;
+  const signal = caller && timeoutController ? AbortSignal.any([caller, timeoutController.signal]) : caller ?? timeoutController?.signal;
+  let cause;
+  let timer;
+  const abortFromCaller = () => {
+    if (cause)
+      return;
+    cause = "caller";
+  };
+  if (caller?.aborted)
+    abortFromCaller();
+  else
+    caller?.addEventListener("abort", abortFromCaller, { once: true });
+  if (timeoutMs !== undefined && timeoutController) {
+    timer = setTimeout(() => {
+      if (cause)
+        return;
+      cause = "timeout";
+      timeoutController.abort(new DOMException("Request timed out", "TimeoutError"));
+    }, timeoutMs);
+  }
+  return {
+    signal,
+    async run(operation) {
+      try {
+        if (cause === "caller")
+          throw cancellationError(cause);
+        return await operation(signal);
+      } catch (error) {
+        if (cause)
+          throw cancellationError(cause);
+        throw error;
+      } finally {
+        if (timer !== undefined)
+          clearTimeout(timer);
+        caller?.removeEventListener("abort", abortFromCaller);
+      }
+    }
+  };
+}
+function cancellationError(cause) {
+  return new RequestCancellationError(cause);
+}
+
+// src/browser/request-id.ts
+var REQUEST_ID_HEADER = "x-request-id";
+function responseTraceId(response) {
+  return response?.headers.get(REQUEST_ID_HEADER) ?? 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)`;
+}
+
+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 });
+  }
+  static is(error) {
+    return typeof error === "object" && error !== null && API_ERROR_BRAND in error;
+  }
+}
+function refuseLocally(path, message) {
+  return new ApiError("VALIDATION_ERROR", 0, { issues: [{ path, code: "invalid_type", message }] }, message);
+}
+function isAbortLikeError(error) {
+  if (error instanceof RequestCancellationError)
+    return true;
+  return typeof error === "object" && error !== null && "name" in error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+function shouldRetryBunNetworkError(error) {
+  if (ApiError.is(error) || isHTTPError(error) || isNetworkError(error) || isTimeoutError(error) || isAbortLikeError(error)) {
+    return;
+  }
+  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);
+    }
+    if (!(input instanceof Request)) {
+      if (unix === undefined)
+        return runtimeFetch(input, init);
+      const unixInit = { ...init, unix };
+      return runtimeFetch(input, unixInit);
+    }
+    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 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");
+    }
+    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");
+    }
+  }
+  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 {}
+    }
+  }
+  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 (config.release) {
+            try {
+              config.release.observe(response.headers.get("x-build-id"));
+            } catch {}
+          }
+          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;
+        if (Array.isArray(value)) {
+          for (const item of value)
+            searchParams.append(key, String(item));
+        } else {
+          searchParams.set(key, String(value));
+        }
+      }
+      if (searchParams.size > 0) {
+        kyOptions.searchParams = searchParams;
+      }
+    }
+    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 (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 });
+    }
+  }
+  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;
+    }
+  };
+}
+
+export { RequestCancellationError, createRequestCancellation, responseTraceId, ApiError, refuseLocally, isAbortLikeError, parseApiErrorBody, createHttpClient };

package/dist/{index-egaabxkz.js → index-5z8tezpx.js}

@@ -1,10 +1,10 @@
 import {
   collectTools,
   createToolRunner
-} from "./index-5mtc969c.js";
+} from "./index-fwbkp2jn.js";
 import {
   toolErrorFromResult
-} from "./index-758zx2ha.js";
+} from "./index-dggwnnjv.js";
 import {
   assertUniqueToolName
 } from "./index-mgtxfe6b.js";