stitchkit 0.44.1 → 0.45.0

package/dist/browser/socket-io.d.ts

@@ -21,6 +21,8 @@
  * unsubscribe), so it plugs straight into `createCacheBridge`.
  */
 import type { EventsMap } from '@socket.io/component-emitter';
+import type { RealtimeContract, RealtimeEventRegistry, RealtimeRejectedEventHook } from '../realtime/contract';
+import { type ValidatedRealtimeSocket } from '../realtime/socket';
 /**
  * Socket.IO event map — `{ event: (...args) => void }`. Aliases Socket.IO's
  * own `EventsMap` constraint, which intentionally maps to `any`: that is what
@@ -113,5 +115,17 @@ export interface SocketIOClient<TServerEvents extends SocketEventMap, TClientEve
      */
     onConnectionChange(listener: (connected: boolean, reason?: string) => void): () => void;
 }
+export interface RealtimeClient<TServerToClient extends RealtimeEventRegistry, TClientToServer extends RealtimeEventRegistry> extends ValidatedRealtimeSocket<TServerToClient, TClientToServer> {
+    connect(): void;
+    disconnect(): void;
+    readonly connected: boolean;
+    onConnectionChange(listener: (connected: boolean, reason?: string) => void): () => void;
+}
+export interface RealtimeClientOptions<TServerToClient extends RealtimeEventRegistry> extends SocketIOClientConfig<{
+    [TEvent in keyof TServerToClient]: (...args: unknown[]) => void;
+}> {
+    onRejected?: RealtimeRejectedEventHook;
+}
+export declare function createRealtimeClient<const TServerToClient extends RealtimeEventRegistry, const TClientToServer extends RealtimeEventRegistry>(contract: RealtimeContract<TServerToClient, TClientToServer>, { onRejected, ...config }: RealtimeClientOptions<TServerToClient>): RealtimeClient<TServerToClient, TClientToServer>;
 export declare function createSocketIOClient<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap>(config: SocketIOClientConfig<TServerEvents>): SocketIOClient<TServerEvents, TClientEvents>;
 //# sourceMappingURL=socket-io.d.ts.map

package/dist/browser/socket-io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket-io.d.ts","sourceRoot":"","sources":["../../src/browser/socket-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AA0D9D;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC;AAEvC,MAAM,WAAW,oBAAoB,CAAC,aAAa,SAAS,cAAc,GAAG,cAAc;IACzF,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,IAAI,CAAC,EACD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACvE,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAClD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC5C,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;;;OAcG;IACH,2BAA2B,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7C;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,cAAc,CAC7B,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc;IAEpC,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;IAChB,+CAA+C;IAC/C,UAAU,IAAI,IAAI,CAAC;IACnB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,aAAa,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAC5F,8DAA8D;IAC9D,IAAI,CAAC,CAAC,SAAS,MAAM,aAAa,GAAG,MAAM,EACzC,KAAK,EAAE,CAAC,EACR,GAAG,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GACpC,IAAI,CAAC;IACR;;;;;;OAMG;IACH,kBAAkB,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACzF;AAED,wBAAgB,oBAAoB,CAClC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EACpC,MAAM,EAAE,oBAAoB,CAAC,aAAa,CAAC,GAAG,cAAc,CAAC,aAAa,EAAE,aAAa,CAAC,CA8J3F"}
+{"version":3,"file":"socket-io.d.ts","sourceRoot":"","sources":["../../src/browser/socket-io.ts"],"names":[],"mappings":"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"}

package/dist/{index-4fyn9f09.js → index-w0mec79h.js}

@@ -1056,6 +1056,176 @@ function createImplement() {
   return (contract, handlers) => implement(contract, handlers);
 }
 
+// src/realtime/socket.ts
+import { z } from "zod";
+var AcknowledgementCallbackSchema = z.function();
+function method(target, name) {
+  const value = Reflect.get(target, name);
+  if (typeof value !== "function") {
+    throw new Error(`Realtime target does not implement ${name}()`);
+  }
+  return (...args) => Reflect.apply(value, target, args);
+}
+function splitWireArguments(definition, args) {
+  if (!definition.ack)
+    return { values: args };
+  const acknowledgement = args.at(-1);
+  if (typeof acknowledgement !== "function")
+    return { values: args };
+  return {
+    values: args.slice(0, -1),
+    acknowledgement: (...callbackArgs) => Reflect.apply(acknowledgement, undefined, callbackArgs)
+  };
+}
+function eventDefinition(registry, event) {
+  const definition = registry[event];
+  if (!definition)
+    throw new Error(`Unknown realtime event "${event}"`);
+  return definition;
+}
+function reportRejected(rejected, hook) {
+  if (!hook) {
+    console.error(`[stitchkit] rejected realtime ${rejected.direction} event "${rejected.event}" (${rejected.phase})`, rejected.error);
+    return;
+  }
+  Promise.resolve(hook(rejected)).catch((error) => {
+    console.error("[stitchkit] realtime rejection hook failed", error);
+  });
+}
+function createValidatedRealtimeSocket({
+  target,
+  inbound,
+  outbound,
+  inboundDirection,
+  outboundDirection,
+  onRejected,
+  subscribe
+}) {
+  const onTarget = method(target, "on");
+  const offTarget = subscribe ? undefined : method(target, "off");
+  const emitTarget = method(target, "emit");
+  return {
+    on: (event, handler) => {
+      const definition = eventDefinition(inbound, event);
+      const wrapped = (...wireArgs) => {
+        const { values, acknowledgement } = splitWireArguments(definition, wireArgs);
+        const parsed = definition.args.safeParse(values);
+        if (!parsed.success) {
+          reportRejected({
+            event,
+            direction: inboundDirection,
+            phase: "arguments",
+            error: parsed.error
+          }, onRejected);
+          return;
+        }
+        if (definition.ack && !acknowledgement) {
+          const callback = AcknowledgementCallbackSchema.safeParse(undefined);
+          if (!callback.success) {
+            reportRejected({
+              event,
+              direction: inboundDirection,
+              phase: "acknowledgement",
+              error: callback.error
+            }, onRejected);
+          }
+          return;
+        }
+        const applicationArgs = [...parsed.data];
+        if (definition.ack) {
+          applicationArgs.push((value) => {
+            const ack = definition.ack?.safeParse(value);
+            if (!ack?.success) {
+              if (ack) {
+                reportRejected({
+                  event,
+                  direction: outboundDirection,
+                  phase: "acknowledgement",
+                  error: ack.error
+                }, onRejected);
+              }
+              return;
+            }
+            acknowledgement?.(ack.data);
+          });
+        }
+        Reflect.apply(handler, undefined, applicationArgs);
+      };
+      if (subscribe)
+        return subscribe(event, wrapped);
+      onTarget(event, wrapped);
+      return () => {
+        offTarget?.(event, wrapped);
+      };
+    },
+    emit: (event, ...args) => {
+      const definition = eventDefinition(outbound, event);
+      const { values, acknowledgement } = splitWireArguments(definition, args);
+      const parsed = definition.args.parse(values);
+      if (definition.ack && !acknowledgement) {
+        AcknowledgementCallbackSchema.parse(undefined);
+      }
+      const wireArgs = [...parsed];
+      if (definition.ack && acknowledgement) {
+        wireArgs.push((value) => {
+          const ack = definition.ack?.safeParse(value);
+          if (!ack?.success) {
+            if (ack) {
+              reportRejected({
+                event,
+                direction: inboundDirection,
+                phase: "acknowledgement",
+                error: ack.error
+              }, onRejected);
+            }
+            return;
+          }
+          acknowledgement(ack.data);
+        });
+      }
+      emitTarget(event, ...wireArgs);
+    }
+  };
+}
+
+// src/server/realtime.ts
+function bindRealtimeServer(contract, handle, options = {}) {
+  const outbound = (target) => createValidatedRealtimeSocket({
+    target,
+    inbound: {},
+    outbound: contract.serverToClient,
+    inboundDirection: "server-inbound",
+    outboundDirection: "server-outbound",
+    onRejected: options.onRejected
+  });
+  const broadcast = outbound(handle.io);
+  return {
+    onConnection: (handler) => {
+      const listener = (raw) => {
+        const events = createValidatedRealtimeSocket({
+          target: raw,
+          inbound: contract.clientToServer,
+          outbound: contract.serverToClient,
+          inboundDirection: "server-inbound",
+          outboundDirection: "server-outbound",
+          onRejected: options.onRejected
+        });
+        handler({
+          raw,
+          events,
+          to: (room) => outbound(raw.to(room))
+        });
+      };
+      handle.io.on("connection", listener);
+      return () => {
+        handle.io.off("connection", listener);
+      };
+    },
+    emit: broadcast.emit,
+    to: (room) => outbound(handle.io.to(room))
+  };
+}
+
 // src/server/websocket.ts
 function webSocketLane(lane) {
   const { match, handlers } = lane;
@@ -1202,4 +1372,4 @@ function socketIoLane(websocket) {
   });
 }
 
-export { parseMultipart, mimeForPath, staticRoute, createHandler, implement, createImplement, webSocketLane, composeWebSocketHandlers, createSocketIOServer, socketIoLane };
+export { parseMultipart, mimeForPath, staticRoute, createHandler, implement, createImplement, bindRealtimeServer, webSocketLane, composeWebSocketHandlers, createSocketIOServer, socketIoLane };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { type ClientConfig, type ClientContract, type ClientRegistryValue, type ContractClientConfig, contractEndpointMatchers, createClient, createClients, createScopedClients, createScopedUrlBuilders, createUrlBuilder, createUrlBuilders, type PathPrefixArgs, type RegistryScope, type ScopeClientConfigs, type ScopedClientRegistry, type ScopedUrlBuilderRegistry, 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 { RealtimeClient, RealtimeClientOptions, SocketEventMap, SocketIOClient, SocketIOClientConfig, } from './browser/socket-io';
+export { createRealtimeClient, createSocketIOClient } from './browser/socket-io';
 export { type ParseSSEOptions, parseSSE } from './browser/stream';
 export * from './contract';
 export { childSpan, createTraceContext, formatTraceparent, parseTraceparent, type TraceContext, } from './observability/trace';
+export * from './realtime';
 export { createRetainedTopics, type RetainedTopics } from './retained';
 //# sourceMappingURL=index.d.ts.map

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,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,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"}
+{"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,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,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,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACjF,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,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -646,6 +646,138 @@ function createUrlBuilders(contracts, source, contractConfig) {
 function createScopedUrlBuilders(contracts, source, scopeConfigs) {
   return buildScopedRegistry(contracts, scopeConfigs, "URL builder", (contract, config) => createUrlBuilder(contract, source, config));
 }
+// src/realtime/socket.ts
+import { z } from "zod";
+var AcknowledgementCallbackSchema = z.function();
+function method(target, name) {
+  const value = Reflect.get(target, name);
+  if (typeof value !== "function") {
+    throw new Error(`Realtime target does not implement ${name}()`);
+  }
+  return (...args) => Reflect.apply(value, target, args);
+}
+function splitWireArguments(definition, args) {
+  if (!definition.ack)
+    return { values: args };
+  const acknowledgement = args.at(-1);
+  if (typeof acknowledgement !== "function")
+    return { values: args };
+  return {
+    values: args.slice(0, -1),
+    acknowledgement: (...callbackArgs) => Reflect.apply(acknowledgement, undefined, callbackArgs)
+  };
+}
+function eventDefinition(registry, event) {
+  const definition = registry[event];
+  if (!definition)
+    throw new Error(`Unknown realtime event "${event}"`);
+  return definition;
+}
+function reportRejected(rejected, hook) {
+  if (!hook) {
+    console.error(`[stitchkit] rejected realtime ${rejected.direction} event "${rejected.event}" (${rejected.phase})`, rejected.error);
+    return;
+  }
+  Promise.resolve(hook(rejected)).catch((error) => {
+    console.error("[stitchkit] realtime rejection hook failed", error);
+  });
+}
+function createValidatedRealtimeSocket({
+  target,
+  inbound,
+  outbound,
+  inboundDirection,
+  outboundDirection,
+  onRejected,
+  subscribe
+}) {
+  const onTarget = method(target, "on");
+  const offTarget = subscribe ? undefined : method(target, "off");
+  const emitTarget = method(target, "emit");
+  return {
+    on: (event, handler) => {
+      const definition = eventDefinition(inbound, event);
+      const wrapped = (...wireArgs) => {
+        const { values, acknowledgement } = splitWireArguments(definition, wireArgs);
+        const parsed = definition.args.safeParse(values);
+        if (!parsed.success) {
+          reportRejected({
+            event,
+            direction: inboundDirection,
+            phase: "arguments",
+            error: parsed.error
+          }, onRejected);
+          return;
+        }
+        if (definition.ack && !acknowledgement) {
+          const callback = AcknowledgementCallbackSchema.safeParse(undefined);
+          if (!callback.success) {
+            reportRejected({
+              event,
+              direction: inboundDirection,
+              phase: "acknowledgement",
+              error: callback.error
+            }, onRejected);
+          }
+          return;
+        }
+        const applicationArgs = [...parsed.data];
+        if (definition.ack) {
+          applicationArgs.push((value) => {
+            const ack = definition.ack?.safeParse(value);
+            if (!ack?.success) {
+              if (ack) {
+                reportRejected({
+                  event,
+                  direction: outboundDirection,
+                  phase: "acknowledgement",
+                  error: ack.error
+                }, onRejected);
+              }
+              return;
+            }
+            acknowledgement?.(ack.data);
+          });
+        }
+        Reflect.apply(handler, undefined, applicationArgs);
+      };
+      if (subscribe)
+        return subscribe(event, wrapped);
+      onTarget(event, wrapped);
+      return () => {
+        offTarget?.(event, wrapped);
+      };
+    },
+    emit: (event, ...args) => {
+      const definition = eventDefinition(outbound, event);
+      const { values, acknowledgement } = splitWireArguments(definition, args);
+      const parsed = definition.args.parse(values);
+      if (definition.ack && !acknowledgement) {
+        AcknowledgementCallbackSchema.parse(undefined);
+      }
+      const wireArgs = [...parsed];
+      if (definition.ack && acknowledgement) {
+        wireArgs.push((value) => {
+          const ack = definition.ack?.safeParse(value);
+          if (!ack?.success) {
+            if (ack) {
+              reportRejected({
+                event,
+                direction: inboundDirection,
+                phase: "acknowledgement",
+                error: ack.error
+              }, onRejected);
+            }
+            return;
+          }
+          acknowledgement(ack.data);
+        });
+      }
+      emitTarget(event, ...wireArgs);
+    }
+  };
+}
+
 // src/retained.ts
 function createRetainedTopics() {
   const last = {};
@@ -691,6 +823,39 @@ function toIoAuth(auth) {
     Promise.resolve().then(auth).then(cb, () => cb({}));
   };
 }
+function createRealtimeClient(contract, { onRejected, ...config }) {
+  const transport = createSocketIOClient(config);
+  const events = createValidatedRealtimeSocket({
+    target: transport,
+    inbound: contract.serverToClient,
+    outbound: contract.clientToServer,
+    inboundDirection: "client-inbound",
+    outboundDirection: "client-outbound",
+    onRejected,
+    subscribe: (event, handler) => {
+      const subscribe = Reflect.get(transport, "on");
+      if (typeof subscribe !== "function") {
+        throw new Error("Socket.IO client does not implement on()");
+      }
+      const unsubscribe = Reflect.apply(subscribe, transport, [event, handler]);
+      if (typeof unsubscribe !== "function") {
+        throw new Error("Socket.IO client on() did not return an unsubscribe function");
+      }
+      return () => {
+        Reflect.apply(unsubscribe, undefined, []);
+      };
+    }
+  });
+  return {
+    ...events,
+    connect: transport.connect,
+    disconnect: transport.disconnect,
+    get connected() {
+      return transport.connected;
+    },
+    onConnectionChange: transport.onConnectionChange
+  };
+}
 function createSocketIOClient(config) {
   let socket = null;
   let desiredConnected = false;
@@ -802,7 +967,7 @@ function createSocketIOClient(config) {
   };
 }
 // src/internal/errors.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/server/stream.ts
 async function* parseSSE(response, options) {
@@ -838,6 +1003,10 @@ async function* parseSSE(response, options) {
     reader.releaseLock();
   }
 }
+// src/realtime/contract.ts
+function defineRealtimeContract(contract) {
+  return contract;
+}
 export {
   unauthorized,
   rateLimited,
@@ -849,6 +1018,7 @@ export {
   formatTraceparent,
   forbidden,
   encodeCursor,
+  defineRealtimeContract,
   defineErrors,
   defineContract,
   decodeCursor,
@@ -859,6 +1029,7 @@ export {
   createScopedUrlBuilders,
   createScopedClients,
   createRetainedTopics,
+  createRealtimeClient,
   createHttpClient,
   createContractFactory,
   createClients,

package/dist/node.d.ts

@@ -9,6 +9,7 @@ export { createHandler } from './server/create';
 export { createImplement, implement } from './server/implement';
 export type { LogFormat } from './server/logger';
 export { type NodeServerConfig, type NodeServerHandle, serveNode } from './server/node';
+export { bindRealtimeServer, type RealtimeServer, type RealtimeServerConnection, type RealtimeServerHandle, } from './server/realtime';
 export { createNodeSocketIOServer as createSocketIOServer, type NodeSocketIOServerHandle as SocketIOServerHandle, type SocketIOServerConfig, } from './server/socket-io-node';
 export type { FetchComposition, FetchHandler, HandlerConfig, LoggingConfig, LogOutcome, RawRoute, RawRouteContext, ServiceDef, } from './server/types';
 //# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EACL,wBAAwB,IAAI,oBAAoB,EAChD,KAAK,wBAAwB,IAAI,oBAAoB,EACrD,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,wBAAwB,IAAI,oBAAoB,EAChD,KAAK,wBAAwB,IAAI,oBAAoB,EACrD,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC"}

package/dist/node.js

@@ -1,9 +1,10 @@
 import {
+  bindRealtimeServer,
   createHandler,
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-4fyn9f09.js";
+} from "./index-w0mec79h.js";
 import"./index-6jypn22c.js";
 import"./index-x3fcszf8.js";
 import {
@@ -55,6 +56,7 @@ export {
   createImplement,
   createHandler,
   conflict,
+  bindRealtimeServer,
   badRequest,
   appError,
   AppError

package/dist/realtime/contract.d.ts

@@ -0,0 +1,36 @@
+import type { z } from 'zod';
+export interface RealtimeEventDefinition<TArgs extends z.ZodType<unknown[]> = z.ZodType<unknown[]>, TAck extends z.ZodType | undefined = z.ZodType | undefined> {
+    args: TArgs;
+    ack?: TAck;
+}
+export type RealtimeEventRegistry = Record<string, RealtimeEventDefinition>;
+export interface RealtimeContract<TServerToClient extends RealtimeEventRegistry, TClientToServer extends RealtimeEventRegistry> {
+    serverToClient: TServerToClient;
+    clientToServer: TClientToServer;
+}
+export declare function defineRealtimeContract<const TServerToClient extends RealtimeEventRegistry, const TClientToServer extends RealtimeEventRegistry>(contract: RealtimeContract<TServerToClient, TClientToServer>): RealtimeContract<TServerToClient, TClientToServer>;
+export type RealtimeEventArguments<TDefinition extends RealtimeEventDefinition> = [
+    ...z.output<TDefinition['args']>,
+    ...(TDefinition extends {
+        ack: infer TAck extends z.ZodType;
+    } ? [(value: z.input<TAck>) => void] : [])
+];
+export type RealtimeEmitArguments<TDefinition extends RealtimeEventDefinition> = [
+    ...(z.input<TDefinition['args']> extends unknown[] ? z.input<TDefinition['args']> : never),
+    ...(TDefinition extends {
+        ack: infer TAck extends z.ZodType;
+    } ? [(value: z.output<TAck>) => void] : [])
+];
+export type RealtimeEventHandler<TDefinition extends RealtimeEventDefinition> = (...args: RealtimeEventArguments<TDefinition>) => void;
+export type InferRealtimeEventMap<TRegistry extends RealtimeEventRegistry> = {
+    [TEvent in keyof TRegistry]: RealtimeEventHandler<TRegistry[TEvent]>;
+};
+export type RealtimeRejectDirection = 'client-inbound' | 'client-outbound' | 'server-inbound' | 'server-outbound';
+export interface RealtimeRejectedEvent {
+    event: string;
+    direction: RealtimeRejectDirection;
+    phase: 'arguments' | 'acknowledgement';
+    error: z.ZodError;
+}
+export type RealtimeRejectedEventHook = (rejected: RealtimeRejectedEvent) => void | Promise<void>;
+//# sourceMappingURL=contract.d.ts.map

package/dist/realtime/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/realtime/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,MAAM,WAAW,uBAAuB,CACtC,KAAK,SAAS,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,EACzD,IAAI,SAAS,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,CAAC,CAAC,OAAO,GAAG,SAAS;IAE1D,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;AAE5E,MAAM,WAAW,gBAAgB,CAC/B,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB;IAE7C,cAAc,EAAE,eAAe,CAAC;IAChC,cAAc,EAAE,eAAe,CAAC;CACjC;AAED,wBAAgB,sBAAsB,CACpC,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,QAAQ,EAAE,gBAAgB,CAAC,eAAe,EAAE,eAAe,CAAC,sDAE7D;AAED,MAAM,MAAM,sBAAsB,CAAC,WAAW,SAAS,uBAAuB,IAAI;IAChF,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,GAAG,CAAC,WAAW,SAAS;QAAE,GAAG,EAAE,MAAM,IAAI,SAAS,CAAC,CAAC,OAAO,CAAA;KAAE,GACzD,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,GAChC,EAAE,CAAC;CACR,CAAC;AAEF,MAAM,MAAM,qBAAqB,CAAC,WAAW,SAAS,uBAAuB,IAAI;IAC/E,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,SAAS,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC;IAC1F,GAAG,CAAC,WAAW,SAAS;QAAE,GAAG,EAAE,MAAM,IAAI,SAAS,CAAC,CAAC,OAAO,CAAA;KAAE,GACzD,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,GACjC,EAAE,CAAC;CACR,CAAC;AAEF,MAAM,MAAM,oBAAoB,CAAC,WAAW,SAAS,uBAAuB,IAAI,CAC9E,GAAG,IAAI,EAAE,sBAAsB,CAAC,WAAW,CAAC,KACzC,IAAI,CAAC;AAEV,MAAM,MAAM,qBAAqB,CAAC,SAAS,SAAS,qBAAqB,IAAI;KAC1E,MAAM,IAAI,MAAM,SAAS,GAAG,oBAAoB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;CACrE,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAC/B,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,uBAAuB,CAAC;IACnC,KAAK,EAAE,WAAW,GAAG,iBAAiB,CAAC;IACvC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC;CACnB;AAED,MAAM,MAAM,yBAAyB,GAAG,CACtC,QAAQ,EAAE,qBAAqB,KAC5B,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/realtime/index.d.ts

@@ -0,0 +1,3 @@
+export { defineRealtimeContract, type InferRealtimeEventMap, type RealtimeContract, type RealtimeEmitArguments, type RealtimeEventArguments, type RealtimeEventDefinition, type RealtimeEventHandler, type RealtimeEventRegistry, type RealtimeRejectDirection, type RealtimeRejectedEvent, type RealtimeRejectedEventHook, } from './contract';
+export type { ValidatedRealtimeSocket } from './socket';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,GAC/B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC"}

package/dist/realtime/socket.d.ts

@@ -0,0 +1,17 @@
+import type { RealtimeEmitArguments, RealtimeEventHandler, RealtimeEventRegistry, RealtimeRejectDirection, RealtimeRejectedEventHook } from './contract';
+interface ValidatedRealtimeSocketOptions<TInbound extends RealtimeEventRegistry, TOutbound extends RealtimeEventRegistry> {
+    target: object;
+    inbound: TInbound;
+    outbound: TOutbound;
+    inboundDirection: RealtimeRejectDirection;
+    outboundDirection: RealtimeRejectDirection;
+    onRejected?: RealtimeRejectedEventHook;
+    subscribe?: (event: string, handler: (...args: unknown[]) => void) => () => void;
+}
+export interface ValidatedRealtimeSocket<TInbound extends RealtimeEventRegistry, TOutbound extends RealtimeEventRegistry> {
+    on<TEvent extends keyof TInbound & string>(event: TEvent, handler: RealtimeEventHandler<TInbound[TEvent]>): () => void;
+    emit<TEvent extends keyof TOutbound & string>(event: TEvent, ...args: RealtimeEmitArguments<TOutbound[TEvent]>): void;
+}
+export declare function createValidatedRealtimeSocket<const TInbound extends RealtimeEventRegistry, const TOutbound extends RealtimeEventRegistry>({ target, inbound, outbound, inboundDirection, outboundDirection, onRejected, subscribe, }: ValidatedRealtimeSocketOptions<TInbound, TOutbound>): ValidatedRealtimeSocket<TInbound, TOutbound>;
+export {};
+//# sourceMappingURL=socket.d.ts.map

package/dist/realtime/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../src/realtime/socket.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EAErB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EAEvB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAEpB,UAAU,8BAA8B,CACtC,QAAQ,SAAS,qBAAqB,EACtC,SAAS,SAAS,qBAAqB;IAEvC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,QAAQ,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;IACpB,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,iBAAiB,EAAE,uBAAuB,CAAC;IAC3C,UAAU,CAAC,EAAE,yBAAyB,CAAC;IACvC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CAClF;AAED,MAAM,WAAW,uBAAuB,CACtC,QAAQ,SAAS,qBAAqB,EACtC,SAAS,SAAS,qBAAqB;IAEvC,EAAE,CAAC,MAAM,SAAS,MAAM,QAAQ,GAAG,MAAM,EACvC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,oBAAoB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAC9C,MAAM,IAAI,CAAC;IACd,IAAI,CAAC,MAAM,SAAS,MAAM,SAAS,GAAG,MAAM,EAC1C,KAAK,EAAE,MAAM,EACb,GAAG,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAChD,IAAI,CAAC;CACT;AAmDD,wBAAgB,6BAA6B,CAC3C,KAAK,CAAC,QAAQ,SAAS,qBAAqB,EAC5C,KAAK,CAAC,SAAS,SAAS,qBAAqB,EAC7C,EACA,MAAM,EACN,OAAO,EACP,QAAQ,EACR,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,SAAS,GACV,EAAE,8BAA8B,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,uBAAuB,CAC9E,QAAQ,EACR,SAAS,CACV,CAkGA"}

package/dist/server/index.d.ts

@@ -17,6 +17,7 @@ export { type MultipartResult, parseMultipart } from './multipart';
 export { generateOpenApiDocument, type OpenApiConfig, type OpenApiDocument, type OpenApiInfo, type OpenApiServer, openApiRoute, } from './openapi';
 export { createRateLimiter, type RateLimitConfig } from './rate-limit';
 export { errorResponse, parseBody, respondJson } from './raw';
+export { bindRealtimeServer, type RealtimeServer, type RealtimeServerConnection, type RealtimeServerHandle, } from './realtime';
 export { type ClientIpOptions, extractIp, generateTraceId, getClientInfo, resolveSocketIp, resolveTraceId, } from './request';
 export { staticRoute } from './router';
 export type { SocketIOServerConfig, SocketIOServerHandle } from './socket-io';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}

package/dist/server/index.js

@@ -1,4 +1,5 @@
 import {
+  bindRealtimeServer,
   composeWebSocketHandlers,
   createHandler,
   createImplement,
@@ -9,7 +10,7 @@ import {
   socketIoLane,
   staticRoute,
   webSocketLane
-} from "../index-4fyn9f09.js";
+} from "../index-w0mec79h.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -718,6 +719,7 @@ export {
   conflict,
   composeWebSocketHandlers,
   cacheHeaders,
+  bindRealtimeServer,
   badRequest,
   appError,
   STITCH_ERROR_STATUS,

package/dist/server/realtime.d.ts

@@ -0,0 +1,22 @@
+import type { Socket, Server as SocketIOServer } from 'socket.io';
+import type { SocketEventMap } from '../browser/socket-io';
+import type { RealtimeContract, RealtimeEventRegistry, RealtimeRejectedEventHook } from '../realtime/contract';
+import { type ValidatedRealtimeSocket } from '../realtime/socket';
+export interface RealtimeServerConnection<TServerToClient extends RealtimeEventRegistry, TClientToServer extends RealtimeEventRegistry> {
+    /** Raw Socket.IO socket for handshake auth, rooms and application-owned delivery policy. */
+    raw: Socket;
+    events: ValidatedRealtimeSocket<TClientToServer, TServerToClient>;
+    to(room: string): Pick<ValidatedRealtimeSocket<RealtimeEventRegistry, TServerToClient>, 'emit'>;
+}
+export interface RealtimeServer<TServerToClient extends RealtimeEventRegistry, TClientToServer extends RealtimeEventRegistry> {
+    onConnection(handler: (connection: RealtimeServerConnection<TServerToClient, TClientToServer>) => void | Promise<void>): () => void;
+    emit: ValidatedRealtimeSocket<RealtimeEventRegistry, TServerToClient>['emit'];
+    to(room: string): Pick<ValidatedRealtimeSocket<RealtimeEventRegistry, TServerToClient>, 'emit'>;
+}
+export interface RealtimeServerHandle {
+    io: SocketIOServer<SocketEventMap, SocketEventMap>;
+}
+export declare function bindRealtimeServer<const TServerToClient extends RealtimeEventRegistry, const TClientToServer extends RealtimeEventRegistry>(contract: RealtimeContract<TServerToClient, TClientToServer>, handle: RealtimeServerHandle, options?: {
+    onRejected?: RealtimeRejectedEventHook;
+}): RealtimeServer<TServerToClient, TClientToServer>;
+//# sourceMappingURL=realtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/server/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,EAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,wBAAwB,CACvC,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB;IAE7C,4FAA4F;IAC5F,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,uBAAuB,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;IAClE,EAAE,CACA,IAAI,EAAE,MAAM,GACX,IAAI,CAAC,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,cAAc,CAC7B,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB;IAE7C,YAAY,CACV,OAAO,EAAE,CACP,UAAU,EAAE,wBAAwB,CAAC,eAAe,EAAE,eAAe,CAAC,KACnE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACxB,MAAM,IAAI,CAAC;IACd,IAAI,EAAE,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9E,EAAE,CACA,IAAI,EAAE,MAAM,GACX,IAAI,CAAC,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,cAAc,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;CACpD;AAED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,KAAK,CAAC,eAAe,SAAS,qBAAqB,EAEnD,QAAQ,EAAE,gBAAgB,CAAC,eAAe,EAAE,eAAe,CAAC,EAC5D,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,yBAAyB,CAAA;CAAO,GACvD,cAAc,CAAC,eAAe,EAAE,eAAe,CAAC,CAoClD"}

package/llms-full.txt

@@ -2799,35 +2799,61 @@ WebSocket engine; it ships thin, typed wrappers over Socket.IO and a bridge that
 syncs socket events into the TanStack Query cache. See
 [ADR 0008](../decisions/0008-thin-wrappers.md).
 
-## Typed events
+## Zod-first event contract
 
-Declare the event maps once, in the shared module — both sides import them:
+Declare wire events once in the shared module. Each `args` schema is a tuple, so
+Socket.IO's no-payload and variadic forms stay intact; `ack` describes the value
+returned through an acknowledgement callback.
 
 ```ts
 // shared/contracts.ts
-export interface ServerToClientEvents {
-  'note:created': (note: Note) => void
-  'note:deleted': (id: string) => void
-}
-export interface ClientToServerEvents {
-  'room:join': (room: string) => void
-}
+import { defineRealtimeContract } from 'stitchkit'
+import { z } from 'zod'
+
+export const realtimeContract = defineRealtimeContract({
+  serverToClient: {
+    'note:created': { args: z.tuple([NoteSchema]) },
+    'note:deleted': { args: z.tuple([z.string()]) },
+  },
+  clientToServer: {
+    'room:join': {
+      args: z.tuple([z.string()]),
+      ack: z.object({ joined: z.boolean() }),
+    },
+    ready: { args: z.tuple([]) },
+  },
+})
 ```
 
-Every `emit` and `on` on both the server and client wrapper is typed against
-these maps.
+The contract derives every event handler type and validates both directions at
+runtime. A malformed inbound tuple never reaches the application handler;
+invalid outbound data throws before Socket.IO publishes it. Rejections call the
+optional `onRejected` hook with event, direction, phase and the Zod error.
 
 ## Server — `createSocketIOServer`
 
 ```ts
-import { createServer, createSocketIOServer } from 'stitchkit/server'
+import {
+  bindRealtimeServer,
+  createServer,
+  createSocketIOServer,
+} from 'stitchkit/server'
+import { realtimeContract } from '@app/shared'
 
-const socket = await createSocketIOServer<ServerToClientEvents, ClientToServerEvents>({
+const socket = await createSocketIOServer({
   cors: { origin: 'https://app.example.com' },
 })
 
-socket.io.on('connection', (s) => {
-  s.on('room:join', (room) => s.join(room))   // rooms, handshake auth — your logic
+const realtime = bindRealtimeServer(realtimeContract, socket, {
+  onRejected: (event) => audit.realtimeRejected(event),
+})
+
+realtime.onConnection(({ raw, events, to }) => {
+  events.on('room:join', (room, acknowledge) => {
+    raw.join(room) // authorization and room membership remain application policy
+    acknowledge({ joined: true })
+    to(room).emit('note:created', note)
+  })
 })
 ```
 
@@ -2840,13 +2866,13 @@ createServer({
   rawRoutes: [socket.route],     // ready-made /socket.io/*socketPath route
 })
 
-// elsewhere — broadcast:
-socket.io.emit('note:created', note)
+// elsewhere — validated broadcast:
+realtime.emit('note:created', note)
 ```
 
 | Handle field | Purpose |
 |--------------|---------|
-| `io` | the typed Socket.IO server — attach `connection` handlers, broadcast |
+| `io` | raw Socket.IO server for middleware, handshake auth and transport ownership |
 | `websocket` | Bun WebSocket handlers — pass to `createServer({ websocket })` |
 | `route` | the `/socket.io/*socketPath` raw route — pass to `createServer({ rawRoutes })` |
 
@@ -2868,20 +2894,29 @@ precedence over the same keys in `serverOptions`. On Bun the engine-level option
 `@socket.io/bun-engine` too — so a configured `maxHttpBufferSize` actually applies
 instead of silently truncating at 1 MB.
 
-## Client — `createSocketIOClient`
+## Client — `createRealtimeClient`
 
 ```ts
-import { createSocketIOClient } from 'stitchkit'
+import { createRealtimeClient } from 'stitchkit'
+import { realtimeContract } from '@app/shared'
 
-const socket = createSocketIOClient<ServerToClientEvents, ClientToServerEvents>({
+const socket = createRealtimeClient(realtimeContract, {
   url: 'https://api.example.com',
+  retain: ['note:created'],
+  onRejected: (event) => reportClientError(event),
 })
 
 socket.connect()
 socket.on('note:created', (note) => { /* typed note */ })
-socket.emit('room:join', 'general')   // typed
+socket.emit('room:join', 'general', ({ joined }) => { /* typed + validated */ })
 ```
 
+## Low-level transport
+
+`createSocketIOClient` remains the low-level Socket.IO transport wrapper for
+schema-agnostic infrastructure. Application wire events should use
+`createRealtimeClient`; it adds the shared contract without replacing Socket.IO.
+
 ### Durable subscriptions
 
 `socket.on(...)` returns an unsubscribe and is **durable** — the handler is
@@ -2901,7 +2936,7 @@ subscribes (and on the next subscribe after a re-render). It is the pub/sub
 analogue of an MQTT *retained* message or an RxJS `BehaviorSubject`.
 
 ```ts
-const client = createSocketIOClient<ServerEvents, ClientEvents>({
+const client = createRealtimeClient(realtimeContract, {
   url,
   retain: ['presence:changed', 'job:state'],   // events to keep the last value of
 })
@@ -2938,7 +2973,7 @@ handshake with **`auth`** instead — the token reaches the server as
 // client — a function is re-read on every (re)connect, so a rotated token is
 // picked up automatically; no need to recreate the client (or lose durable
 // subscriptions). It may be async.
-const socket = createSocketIOClient<ServerToClientEvents, ClientToServerEvents>({
+const socket = createRealtimeClient(realtimeContract, {
   url: 'https://api.example.com',
   auth: () => ({ token: getAccessToken() }),
 })
@@ -5207,12 +5242,16 @@ The browser-and-server entrypoint. Re-exports everything from
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createSocketIOClient` | function | the typed Socket.IO client — [guide](../guide/realtime.md#client--createsocketioclient) |
+| `createSocketIOClient` | function | low-level typed Socket.IO transport primitive — [guide](../guide/realtime.md#low-level-transport) |
+| `defineRealtimeContract` | function | Zod-first shared Socket.IO event contract — [guide](../guide/realtime.md#zod-first-event-contract) |
+| `createRealtimeClient` | function | inferred, runtime-validated Socket.IO client — [guide](../guide/realtime.md#client--createrealtimeclient) |
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
 | `SocketIOClient` | _type_ | the client handle |
 | `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`) |
 | `SocketEventMap` | _type_ | the shape of an event map |
+| `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
+| `RealtimeClientOptions` | _type_ | transport options and the rejected-event hook for `createRealtimeClient` |
 | `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
 
@@ -5407,6 +5446,10 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createSocketIOServer` | function | the typed Socket.IO server — [guide](../guide/realtime.md#server--createsocketioserver) |
+| `bindRealtimeServer` | function | inferred, runtime-validated connection and broadcast boundary |
+| `RealtimeServer` | _type_ | validated broadcast and connection API inferred from a realtime contract |
+| `RealtimeServerConnection` | _type_ | one validated connection with raw socket access for auth and rooms |
+| `RealtimeServerHandle` | _type_ | minimal Socket.IO server handle accepted by `bindRealtimeServer` |
 | `SocketIOServerConfig` | _type_ | config for `createSocketIOServer` |
 | `SocketIOServerHandle` | _type_ | the `{ io, websocket, route }` handle |
 | `composeWebSocketHandlers` | function | compose one Bun `websocket` from N lanes — a raw binary lane beside Socket.IO ([guide](../guide/realtime.md#raw-binary-lane-bun)) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.44.1",
+  "version": "0.45.0",
   "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",