stitchkit 0.72.2 → 0.72.3

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

@@ -14,6 +14,8 @@
  */
 import type { QueryClient, QueryKey } from '@tanstack/react-query';
 /** Minimal emitter — subscribe to an event, get an unsubscribe back. */
+import type { InferRealtimeEventMap, RealtimeEventRegistry } from '../realtime/contract.js';
+import type { ValidatedRealtimeSocket } from '../realtime/socket.js';
 export interface CacheBridgeSocket<TEvents> {
     on<K extends keyof TEvents & string>(event: K, handler: TEvents[K]): () => void;
 }
@@ -52,6 +54,28 @@ export interface CacheBridge {
     /** Forget every freshness marker without changing socket subscriptions. */
     clearFresh(): void;
 }
+/**
+ * The bridge, fed by a validated realtime contract instead of a raw socket.
+ *
+ * A realtime registry maps an event name to its DEFINITION — `{ args, ack }` — while the bridge's
+ * event map wants the handler FUNCTION at that position. Structurally the socket still matched,
+ * so the generic bound to the registry and every payload inferred as `never`: the combination
+ * `AGENTS.md` prescribes did not compile, and the error pointed at the consumer's own property
+ * access rather than at the seam. Naming the mapping is the whole fix; nothing runs differently.
+ */
+export interface RealtimeCacheBridgeConfig<TInbound extends RealtimeEventRegistry> extends Omit<CacheBridgeConfig<InferRealtimeEventMap<TInbound>>, 'socket'> {
+    socket: ValidatedRealtimeSocket<TInbound, RealtimeEventRegistry>;
+}
 export declare function createCacheBridge<TEvents>(config: CacheBridgeConfig<TEvents>): CacheBridge;
+/**
+ * The same bridge, fed by a validated realtime contract instead of a raw socket.
+ *
+ * A separate function rather than an overload, deliberately. A validated socket also satisfies
+ * the looser `CacheBridgeSocket`, so an overload would be decided structurally — and worse, an
+ * existing caller that passes its event map explicitly (`createCacheBridge<NoteEvents>(…)`) would
+ * bind to whichever signature came first and stop compiling. Two names cost one line at the call
+ * site and break nobody.
+ */
+export declare function createRealtimeCacheBridge<TInbound extends RealtimeEventRegistry>(config: RealtimeCacheBridgeConfig<TInbound>): CacheBridge;
 export {};
 //# sourceMappingURL=cache-bridge.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"cache-bridge.d.ts","sourceRoot":"","sources":["../../src/react/cache-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEnE,wEAAwE;AACxE,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;CACjF;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,gFAAgF;IAChF,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC;CACjC;AAED,oEAAoE;AACpE,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3E,MAAM,MAAM,kBAAkB,CAAC,QAAQ,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAE7F,MAAM,MAAM,mBAAmB,CAAC,OAAO,IAAI;KACxC,CAAC,IAAI,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7E,CAAC;AAEF,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACnC;;;;;OAKG;IACH,WAAW,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,CAAC;IAC/C,QAAQ,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACvC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,IAAI,IAAI,CAAC;IAChB,UAAU,IAAI,IAAI,CAAC;IACnB;qEACiE;IACjE,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,2EAA2E;IAC3E,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,WAAW,CAsF1F"}
+{"version":3,"file":"cache-bridge.d.ts","sourceRoot":"","sources":["../../src/react/cache-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEnE,wEAAwE;AACxE,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAElE,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;CACjF;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,gFAAgF;IAChF,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC;CACjC;AAED,oEAAoE;AACpE,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3E,MAAM,MAAM,kBAAkB,CAAC,QAAQ,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAE7F,MAAM,MAAM,mBAAmB,CAAC,OAAO,IAAI;KACxC,CAAC,IAAI,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7E,CAAC;AAEF,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACnC;;;;;OAKG;IACH,WAAW,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,CAAC;IAC/C,QAAQ,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACvC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,IAAI,IAAI,CAAC;IAChB,UAAU,IAAI,IAAI,CAAC;IACnB;qEACiE;IACjE,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,2EAA2E;IAC3E,UAAU,IAAI,IAAI,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB,CAAC,QAAQ,SAAS,qBAAqB,CAC/E,SAAQ,IAAI,CAAC,iBAAiB,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC;IAC1E,MAAM,EAAE,uBAAuB,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;CAClE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,WAAW,CAsF1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,SAAS,qBAAqB,EAC9E,MAAM,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC1C,WAAW,CAKb"}

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.js';
+export { type CacheBridge, type CacheBridgeConfig, type CacheBridgeContext, type CacheBridgeHandler, type CacheBridgeHandlers, type CacheBridgeSocket, createCacheBridge, createRealtimeCacheBridge, type RealtimeCacheBridgeConfig, } from './react/cache-bridge.js';
 export { type CursorQueryConfig, createCursorQuery } from './react/cursor-query.js';
 export { createEntityCacheHandlers, type DeletedPayload, type EntityCacheConfig, type EntityCacheEvent, type EntityCacheHandlers, type EntityCacheKey, type EntityCacheListConfig, type EntityCacheListShape, type EntityCacheMembership, type EntityCacheMembershipPolicy, type EntityCacheTotalDeltaInput, type EntityCacheTotalPolicy, } from './react/entity-cache.js';
 //# 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,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,GAC5B,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,EACjB,yBAAyB,EACzB,KAAK,yBAAyB,GAC/B,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,EACzB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC"}

package/dist/react.js

@@ -78,6 +78,9 @@ function createCacheBridge(config) {
     clearFresh
   };
 }
+function createRealtimeCacheBridge(config) {
+  return createCacheBridge(config);
+}
 // src/react/cursor-query.ts
 import {
   createInfiniteQuery
@@ -311,6 +314,7 @@ function idOf(payload, getId) {
   return hasStringId(payload) ? payload.id : getId(payload);
 }
 export {
+  createRealtimeCacheBridge,
   createEntityCacheHandlers,
   createCursorQuery,
   createCacheBridge

package/llms-full.txt

@@ -7071,6 +7071,26 @@ leaving the handshake waiting forever.
 
 ## Cache bridge
 
+**Using a validated realtime contract? Use `createRealtimeCacheBridge`.** A
+realtime registry maps an event name to its *definition* (`{ args, ack }`),
+while the plain bridge's event map expects the *handler function* at that
+position. A validated socket satisfies the looser type structurally, so passing
+one to `createCacheBridge` compiled and inferred every payload as `never` —
+the error then landed on your own property access rather than on the seam.
+`createRealtimeCacheBridge` performs the mapping; nothing runs differently.
+
+```ts
+import { createRealtimeCacheBridge } from 'stitchkit/react'
+
+const bridge = createRealtimeCacheBridge<typeof contract.serverToClient>({
+  socket: realtimeClient,
+  queryClient,
+  handlers: {
+    noteUpdated: (note, { queryClient: qc }) => qc.setQueryData(noteKey(note.id), note),
+  },
+})
+```
+
 `createCacheBridge` syncs socket events into the TanStack Query cache — a server
 push updates the UI with no refetch. It is transport-agnostic: it takes any
 emitter with `on(event, handler) => unsubscribe`, which the
@@ -13764,6 +13784,7 @@ and `react-query-kit` peers.
 |--------|------|---------|
 | `createCursorQuery` | function | a cursor-paginated infinite query — [guide](../guide/client.md#cursor-pagination) |
 | `createCacheBridge` | function | sync socket events into the Query cache — [guide](../guide/realtime.md#cache-bridge) |
+| `createRealtimeCacheBridge` | function | the same bridge fed by a **validated realtime contract**; the payload comes from the contract's args tuple instead of inferring `never` |
 | `createEntityCacheHandlers` | function | created/updated/deleted cache handlers for one entity — [guide](../guide/realtime.md#entity-cache-handlers) |
 | `EntityCacheConfig` | _type_ | config for `createEntityCacheHandlers` |
 | `EntityCacheMembership` / `EntityCacheMembershipPolicy` | _type_ | per-exact-query `include | exclude | unknown` filter decision and unknown invalidation policy |
@@ -13777,6 +13798,7 @@ and `react-query-kit` peers.
 | `CursorQueryConfig` | _type_ | config for `createCursorQuery` |
 | `CacheBridge` | _type_ | the `createCacheBridge` handle |
 | `CacheBridgeConfig` | _type_ | config for `createCacheBridge` |
+| `RealtimeCacheBridgeConfig` | _type_ | config for `createRealtimeCacheBridge` — same fields, a `ValidatedRealtimeSocket` in place of the raw socket |
 | `CacheBridgeContext` | _type_ | the `ctx` a bridge handler receives |
 | `CacheBridgeHandler` | _type_ | one event-to-cache handler |
 | `CacheBridgeHandlers` | _type_ | the handler map |

package/package.json

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