stitchkit 0.38.0 → 0.39.0

package/dist/{index-x4wbc8sz.js → index-xax049k6.js}

@@ -2,11 +2,66 @@ import {
   mapObject
 } from "./index-809wc1tt.js";
 
+// src/contract/define.ts
+import { z } from "zod";
+
+// src/internal/route-pattern.ts
+var PARAM_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function parseTrailingWildcard(path) {
+  const segments = path.split("/").filter(Boolean);
+  const paramNames = new Set;
+  let wildcard = null;
+  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("*")) {
+      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)) {
+      throw new Error(`Trailing wildcard in path "${path}" must be named, for example "/*filePath"`);
+    }
+    if (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`);
+    }
+    if (paramNames.has(name)) {
+      throw new Error(`Duplicate route parameter name "${name}" in path "${path}"`);
+    }
+    wildcard = { name, segmentIndex };
+  }
+  return wildcard;
+}
+
 // src/contract/define.ts
 var ALL_TRANSPORTS = ["HTTP", "MCP", "AGENT", "CLI"];
 function defineContract(meta, endpoints) {
   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}"`);
+      }
+    }
     if (ep.desc.trim() === "") {
       throw new Error(`Contract "${meta.prefix}": endpoint "${key}" has an empty desc`);
     }
@@ -15,6 +70,8 @@ function defineContract(meta, endpoints) {
     }
     if (ep.rawResponse)
       assertRawEndpoint(meta.prefix, key, ep);
+    if (ep.method === "HEAD")
+      assertHeadEndpoint(meta.prefix, key, ep);
     if (ep.rawBody)
       assertRawBodyEndpoint(meta.prefix, key, ep);
     if ("responseMeta" in ep)
@@ -55,6 +112,17 @@ function assertRawEndpoint(prefix, key, ep) {
     throw new Error(`${where} is HTTP-only — remove ${nonHttp.join(", ")} from expose`);
   }
 }
+function assertHeadEndpoint(prefix, key, ep) {
+  const where = `Contract "${prefix}": HEAD endpoint "${key}"`;
+  if (!ep.rawResponse)
+    throw new Error(`${where} must declare rawResponse: true`);
+  if (ep.input)
+    throw new Error(`${where} cannot declare an input schema`);
+  if (ep.multipart)
+    throw new Error(`${where} cannot be multipart`);
+  if (ep.rawBody)
+    throw new Error(`${where} cannot retain a raw body`);
+}
 function assertRawBodyEndpoint(prefix, key, ep) {
   const where = `Contract "${prefix}": rawBody endpoint "${key}"`;
   if (!ep.input)
@@ -194,7 +262,7 @@ function createContractFactory() {
   };
 }
 // src/contract/pagination.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/internal/base64url.ts
 function bytesToBase64Url(bytes) {
@@ -214,9 +282,9 @@ function base64UrlToBytes(segment) {
 
 // src/contract/pagination.ts
 function paginatedSchema(itemSchema) {
-  return z.object({
-    items: z.array(itemSchema),
-    nextCursor: z.string().nullable()
+  return z2.object({
+    items: z2.array(itemSchema),
+    nextCursor: z2.string().nullable()
   });
 }
 function toBase64Url(str) {
@@ -238,4 +306,4 @@ function decodeCursor(cursor, schema) {
     return null;
   }
 }
-export { ALL_TRANSPORTS, defineContract, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, defineErrors, createContractFactory, paginatedSchema, encodeCursor, decodeCursor };
+export { parseTrailingWildcard, ALL_TRANSPORTS, defineContract, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, defineErrors, createContractFactory, paginatedSchema, encodeCursor, decodeCursor };

package/dist/{index-n5t4gnfz.js → index-y5scd1cr.js}

@@ -14,7 +14,7 @@ import {
   runWithRequestContext,
   safeJsonParse,
   validateHandlerOutput
-} from "./index-mzx0an0s.js";
+} from "./index-fyfk537k.js";
 
 // src/tools/coerce.ts
 import { z } from "zod";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { type ClientConfig, type ContractClientConfig, createClient, createClients, createUrlBuilder, createUrlBuilders, type PathPrefixArgs, type UrlBuilderConfig, } from './browser/client';
-export { ApiError, type ApiEvent, type ApiEventListener, type ConfiguredHttpClient, createHttpClient, type HeaderProvider, type HttpClient, type HttpClientConfig, type RequestOptions, } from './browser/http';
+export { type ClientConfig, type ClientContract, type ClientRegistryValue, type ContractClientConfig, contractEndpointMatchers, createClient, createClients, createScopedClients, createUrlBuilder, createUrlBuilders, type PathPrefixArgs, type RegistryScope, type ScopeClientConfigs, type ScopedClientRegistry, type UrlBuilderConfig, } from './browser/client';
+export { ApiError, type ApiEvent, type ApiEventListener, type ConfiguredHttpClient, createHttpClient, type HeaderProvider, type HttpClient, type HttpClientConfig, type RequestOptions, type UnauthorizedMatcher, } from './browser/http';
 export type { SocketEventMap, SocketIOClient, SocketIOClientConfig, } from './browser/socket-io';
 export { createSocketIOClient } from './browser/socket-io';
 export { type ParseSSEOptions, parseSSE } from './browser/stream';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAClE,cAAc,YAAY,CAAC;AAG3B,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAClE,cAAc,YAAY,CAAC;AAG3B,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -14,9 +14,10 @@ import {
   isStitchErrorCode,
   notFound,
   paginatedSchema,
+  parseTrailingWildcard,
   rateLimited,
   unauthorized
-} from "./index-x4wbc8sz.js";
+} from "./index-xax049k6.js";
 import {
   isRecord,
   mapObject,
@@ -86,14 +87,62 @@ function resolvePathPrefix(config, args) {
   }
   return config.pathPrefix(args);
 }
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function decodePathSegment(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+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;
+    }
+    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;
+    }
+    return true;
+  };
+}
 function extractParamNames(path) {
   const matches = path.match(/:(\w+)/g);
   const names = matches ? matches.map((match) => match.slice(1)) : [];
-  if (path.endsWith("/*"))
-    names.push("*");
+  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) {
@@ -101,14 +150,14 @@ function fillPathParams(path, args) {
     }
     return encodeURIComponent(String(value));
   });
-  if (!filled.endsWith("/*"))
+  if (!wildcard)
     return filled;
-  const wildcard = args["*"];
-  if (wildcard === undefined || wildcard === null) {
-    throw new Error("Missing path param: *");
+  const wildcardValue = args[wildcard.name];
+  if (wildcardValue === undefined || wildcardValue === null) {
+    throw new Error(`Missing path param: ${wildcard.name}`);
   }
-  const remainder = String(wildcard).split("/").map((segment) => encodeURIComponent(segment)).join("/");
-  filled = `${filled.slice(0, -1)}${remainder}`;
+  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) {
@@ -232,7 +281,7 @@ function createHttpClient(config) {
   let ssrCookies = null;
   let isLoggedOut = false;
   const listeners = new Set;
-  const authEndpoints = config.authEndpoints ?? ["/auth/"];
+  const suppressUnauthorizedFor = config.suppressUnauthorizedFor ?? [];
   const parseError = config.parseError ?? parseApiErrorBody;
   function emit(event) {
     for (const fn of listeners) {
@@ -271,7 +320,7 @@ function createHttpClient(config) {
         async ({ request: request2, response }) => {
           if (response.status === 401) {
             const url = new URL(request2.url).pathname;
-            if (!isLoggedOut && !authEndpoints.some((path) => url.startsWith(path))) {
+            if (!isLoggedOut && !suppressUnauthorizedFor.some((matches) => matches(url))) {
               isLoggedOut = true;
               emit({ type: "unauthorized" });
             }
@@ -341,6 +390,7 @@ function createHttpClient(config) {
   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),
@@ -379,6 +429,25 @@ function withOutput(endpoint, result) {
     return result;
   return result.then((value) => value === undefined ? undefined : schema.parse(value));
 }
+function contractEndpointMatchers(contract, endpointNames, contractConfig) {
+  const selected = endpointNames ? new Set(endpointNames) : null;
+  const matchers = [];
+  for (const [key, endpoint] of typedEntries(contract.endpoints)) {
+    if (selected && !selected.has(key))
+      continue;
+    if (endpoint.expose && !endpoint.expose.includes("HTTP")) {
+      if (selected) {
+        throw new Error(`Cannot create an HTTP route matcher for non-HTTP endpoint: ${String(key)}`);
+      }
+      continue;
+    }
+    matchers.push(createClientRouteMatcher(endpoint, contract.meta.prefix, contractConfig));
+  }
+  if (selected && matchers.length !== selected.size) {
+    throw new Error("Cannot create an HTTP route matcher for an unknown endpoint");
+  }
+  return matchers;
+}
 function createClient(contract, configOrClient, contractConfig) {
   const client = {};
   const makeMethod = isHttpAdapter(configOrClient) ? (endpoint) => createHttpMethod(endpoint, contract.meta.prefix, configOrClient, contractConfig) : (endpoint) => createFetchMethod(endpoint, contract.meta.prefix, configOrClient, contractConfig);
@@ -392,6 +461,32 @@ function createClient(contract, configOrClient, contractConfig) {
 function createClients(contracts, configOrClient, contractConfig) {
   return mapObject(contracts, (_key, contract) => createClient(contract, configOrClient, contractConfig));
 }
+function createScopedClients(contracts, configOrClient, scopeConfigs) {
+  const registry = {};
+  for (const [namespace, value] of Object.entries(contracts)) {
+    const list = Array.isArray(value) ? value : [value];
+    const client = {};
+    for (const contract of list) {
+      const scope = contract.meta.scope;
+      if (!scope) {
+        throw new Error(`Contract in client namespace "${namespace}" has no scope`);
+      }
+      const scopeConfig = Object.entries(scopeConfigs).find(([configuredScope]) => configuredScope === scope)?.[1];
+      if (!scopeConfig) {
+        throw new Error(`Missing client config for scope: ${scope}`);
+      }
+      const scoped = createClient(contract, configOrClient, scopeConfig);
+      for (const [methodName, method] of Object.entries(scoped)) {
+        if (Object.hasOwn(client, methodName)) {
+          throw new Error(`Client namespace "${namespace}" has duplicate method: ${methodName}`);
+        }
+        client[methodName] = method;
+      }
+    }
+    registry[namespace] = client;
+  }
+  return registry;
+}
 function isHttpAdapter(value) {
   return typeof value === "object" && "get" in value && typeof value.get === "function";
 }
@@ -408,7 +503,7 @@ function createHttpMethod(endpoint, prefix, client, config) {
       if (!isMultipartFile(file)) {
         throw new Error(`Missing multipart file field: ${endpoint.multipart}`);
       }
-      if (httpMethod === "get" || httpMethod === "delete") {
+      if (httpMethod === "get" || httpMethod === "head" || httpMethod === "delete") {
         throw new Error(`Multipart endpoint ${endpoint.method} ${endpoint.path} must be POST / PUT / PATCH`);
       }
       const formData = new FormData;
@@ -416,8 +511,8 @@ function createHttpMethod(endpoint, prefix, client, config) {
       appendFormFields(formData, plan.remainingArgs, new Set([endpoint.multipart]));
       return withOutput(endpoint, client[httpMethod](plan.relativeUrl, formData, withTimeout(undefined, endpoint)));
     }
-    if (httpMethod === "get") {
-      return withOutput(endpoint, client.get(plan.relativeUrl, withTimeout(undefined, endpoint)));
+    if (httpMethod === "get" || httpMethod === "head") {
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, withTimeout(undefined, endpoint)));
     }
     if (httpMethod === "delete") {
       return withOutput(endpoint, client.delete(plan.relativeUrl, withTimeout(undefined, endpoint)));
@@ -434,7 +529,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       ...typeof config.headers === "function" ? config.headers() : config.headers
     };
     const signal = endpoint.timeout !== undefined ? AbortSignal.timeout(endpoint.timeout) : undefined;
-    const hasBody = endpoint.method !== "GET" && endpoint.method !== "DELETE" && !endpoint.multipart && endpoint.input && args;
+    const hasBody = endpoint.method !== "GET" && endpoint.method !== "HEAD" && endpoint.method !== "DELETE" && !endpoint.multipart && endpoint.input && args;
     if (hasBody)
       headers["Content-Type"] = "application/json";
     if (endpoint.multipart && args) {
@@ -494,12 +589,14 @@ async function throwForErrorResponse(res, config, fallbackBody) {
 function createUrlBuilder(contract, source, contractConfig) {
   const builder = {};
   for (const [key, endpoint] of typedEntries(contract.endpoints)) {
-    if (endpoint.method !== "GET" || endpoint.multipart)
-      continue;
     if (endpoint.expose && !endpoint.expose.includes("HTTP"))
       continue;
     setClientMethod(builder, key, (args) => {
       const plan = planClientRequest(endpoint, contract.meta.prefix, args ?? {}, contractConfig);
+      if (endpoint.method !== "GET" && endpoint.method !== "DELETE" && Object.keys(plan.remainingArgs).length > 0) {
+        const fields = Object.keys(plan.remainingArgs).join(", ");
+        throw new Error(`URL builder for ${endpoint.method} ${endpoint.path} received non-URL fields: ${fields}`);
+      }
       return joinClientBaseUrl(source.baseUrl, plan.relativeUrl);
     });
   }
@@ -718,11 +815,13 @@ export {
   createUrlBuilder,
   createTraceContext,
   createSocketIOClient,
+  createScopedClients,
   createRetainedTopics,
   createHttpClient,
   createContractFactory,
   createClients,
   createClient,
+  contractEndpointMatchers,
   conflict,
   childSpan,
   badRequest,

package/dist/internal/route-pattern.d.ts

@@ -0,0 +1,7 @@
+export interface TrailingWildcard {
+    name: string;
+    segmentIndex: number;
+}
+/** Parse and validate the route's single named terminal wildcard, if present. */
+export declare function parseTrailingWildcard(path: string): TrailingWildcard | null;
+//# sourceMappingURL=route-pattern.d.ts.map

package/dist/internal/route-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-pattern.d.ts","sourceRoot":"","sources":["../../src/internal/route-pattern.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CA2C3E"}

package/dist/node.js

@@ -3,8 +3,8 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-p3kwf73n.js";
-import"./index-czmqks7r.js";
+} from "./index-7rbzbnnf.js";
+import"./index-6jypn22c.js";
 import"./index-x3fcszf8.js";
 import {
   AppError,
@@ -15,7 +15,7 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "./index-mzx0an0s.js";
+} from "./index-fyfk537k.js";
 // src/server/node.ts
 import { serve } from "srvx";
 async function serveNode(config) {

package/dist/observability/index.js

@@ -16,7 +16,7 @@ import {
   setRequestError,
   setRequestUser,
   wrapInRequestContext
-} from "../index-mzx0an0s.js";
+} from "../index-fyfk537k.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

@@ -1,54 +1,68 @@
 /**
- * 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,
- * }});
- * ```
+ * Declarative CRUD cache handlers for `createCacheBridge`. One config projects
+ * a full event entity into the cached list item and patches plain, paginated or
+ * infinite TanStack Query data without changing its envelope metadata.
  */
 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 | {
+/** The `deleted` event may carry the whole entity or only its id. */
+export type DeletedPayload<TData> = TData | {
     id: string;
 };
+/** Typed event passed to dynamic list/detail query-key selectors. */
+export type EntityCacheEvent<TData> = {
+    type: 'created';
+    entity: TData;
+    id: string;
+} | {
+    type: 'updated';
+    entity: TData;
+    id: string;
+} | {
+    type: 'deleted';
+    payload: DeletedPayload<TData>;
+    id: string;
+};
+/** A static cache key/prefix or an event-aware key factory. */
+export type EntityCacheKey<TData> = QueryKey | ((event: EntityCacheEvent<TData>) => QueryKey);
+export type EntityCacheListShape = 'array' | 'paginated' | 'infinite-array' | 'infinite-paginated';
+/** List envelope, scoped key and explicit CRUD policies. */
+export interface EntityCacheListConfig<TData, TListItem> {
+    /** Static query-key prefix or an event-aware scoped key factory. */
+    key: EntityCacheKey<TData>;
+    /** Edge/page used for a create or an inserted missing update. */
+    createAt: 'start' | 'end';
+    /** Explicit behavior when an update's id is absent from every cached page. */
+    updateMissing: 'skip' | 'insert';
+    /** Backend-equivalent ordering for each affected logical item array. */
+    compare?: (left: TListItem, right: TListItem) => number;
+    /** Cached data envelope; no runtime shape inference is performed. */
+    shape: EntityCacheListShape;
+}
 /** 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;
+export interface EntityCacheConfig<TData, TListItem = TData> {
+    /** Canonical id from a full created/updated entity. */
+    getId: (entity: TData) => string;
+    /** Canonical id from the projected item stored in list caches. */
+    getListItemId: (item: TListItem) => string;
+    /** Project a full mutation entity into the list cache's item type. */
+    toListItem: (entity: TData) => TListItem;
+    /** Read a deleted id. Default: a string `.id`, otherwise `getId(payload)`. */
+    getDeletedId?: (payload: DeletedPayload<TData>) => string;
+    /** List envelope, key/prefix, insertion policy and optional ordering. */
+    list: EntityCacheListConfig<TData, TListItem>;
+    /** Static detail key or event-aware key factory. Omit to skip detail updates. */
+    detailKey?: EntityCacheKey<TData>;
 }
-/** The three handlers to wire onto a `createCacheBridge` `handlers` map. */
-export interface EntityCacheHandlers<T> {
-    created: CacheBridgeHandler<T>;
-    updated: CacheBridgeHandler<T>;
-    deleted: CacheBridgeHandler<DeletedPayload<T>>;
+/** The three handlers to wire onto a `createCacheBridge` handlers map. */
+export interface EntityCacheHandlers<TData> {
+    created: CacheBridgeHandler<TData>;
+    updated: CacheBridgeHandler<TData>;
+    deleted: CacheBridgeHandler<DeletedPayload<TData>>;
 }
 /**
- * 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.
+ * Build created/updated/deleted cache handlers over one declared list shape.
+ * Every event resolves its own scoped keys and applies the same fresh-echo gate.
  */
-export declare function createEntityCacheHandlers<T>(config: EntityCacheConfig<T>): EntityCacheHandlers<T>;
+export declare function createEntityCacheHandlers<TData, TListItem = TData>(config: EntityCacheConfig<TData, TListItem>): EntityCacheHandlers<TData>;
 //# sourceMappingURL=entity-cache.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"entity-cache.d.ts","sourceRoot":"","sources":["../../src/react/entity-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGpE,OAAO,KAAK,EAAsB,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,qEAAqE;AACrE,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,CAAC,KAAK,IAC9B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,+DAA+D;AAC/D,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI,QAAQ,GAAG,CAAC,CAAC,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAC5B,OAAO,GACP,WAAW,GACX,gBAAgB,GAChB,oBAAoB,CAAC;AAEzB,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB,CAAC,KAAK,EAAE,SAAS;IACrD,oEAAoE;IACpE,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC;IAC1B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,MAAM,CAAC;IACxD,qEAAqE;IACrE,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AAED,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK;IACzD,uDAAuD;IACvD,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK,MAAM,CAAC;IACjC,kEAAkE;IAClE,aAAa,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC;IAC3C,sEAAsE;IACtE,UAAU,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK,SAAS,CAAC;IACzC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC;IAC1D,yEAAyE;IACzE,IAAI,EAAE,qBAAqB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC9C,iFAAiF;IACjF,SAAS,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;CACnC;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB,CAAC,KAAK;IACxC,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,EAAE,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;CACpD;AAiJD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,EAChE,MAAM,EAAE,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,GAC1C,mBAAmB,CAAC,KAAK,CAAC,CAkD5B"}

package/dist/react.d.ts

@@ -1,4 +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';
+export { createEntityCacheHandlers, type DeletedPayload, type EntityCacheConfig, type EntityCacheEvent, type EntityCacheHandlers, type EntityCacheKey, type EntityCacheListConfig, type EntityCacheListShape, } 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;AACjF,OAAO,EACL,yBAAyB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,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,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,sBAAsB,CAAC"}