stitchkit 0.18.0 → 0.19.0

package/dist/index.js

@@ -5,8 +5,10 @@ import {
   appError,
   badRequest,
   conflict,
+  createContractFactory,
   decodeCursor,
   defineContract,
+  defineErrors,
   encodeCursor,
   forbidden,
   isStitchErrorCode,
@@ -14,30 +16,18 @@ import {
   paginatedSchema,
   rateLimited,
   unauthorized
-} from "./index-yzac2zbh.js";
+} from "./index-x62gnfsk.js";
+import {
+  isRecord,
+  mapObject,
+  typedEntries
+} from "./index-809wc1tt.js";
 
 // src/internal/http-input.ts
 function inputIsQuery(method) {
   return method === "GET" || method === "DELETE";
 }
 
-// src/internal/typed.ts
-function typedEntries(value) {
-  return Object.entries(value);
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function mapObject(source, mapper) {
-  const result = {};
-  for (const [key, value] of typedEntries(source)) {
-    const mapped = mapper(key, value);
-    if (mapped !== undefined)
-      result[key] = mapped;
-  }
-  return result;
-}
-
 // src/browser/http.ts
 import ky, { isHTTPError } from "ky";
 
@@ -244,6 +234,12 @@ function withTimeout(options, timeout) {
     return options;
   return { ...options, timeout };
 }
+function withOutput(endpoint, result) {
+  const schema = endpoint.output;
+  if (!schema)
+    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");
 }
@@ -310,18 +306,21 @@ function createHttpMethod(endpoint, prefix, client, config) {
       if (!isMultipartFile(file)) {
         throw new Error(`Missing multipart file field: ${endpoint.multipart}`);
       }
+      if (httpMethod === "get" || httpMethod === "delete") {
+        throw new Error(`Multipart endpoint ${endpoint.method} ${endpoint.path} must be POST / PUT / PATCH`);
+      }
       const formData = new FormData;
       appendMultipartFile(formData, endpoint.multipart, file);
       appendFormFields(formData, firstArg, new Set([...prefixKeys, endpoint.multipart]));
-      return client.post(url, formData, withTimeout(undefined, endpoint.timeout));
+      return withOutput(endpoint, client[httpMethod](url, formData, withTimeout(undefined, endpoint.timeout)));
     }
     if (isGet) {
       const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return client.get(url, withTimeout(params ? { params } : undefined, endpoint.timeout));
+      return withOutput(endpoint, client.get(url, withTimeout(params ? { params } : undefined, endpoint.timeout)));
     }
     if (httpMethod === "delete") {
       const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return client.delete(url, withTimeout(params ? { params } : undefined, endpoint.timeout));
+      return withOutput(endpoint, client.delete(url, withTimeout(params ? { params } : undefined, endpoint.timeout)));
     }
     const payload = {};
     for (const [key, value] of Object.entries(firstArg)) {
@@ -329,7 +328,7 @@ function createHttpMethod(endpoint, prefix, client, config) {
         payload[key] = value;
       }
     }
-    return client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint.timeout));
+    return withOutput(endpoint, client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint.timeout)));
   };
 }
 function createFetchMethod(endpoint, prefix, config, contractConfig) {
@@ -346,6 +345,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       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) {
@@ -378,7 +378,8 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
         method: endpoint.method,
         headers,
         credentials: config.credentials,
-        body: formData
+        body: formData,
+        signal
       });
       if (!res2.ok) {
         await throwForErrorResponse(res2, config, null);
@@ -392,6 +393,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       method: endpoint.method,
       headers,
       credentials: config.credentials,
+      signal,
       ...hasBody && {
         body: JSON.stringify(stripParams(hasBody, endpoint.path, prefixKeys))
       }
@@ -461,9 +463,6 @@ function stripParams(args, path, extra) {
   }
   return result;
 }
-// src/browser/socket-io.ts
-import { io } from "socket.io-client";
-
 // src/retained.ts
 function createRetainedTopics() {
   const last = {};
@@ -491,6 +490,17 @@ function createRetainedTopics() {
 }
 
 // src/browser/socket-io.ts
+var SOCKET_IO_CLIENT = "socket.io-client";
+var ioLoader = null;
+function loadIo() {
+  if (!ioLoader) {
+    ioLoader = import(SOCKET_IO_CLIENT).then((mod) => mod.io, (cause) => {
+      ioLoader = null;
+      throw new Error('stitchkit: createSocketIOClient needs the "socket.io-client" peer — install it (e.g. `bun add socket.io-client`).', { cause });
+    });
+  }
+  return ioLoader;
+}
 function toIoAuth(auth) {
   if (typeof auth !== "function")
     return auth;
@@ -500,6 +510,7 @@ function toIoAuth(auth) {
 }
 function createSocketIOClient(config) {
   let socket = null;
+  let desiredConnected = false;
   let reconnectTimer = null;
   const serverDisconnectDelay = config.reconnectOnServerDisconnect ?? 1000;
   const connectionListeners = new Set;
@@ -517,50 +528,57 @@ function createSocketIOClient(config) {
       reconnectTimer = null;
     }
   }
+  function openSocket(io) {
+    if (!desiredConnected || socket)
+      return;
+    socket = io(config.url, {
+      path: config.path ?? "/socket.io/",
+      withCredentials: config.withCredentials ?? true,
+      auth: toIoAuth(config.auth),
+      ...config.query && { query: config.query },
+      ...config.extraHeaders && { extraHeaders: config.extraHeaders },
+      transports: config.transports ?? ["websocket", "polling"],
+      autoConnect: false,
+      reconnection: true,
+      reconnectionAttempts: config.reconnectionAttempts ?? Infinity,
+      reconnectionDelay: config.reconnectionDelay ?? 1000,
+      reconnectionDelayMax: config.reconnectionDelayMax ?? 5000,
+      timeout: config.timeout ?? 20000
+    });
+    socket.on("connect", () => notifyConnection(true));
+    socket.on("disconnect", (reason) => {
+      notifyConnection(false, reason);
+      if (reason === "io server disconnect" && serverDisconnectDelay !== false) {
+        const current = socket;
+        clearReconnectTimer();
+        reconnectTimer = setTimeout(() => {
+          reconnectTimer = null;
+          if (socket === current && current && !current.connected)
+            current.connect();
+        }, serverDisconnectDelay);
+      }
+    });
+    if (retained) {
+      for (const name of retainNames) {
+        socket.on(name, (payload) => retained.record(name, payload));
+      }
+    }
+    for (const attach of subscriptions)
+      attach(socket);
+    socket.connect();
+  }
   return {
     get connected() {
       return socket?.connected ?? false;
     },
     connect() {
-      if (socket)
+      if (socket || desiredConnected)
         return;
-      socket = io(config.url, {
-        path: config.path ?? "/socket.io/",
-        withCredentials: config.withCredentials ?? true,
-        auth: toIoAuth(config.auth),
-        ...config.query && { query: config.query },
-        ...config.extraHeaders && { extraHeaders: config.extraHeaders },
-        transports: config.transports ?? ["websocket", "polling"],
-        autoConnect: false,
-        reconnection: true,
-        reconnectionAttempts: config.reconnectionAttempts ?? Infinity,
-        reconnectionDelay: config.reconnectionDelay ?? 1000,
-        reconnectionDelayMax: config.reconnectionDelayMax ?? 5000,
-        timeout: config.timeout ?? 20000
-      });
-      socket.on("connect", () => notifyConnection(true));
-      socket.on("disconnect", (reason) => {
-        notifyConnection(false, reason);
-        if (reason === "io server disconnect" && serverDisconnectDelay !== false) {
-          const current = socket;
-          clearReconnectTimer();
-          reconnectTimer = setTimeout(() => {
-            reconnectTimer = null;
-            if (socket === current && current && !current.connected)
-              current.connect();
-          }, serverDisconnectDelay);
-        }
-      });
-      if (retained) {
-        for (const name of retainNames) {
-          socket.on(name, (payload) => retained.record(name, payload));
-        }
-      }
-      for (const attach of subscriptions)
-        attach(socket);
-      socket.connect();
+      desiredConnected = true;
+      loadIo().then(openSocket);
     },
     disconnect() {
+      desiredConnected = false;
       clearReconnectTimer();
       if (!socket)
         return;
@@ -648,12 +666,14 @@ export {
   formatTraceparent,
   forbidden,
   encodeCursor,
+  defineErrors,
   defineContract,
   decodeCursor,
   createTraceContext,
   createSocketIOClient,
   createRetainedTopics,
   createHttpClient,
+  createContractFactory,
   createClients,
   createClient,
   conflict,

package/dist/internal/base64url.d.ts

@@ -0,0 +1,16 @@
+/**
+ * base64url over raw bytes — the one codec shared by cursor pagination, JWT
+ * segments, OAuth-token minting and PKCE. `btoa`/`atob` based (not Node
+ * `Buffer`), so it works identically in the server, the browser and the typed
+ * client. Kept byte-level: string callers compose with `TextEncoder` /
+ * `TextDecoder` themselves (pagination round-trips UTF-8; JWT/PKCE are binary).
+ */
+/** Encode raw bytes as an unpadded base64url string. */
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+/**
+ * Decode a base64url string to bytes. A character outside the alphabet, or a
+ * length that no base64 string can have (`% 4 === 1`), is malformed — reject it
+ * before `atob` rather than emit silent garbage.
+ */
+export declare function base64UrlToBytes(segment: string): Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=base64url.d.ts.map

package/dist/internal/base64url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64url.d.ts","sourceRoot":"","sources":["../../src/internal/base64url.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAI1D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAOzE"}

package/dist/node.js

@@ -3,7 +3,8 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-6qv1fxqy.js";
+} from "./index-wpbn133x.js";
+import"./index-tje0q6gp.js";
 import {
   AppError,
   appError,
@@ -13,10 +14,10 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "./index-ktn76xz0.js";
-import"./index-dz2k8d5h.js";
+} from "./index-ng2v2ts4.js";
+import"./index-dzx781tm.js";
 import"./index-khwedj16.js";
-import"./index-tm7dqzxc.js";
+import"./index-c7nyw0yt.js";
 // src/server/node.ts
 import { serve } from "srvx";
 async function serveNode(config) {

package/dist/observability/index.js

@@ -8,7 +8,7 @@ import {
   setRequestError,
   setRequestUser,
   wrapInRequestContext
-} from "../index-dz2k8d5h.js";
+} from "../index-dzx781tm.js";
 import {
   childSpan,
   createTraceContext,
@@ -19,7 +19,7 @@ import {
 import {
   isRecord,
   isUnsafeKey
-} from "../index-tm7dqzxc.js";
+} from "../index-c7nyw0yt.js";
 
 // src/observability/sanitize.ts
 var DEFAULT_SENSITIVE_KEYS = /(password|passwd|pwd|secret|token|apikey|api[-_ ]?key|auth|authorization|bearer|session|cookie|init[-_ ]?data|credential|private[-_ ]?key)/i;

package/dist/react/entity-cache.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Declarative CRUD cache handlers for `createCacheBridge` — the created /
+ * updated / deleted socket events of one entity, patched into its list and
+ * detail queries. Every project hand-rolls this same updater; this builds it
+ * from a small config.
+ *
+ * It patches stitchkit's own `Paginated<T>` list envelope (plain or a TanStack
+ * `InfiniteData` of it) and the entity's detail query. It does **not** flatten
+ * pages or expose a `useAllX` surface — flattening stays in the component (a
+ * deliberate boundary): this only keeps the cache correct.
+ *
+ * ```ts
+ * const handlers = createEntityCacheHandlers<Widget>({
+ *   getId: (w) => w.id,
+ *   listKey: ['widgets'],
+ *   detailKey: (id) => ['widgets', id],
+ * });
+ * createCacheBridge({ socket, queryClient, handlers: {
+ *   widgetCreated: handlers.created,
+ *   widgetUpdated: handlers.updated,
+ *   widgetDeleted: handlers.deleted,
+ * }});
+ * ```
+ */
+import type { QueryKey } from '@tanstack/react-query';
+import type { CacheBridgeHandler } from './cache-bridge';
+/** The `deleted` event may carry the whole entity or just its id. */
+export type DeletedPayload<T> = T | {
+    id: string;
+};
+/** Config for `createEntityCacheHandlers`. */
+export interface EntityCacheConfig<T> {
+    /** Read the entity's id — the identity used to match, replace and remove. */
+    getId: (entity: T) => string;
+    /** Read the id from a `deleted` payload (entity or `{ id }`). Default `getId` / `.id`. */
+    getDeletedId?: (payload: DeletedPayload<T>) => string;
+    /** Query key (or prefix) of the list(s) to patch — matched by partial equality. */
+    listKey: QueryKey;
+    /** Build the detail query key for an id. Omit to skip detail-cache updates. */
+    detailKey?: (id: string) => QueryKey;
+}
+/** The three handlers to wire onto a `createCacheBridge` `handlers` map. */
+export interface EntityCacheHandlers<T> {
+    created: CacheBridgeHandler<T>;
+    updated: CacheBridgeHandler<T>;
+    deleted: CacheBridgeHandler<DeletedPayload<T>>;
+}
+/**
+ * Build created / updated / deleted cache handlers for one entity. Each skips a
+ * stale socket echo of a change the client just made (`ctx.isFresh`), keyed on
+ * the entity's detail key when available, else the list key.
+ */
+export declare function createEntityCacheHandlers<T>(config: EntityCacheConfig<T>): EntityCacheHandlers<T>;
+//# sourceMappingURL=entity-cache.d.ts.map

package/dist/react/entity-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-cache.d.ts","sourceRoot":"","sources":["../../src/react/entity-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGpE,OAAO,KAAK,EAAsB,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAK7E,qEAAqE;AACrE,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,6EAA6E;IAC7E,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IAC7B,0FAA0F;IAC1F,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IACtD,mFAAmF;IACnF,OAAO,EAAE,QAAQ,CAAC;IAClB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,QAAQ,CAAC;CACtC;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;CAChD;AAyBD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EACzC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC3B,mBAAmB,CAAC,CAAC,CAAC,CAuCxB"}

package/dist/react.d.ts

@@ -1,3 +1,4 @@
 export { type CacheBridge, type CacheBridgeConfig, type CacheBridgeContext, type CacheBridgeHandler, type CacheBridgeHandlers, type CacheBridgeSocket, createCacheBridge, } from './react/cache-bridge';
 export { type CursorQueryConfig, createCursorQuery } from './react/cursor-query';
+export { createEntityCacheHandlers, type DeletedPayload, type EntityCacheConfig, type EntityCacheHandlers, } from './react/entity-cache';
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EACL,yBAAyB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAC"}

package/dist/react.js

@@ -1,3 +1,7 @@
+import {
+  isRecord
+} from "./index-809wc1tt.js";
+
 // src/react/cache-bridge.ts
 function createCacheBridge(config) {
   const freshWindow = config.freshWindow ?? 500;
@@ -46,7 +50,77 @@ function createCursorQuery(config) {
     getNextPageParam: (lastPage) => lastPage.nextCursor
   });
 }
+// src/react/entity-cache.ts
+function patchItems(data, fn) {
+  if (!data)
+    return data;
+  if ("pages" in data) {
+    return { ...data, pages: data.pages.map((page) => ({ ...page, items: fn(page.items) })) };
+  }
+  return { ...data, items: fn(data.items) };
+}
+function prepend(data, entity) {
+  if (!data)
+    return data;
+  if ("pages" in data) {
+    const [first, ...rest] = data.pages;
+    if (!first)
+      return data;
+    return { ...data, pages: [{ ...first, items: [entity, ...first.items] }, ...rest] };
+  }
+  return { ...data, items: [entity, ...data.items] };
+}
+function createEntityCacheHandlers(config) {
+  const { getId, listKey, detailKey } = config;
+  const deletedId = config.getDeletedId ?? ((payload) => idOf(payload, getId));
+  const freshKey = (id) => detailKey ? detailKey(id) : listKey;
+  const patchList = (ctx, fn) => {
+    ctx.queryClient.setQueriesData({ queryKey: listKey }, (old) => patchItems(old, fn));
+  };
+  return {
+    created(entity, ctx) {
+      const id = getId(entity);
+      if (ctx.isFresh(freshKey(id)))
+        return;
+      ctx.queryClient.setQueriesData({ queryKey: listKey }, (old) => {
+        const present = hasId(old, getId, id);
+        return present ? old : prepend(old, entity);
+      });
+      if (detailKey)
+        ctx.queryClient.setQueryData(detailKey(id), entity);
+    },
+    updated(entity, ctx) {
+      const id = getId(entity);
+      if (ctx.isFresh(freshKey(id)))
+        return;
+      patchList(ctx, (items) => items.map((item) => getId(item) === id ? entity : item));
+      if (detailKey)
+        ctx.queryClient.setQueryData(detailKey(id), entity);
+    },
+    deleted(payload, ctx) {
+      const id = deletedId(payload);
+      if (ctx.isFresh(freshKey(id)))
+        return;
+      patchList(ctx, (items) => items.filter((item) => getId(item) !== id));
+      if (detailKey)
+        ctx.queryClient.removeQueries({ queryKey: detailKey(id) });
+    }
+  };
+}
+function hasStringId(value) {
+  return isRecord(value) && typeof value.id === "string";
+}
+function idOf(payload, getId) {
+  return hasStringId(payload) ? payload.id : getId(payload);
+}
+function hasId(data, getId, id) {
+  if (!data)
+    return false;
+  const pages = "pages" in data ? data.pages : [data];
+  return pages.some((page) => page.items.some((item) => getId(item) === id));
+}
 export {
+  createEntityCacheHandlers,
   createCursorQuery,
   createCacheBridge
 };

package/dist/server/create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAEV,eAAe,EACf,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAyNxF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAsBnD"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAEV,eAAe,EACf,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA8NxF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAsBnD"}

package/dist/server/error-hook.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A framework for the `onError` hook — the project supplies a code map and an
+ * envelope shape, `createErrorHook` does the normalisation.
+ *
+ * Every project writes the same `onError`: turn a thrown value into one wire
+ * shape, mapping stitchkit's own error codes to the app's public codes. The
+ * exhaustive `codeMap` (`satisfies Record<StitchErrorCode, …>`) is the point —
+ * a new `StitchErrorCode` in an upgrade breaks the map at compile time instead
+ * of leaking stitchkit's code to the wire. The envelope stays app-owned via
+ * `render`, so the core prescribes no domain shape (ADR 0002).
+ *
+ * ```ts
+ * const onError = createErrorHook({
+ *   codeMap: {
+ *     BAD_REQUEST: 'bad_request', VALIDATION_ERROR: 'bad_request',
+ *     UNAUTHORIZED: 'unauthenticated', FORBIDDEN: 'forbidden',
+ *     NOT_FOUND: 'not_found', METHOD_NOT_ALLOWED: 'not_found',
+ *     CONFLICT: 'conflict', RATE_LIMITED: 'rate_limited',
+ *     INTERNAL_SERVER_ERROR: 'internal',
+ *   } satisfies Record<StitchErrorCode, string>,
+ *   render: (info) => ({ ok: false, error: { code: info.code, message: info.message } }),
+ * });
+ * createServer({ services, hooks: { onError } });
+ * ```
+ */
+import { type StitchErrorCode } from '../contract';
+import type { LifecycleHooks } from './types';
+/** The normalised error handed to `render` — code already remapped. */
+export interface ResolvedError {
+    /** Wire code — the app code from `codeMap` for a stitch error, else the thrown code. */
+    code: string;
+    /** HTTP status. */
+    status: number;
+    /** Safe message — the `AppError` message, or a generic string for a raw throw. */
+    message: string;
+    /** Structured details, when the thrown `AppError` carried them. */
+    details?: Record<string, unknown>;
+    /** Recovery hint, when the thrown `AppError` carried one. */
+    hint?: string;
+}
+/** Config for `createErrorHook`. */
+export interface ErrorHookConfig<TWireCode extends string = string> {
+    /**
+     * Remap stitchkit's own error codes to your public wire codes. Exhaustive —
+     * `satisfies Record<StitchErrorCode, …>` makes a new framework code a compile
+     * error here. Codes you threw yourself (not stitchkit's) pass through as-is.
+     */
+    codeMap?: Record<StitchErrorCode, TWireCode>;
+    /** Build the response body from the resolved error. */
+    render: (info: ResolvedError) => unknown;
+    /** Observe the raw thrown value before rendering — logging / metrics. */
+    onError?: (error: unknown, info: ResolvedError) => void;
+}
+/** Build an `onError` hook from a code map + envelope renderer. */
+export declare function createErrorHook<TWireCode extends string = string>(config: ErrorHookConfig<TWireCode>): NonNullable<LifecycleHooks['onError']>;
+//# sourceMappingURL=error-hook.d.ts.map

package/dist/server/error-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-hook.d.ts","sourceRoot":"","sources":["../../src/server/error-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IAChE;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IAC7C,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC;IACzC,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CACzD;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,EAC/D,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAoBxC"}

package/dist/server/index.d.ts

@@ -1,12 +1,13 @@
 export { AppError, appError, badRequest, conflict, forbidden, isStitchErrorCode, notFound, rateLimited, STITCH_ERROR_STATUS, type StitchErrorCode, unauthorized, } from '../contract';
 export { cacheHeaders, createCache } from './cache';
 export { createHandler, createServer } from './create';
+export { createErrorHook, type ErrorHookConfig, type ResolvedError, } from './error-hook';
 export { createEventBus, type EventBus } from './event-bus';
 export { type ByteRange, parseByteRange, type ServeFileOptions, serveFile, weakETag, } from './file';
 export { createImplement, implement } from './implement';
 export { type AuthHook, type AuthHookConfig, type AuthRule, type BearerResolverConfig, createAuthHook, createBearerResolver, extractToken, type JwtPayload, type SignJwtOptions, signJwt, verifyJwt, } from './middleware/auth';
 export { type CookieDef, type CookieOptions, defineCookie, parseCookies, serializeCookie, } from './middleware/cookies';
-export { type CorsConfig, corsHeaders, corsPreflightResponse, } from './middleware/cors';
+export { type CorsConfig, corsHeaders, corsPreflightResponse, DEFAULT_CORS_ALLOW_HEADERS, } from './middleware/cors';
 export { deriveCodeChallenge, type PkceMethod, verifyPkce } from './middleware/pkce';
 export { parseMultipart } from './multipart';
 export { generateOpenApiDocument, type OpenApiConfig, type OpenApiDocument, type OpenApiInfo, type OpenApiServer, openApiRoute, } from './openapi';

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,KAAK,SAAS,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,QAAQ,EACR,cAAc,EACd,SAAS,EACT,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,KAAK,SAAS,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,QAAQ,EACR,cAAc,EACd,SAAS,EACT,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/server/index.js

@@ -1,7 +1,5 @@
 import {
   composeWebSocketHandlers,
-  corsHeaders,
-  corsPreflightResponse,
   createHandler,
   createImplement,
   createServer,
@@ -12,7 +10,7 @@ import {
   socketIoLane,
   staticRoute,
   webSocketLane
-} from "../index-6qv1fxqy.js";
+} from "../index-wpbn133x.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -25,7 +23,12 @@ import {
   signJwt,
   verifyJwt,
   verifyPkce
-} from "../index-yv93m4yr.js";
+} from "../index-ynnh9x6h.js";
+import {
+  DEFAULT_CORS_ALLOW_HEADERS,
+  corsHeaders,
+  corsPreflightResponse
+} from "../index-tje0q6gp.js";
 import {
   jsonSchemaFields,
   toJsonSchema
@@ -42,7 +45,7 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "../index-ktn76xz0.js";
+} from "../index-ng2v2ts4.js";
 import {
   extractIp,
   generateTraceId,
@@ -50,11 +53,11 @@ import {
   getTraceId,
   resolveSocketIp,
   resolveTraceId
-} from "../index-dz2k8d5h.js";
+} from "../index-dzx781tm.js";
 import"../index-khwedj16.js";
 import {
   isRecord
-} from "../index-tm7dqzxc.js";
+} from "../index-c7nyw0yt.js";
 // src/server/swept-map.ts
 function createSweptMap(options) {
   const store = new Map;
@@ -112,6 +115,26 @@ function cacheHeaders(maxAge, scope = "public") {
     "Cache-Control": `${scope}, max-age=${maxAge}`
   };
 }
+// src/server/error-hook.ts
+function createErrorHook(config) {
+  return (_ctx, error) => {
+    const isApp = AppError.is(error);
+    const rawCode = isApp ? error.code : "INTERNAL_SERVER_ERROR";
+    const code = config.codeMap && isStitchErrorCode(rawCode) ? config.codeMap[rawCode] : rawCode;
+    const info = {
+      code,
+      status: isApp ? error.status : 500,
+      message: isApp ? error.message : "Internal server error",
+      details: isApp ? error.details : undefined,
+      hint: isApp ? error.hint : undefined
+    };
+    config.onError?.(error, info);
+    return new Response(JSON.stringify(config.render(info)), {
+      status: info.status,
+      headers: { "content-type": "application/json" }
+    });
+  };
+}
 // src/server/event-bus.ts
 function createEventBus(options = {}) {
   const subscriptions = new Map;
@@ -633,6 +656,7 @@ export {
   createImplement,
   createHandler,
   createEventBus,
+  createErrorHook,
   createCache,
   createBearerResolver,
   createAuthHook,
@@ -644,5 +668,6 @@ export {
   badRequest,
   appError,
   STITCH_ERROR_STATUS,
+  DEFAULT_CORS_ALLOW_HEADERS,
   AppError
 };