@open-mercato/events 0.4.5-develop-6bdcebbece → 0.4.5-develop-0c30cb4b11

package/AGENTS.md

@@ -90,3 +90,54 @@ Workers in `modules/events/workers/` handle async event processing. Follow the s
 - **Declaring events in a module**: `packages/core/AGENTS.md` → Events
 - **Adding subscribers in a module**: `packages/core/AGENTS.md` → Events → Event Subscribers
 - **Queue worker contract**: `packages/queue/AGENTS.md`
+
+## DOM Event Bridge (SSE)
+
+The DOM Event Bridge streams server-side events to the browser via Server-Sent Events (SSE).
+
+### How It Works
+
+1. Module declares events with `clientBroadcast: true` in `events.ts`
+2. SSE endpoint at `/api/events/stream` subscribes to the event bus
+3. Client-side `eventBridge.ts` connects via `EventSource` with auto-reconnect
+4. Events are dispatched as `om:event` CustomEvents on `window`
+5. Widgets/components listen via `useAppEvent(pattern, handler)` hook
+
+### Enabling Broadcast on Events
+
+In your module's `events.ts`:
+```typescript
+const events = [
+  { id: 'mymod.entity.created', label: 'Created', category: 'crud', clientBroadcast: true },
+] as const
+```
+
+### Consuming Events in Components
+
+```typescript
+import { useAppEvent } from '@open-mercato/ui/backend/injection/useAppEvent'
+
+// Wildcard: listen to all events from a module
+useAppEvent('mymod.*', (event) => {
+  console.log(event.id, event.payload)
+}, [])
+
+// Exact match
+useAppEvent('mymod.entity.created', (event) => {
+  // refresh data
+}, [])
+```
+
+### Key Rules
+
+- Events are server-filtered by audience before SSE send:
+  - Tenant: `tenantId` must match
+  - Organization: `organizationId` or `organizationIds` must match selected organization
+  - Recipient user: `recipientUserId` or `recipientUserIds` must include connection user
+  - Recipient role: `recipientRoleId` or `recipientRoleIds` must intersect connection roles
+- Missing `tenantId` in event payload means no delivery
+- SSE sends heartbeats every 30s; client auto-reconnects if no heartbeat within 45s
+- Max payload size is 4096 bytes per event
+- Client deduplicates events within a 500ms window
+- `isBroadcastEvent(eventId)` checks if an event has `clientBroadcast: true`
+- The `useEventBridge()` hook must be mounted once in the app shell to start receiving events

package/dist/bus.js

@@ -1,6 +1,23 @@
 import { createQueue } from "@open-mercato/queue";
 import { getRedisUrl } from "@open-mercato/shared/lib/redis/connection";
 const EVENTS_QUEUE_NAME = "events";
+const GLOBAL_EVENT_TAPS_KEY = "__openMercatoEventBusGlobalTaps__";
+function getGlobalEventTaps() {
+  const existing = globalThis[GLOBAL_EVENT_TAPS_KEY];
+  if (existing instanceof Set) {
+    return existing;
+  }
+  const created = /* @__PURE__ */ new Set();
+  globalThis[GLOBAL_EVENT_TAPS_KEY] = created;
+  return created;
+}
+function registerGlobalEventTap(handler) {
+  const taps = getGlobalEventTaps();
+  taps.add(handler);
+  return () => {
+    taps.delete(handler);
+  };
+}
 function matchEventPattern(eventName, pattern) {
   if (pattern === "*") return true;
   if (pattern === eventName) return true;
@@ -53,6 +70,14 @@ function createEventBus(opts) {
     }
   }
   async function emit(event, payload, options) {
+    const taps = getGlobalEventTaps();
+    for (const tap of taps) {
+      try {
+        await Promise.resolve(tap(event, payload, options));
+      } catch (error) {
+        console.error(`[events] Global tap error for "${event}":`, error);
+      }
+    }
     await deliver(event, payload);
     if (options?.persistent) {
       const q = getQueue();
@@ -74,6 +99,7 @@ function createEventBus(opts) {
   };
 }
 export {
-  createEventBus
+  createEventBus,
+  registerGlobalEventTap
 };
 //# sourceMappingURL=bus.js.map

package/dist/bus.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/bus.ts"],
-  "sourcesContent": ["import { createQueue } from '@open-mercato/queue'\nimport type { Queue } from '@open-mercato/queue'\nimport { getRedisUrl } from '@open-mercato/shared/lib/redis/connection'\nimport type {\n  EventBus,\n  CreateBusOptions,\n  SubscriberHandler,\n  SubscriberDescriptor,\n  EventPayload,\n  EmitOptions,\n} from './types'\n\n/** Queue name for persistent events */\nconst EVENTS_QUEUE_NAME = 'events'\n\n/**\n * Match an event name against a pattern.\n *\n * Supports:\n * - Exact match: `customers.people.created`\n * - Wildcard `*` matches single segment: `customers.*` matches `customers.people` but not `customers.people.created`\n * - Global wildcard: `*` alone matches all events\n *\n * @param eventName - The actual event name\n * @param pattern - The pattern to match against\n * @returns True if the event matches the pattern\n */\nfunction matchEventPattern(eventName: string, pattern: string): boolean {\n  // Global wildcard matches all events\n  if (pattern === '*') return true\n\n  // Exact match\n  if (pattern === eventName) return true\n\n  // No wildcards in pattern means we need exact match, which already failed\n  if (!pattern.includes('*')) return false\n\n  // Convert pattern to regex:\n  // - Escape regex special chars (except *)\n  // - Replace * with [^.]+ (match one or more non-dot chars)\n  const regexPattern = pattern\n    .replace(/[.+^${}()|[\\]\\\\]/g, '\\\\$&')\n    .replace(/\\*/g, '[^.]+')\n  const regex = new RegExp(`^${regexPattern}$`)\n  return regex.test(eventName)\n}\n\n/** Job data structure for queued events */\ntype EventJobData = {\n  event: string\n  payload: EventPayload\n}\n\n/**\n * Creates an event bus instance.\n *\n * The event bus provides:\n * - In-memory event delivery to registered handlers\n * - Optional persistence via the queue package when `persistent: true`\n *\n * @param opts - Configuration options\n * @returns An EventBus instance\n *\n * @example\n * ```typescript\n * const bus = createEventBus({\n *   resolve: container.resolve.bind(container),\n *   queueStrategy: 'local', // or 'async' for BullMQ\n * })\n *\n * // Register a handler\n * bus.on('user.created', async (payload, ctx) => {\n *   const userService = ctx.resolve('userService')\n *   await userService.sendWelcomeEmail(payload.userId)\n * })\n *\n * // Emit an event (immediate delivery)\n * await bus.emit('user.created', { userId: '123' })\n *\n * // Emit with persistence (for async worker processing)\n * await bus.emit('order.placed', { orderId: '456' }, { persistent: true })\n * ```\n */\nexport function createEventBus(opts: CreateBusOptions): EventBus {\n  // In-memory listeners for immediate event delivery\n  const listeners = new Map<string, Set<SubscriberHandler>>()\n\n  // Determine queue strategy from options or environment\n  const queueStrategy = opts.queueStrategy ??\n    (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  // Lazy-initialized queue for persistent events\n  let queue: Queue<EventJobData> | null = null\n\n  /**\n   * Gets or creates the queue instance for persistent events.\n   */\n  function getQueue(): Queue<EventJobData> {\n    if (!queue) {\n      if (queueStrategy === 'async') {\n        queue = createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {\n          connection: { url: getRedisUrl('QUEUE') }\n        })\n      } else {\n        queue = createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'local')\n      }\n    }\n    return queue\n  }\n\n  /**\n   * Delivers an event to all registered in-memory handlers.\n   * Supports wildcard pattern matching for event patterns.\n   */\n  async function deliver(event: string, payload: EventPayload): Promise<void> {\n    // Check all registered patterns (including wildcards)\n    for (const [pattern, handlers] of listeners) {\n      if (!matchEventPattern(event, pattern)) continue\n      if (!handlers || handlers.size === 0) continue\n\n      for (const handler of handlers) {\n        try {\n          // Pass eventName in context for wildcard handlers\n          await Promise.resolve(handler(payload, {\n            resolve: opts.resolve,\n            eventName: event,\n          }))\n        } catch (error) {\n          console.error(`[events] Handler error for \"${event}\" (pattern: \"${pattern}\"):`, error)\n        }\n      }\n    }\n  }\n\n  /**\n   * Registers a handler for an event.\n   */\n  function on(event: string, handler: SubscriberHandler): void {\n    if (!listeners.has(event)) {\n      listeners.set(event, new Set())\n    }\n    listeners.get(event)!.add(handler)\n  }\n\n  /**\n   * Registers multiple module subscribers at once.\n   */\n  function registerModuleSubscribers(subs: SubscriberDescriptor[]): void {\n    for (const sub of subs) {\n      on(sub.event, sub.handler)\n    }\n  }\n\n  /**\n   * Emits an event to all registered handlers.\n   *\n   * If `persistent: true`, also enqueues the event for async processing.\n   */\n  async function emit(\n    event: string,\n    payload: EventPayload,\n    options?: EmitOptions\n  ): Promise<void> {\n    // Always deliver to in-memory handlers first\n    await deliver(event, payload)\n\n    // If persistent, also enqueue for async processing\n    if (options?.persistent) {\n      const q = getQueue()\n      await q.enqueue({ event, payload })\n    }\n  }\n\n  /**\n   * Clears all events from the persistent queue.\n   */\n  async function clearQueue(): Promise<{ removed: number }> {\n    const q = getQueue()\n    return q.clear()\n  }\n\n  // Backward compatibility alias\n  const emitEvent = emit\n\n  return {\n    emit,\n    emitEvent, // Alias for backward compatibility\n    on,\n    registerModuleSubscribers,\n    clearQueue,\n  }\n}\n"],
-  "mappings": "AAAA,SAAS,mBAAmB;AAE5B,SAAS,mBAAmB;AAW5B,MAAM,oBAAoB;AAc1B,SAAS,kBAAkB,WAAmB,SAA0B;AAEtE,MAAI,YAAY,IAAK,QAAO;AAG5B,MAAI,YAAY,UAAW,QAAO;AAGlC,MAAI,CAAC,QAAQ,SAAS,GAAG,EAAG,QAAO;AAKnC,QAAM,eAAe,QAClB,QAAQ,qBAAqB,MAAM,EACnC,QAAQ,OAAO,OAAO;AACzB,QAAM,QAAQ,IAAI,OAAO,IAAI,YAAY,GAAG;AAC5C,SAAO,MAAM,KAAK,SAAS;AAC7B;AAsCO,SAAS,eAAe,MAAkC;AAE/D,QAAM,YAAY,oBAAI,IAAoC;AAG1D,QAAM,gBAAgB,KAAK,kBACxB,QAAQ,IAAI,mBAAmB,UAAU,UAAU;AAGtD,MAAI,QAAoC;AAKxC,WAAS,WAAgC;AACvC,QAAI,CAAC,OAAO;AACV,UAAI,kBAAkB,SAAS;AAC7B,gBAAQ,YAA0B,mBAAmB,SAAS;AAAA,UAC5D,YAAY,EAAE,KAAK,YAAY,OAAO,EAAE;AAAA,QAC1C,CAAC;AAAA,MACH,OAAO;AACL,gBAAQ,YAA0B,mBAAmB,OAAO;AAAA,MAC9D;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAMA,iBAAe,QAAQ,OAAe,SAAsC;AAE1E,eAAW,CAAC,SAAS,QAAQ,KAAK,WAAW;AAC3C,UAAI,CAAC,kBAAkB,OAAO,OAAO,EAAG;AACxC,UAAI,CAAC,YAAY,SAAS,SAAS,EAAG;AAEtC,iBAAW,WAAW,UAAU;AAC9B,YAAI;AAEF,gBAAM,QAAQ,QAAQ,QAAQ,SAAS;AAAA,YACrC,SAAS,KAAK;AAAA,YACd,WAAW;AAAA,UACb,CAAC,CAAC;AAAA,QACJ,SAAS,OAAO;AACd,kBAAQ,MAAM,+BAA+B,KAAK,gBAAgB,OAAO,OAAO,KAAK;AAAA,QACvF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAKA,WAAS,GAAG,OAAe,SAAkC;AAC3D,QAAI,CAAC,UAAU,IAAI,KAAK,GAAG;AACzB,gBAAU,IAAI,OAAO,oBAAI,IAAI,CAAC;AAAA,IAChC;AACA,cAAU,IAAI,KAAK,EAAG,IAAI,OAAO;AAAA,EACnC;AAKA,WAAS,0BAA0B,MAAoC;AACrE,eAAW,OAAO,MAAM;AACtB,SAAG,IAAI,OAAO,IAAI,OAAO;AAAA,IAC3B;AAAA,EACF;AAOA,iBAAe,KACb,OACA,SACA,SACe;AAEf,UAAM,QAAQ,OAAO,OAAO;AAG5B,QAAI,SAAS,YAAY;AACvB,YAAM,IAAI,SAAS;AACnB,YAAM,EAAE,QAAQ,EAAE,OAAO,QAAQ,CAAC;AAAA,IACpC;AAAA,EACF;AAKA,iBAAe,aAA2C;AACxD,UAAM,IAAI,SAAS;AACnB,WAAO,EAAE,MAAM;AAAA,EACjB;AAGA,QAAM,YAAY;AAElB,SAAO;AAAA,IACL;AAAA,IACA;AAAA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;",
+  "sourcesContent": ["import { createQueue } from '@open-mercato/queue'\nimport type { Queue } from '@open-mercato/queue'\nimport { getRedisUrl } from '@open-mercato/shared/lib/redis/connection'\nimport type {\n  EventBus,\n  CreateBusOptions,\n  SubscriberHandler,\n  SubscriberDescriptor,\n  EventPayload,\n  EmitOptions,\n} from './types'\n\n/** Queue name for persistent events */\nconst EVENTS_QUEUE_NAME = 'events'\n\ntype GlobalEventTap = (event: string, payload: EventPayload, options?: EmitOptions) => void | Promise<void>\nconst GLOBAL_EVENT_TAPS_KEY = '__openMercatoEventBusGlobalTaps__'\n\nfunction getGlobalEventTaps(): Set<GlobalEventTap> {\n  const existing = (globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY]\n  if (existing instanceof Set) {\n    return existing as Set<GlobalEventTap>\n  }\n  const created = new Set<GlobalEventTap>()\n  ;(globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY] = created\n  return created\n}\n\nexport function registerGlobalEventTap(handler: GlobalEventTap): () => void {\n  const taps = getGlobalEventTaps()\n  taps.add(handler)\n  return () => {\n    taps.delete(handler)\n  }\n}\n\n/**\n * Match an event name against a pattern.\n *\n * Supports:\n * - Exact match: `customers.people.created`\n * - Wildcard `*` matches single segment: `customers.*` matches `customers.people` but not `customers.people.created`\n * - Global wildcard: `*` alone matches all events\n *\n * @param eventName - The actual event name\n * @param pattern - The pattern to match against\n * @returns True if the event matches the pattern\n */\nfunction matchEventPattern(eventName: string, pattern: string): boolean {\n  // Global wildcard matches all events\n  if (pattern === '*') return true\n\n  // Exact match\n  if (pattern === eventName) return true\n\n  // No wildcards in pattern means we need exact match, which already failed\n  if (!pattern.includes('*')) return false\n\n  // Convert pattern to regex:\n  // - Escape regex special chars (except *)\n  // - Replace * with [^.]+ (match one or more non-dot chars)\n  const regexPattern = pattern\n    .replace(/[.+^${}()|[\\]\\\\]/g, '\\\\$&')\n    .replace(/\\*/g, '[^.]+')\n  const regex = new RegExp(`^${regexPattern}$`)\n  return regex.test(eventName)\n}\n\n/** Job data structure for queued events */\ntype EventJobData = {\n  event: string\n  payload: EventPayload\n}\n\n/**\n * Creates an event bus instance.\n *\n * The event bus provides:\n * - In-memory event delivery to registered handlers\n * - Optional persistence via the queue package when `persistent: true`\n *\n * @param opts - Configuration options\n * @returns An EventBus instance\n *\n * @example\n * ```typescript\n * const bus = createEventBus({\n *   resolve: container.resolve.bind(container),\n *   queueStrategy: 'local', // or 'async' for BullMQ\n * })\n *\n * // Register a handler\n * bus.on('user.created', async (payload, ctx) => {\n *   const userService = ctx.resolve('userService')\n *   await userService.sendWelcomeEmail(payload.userId)\n * })\n *\n * // Emit an event (immediate delivery)\n * await bus.emit('user.created', { userId: '123' })\n *\n * // Emit with persistence (for async worker processing)\n * await bus.emit('order.placed', { orderId: '456' }, { persistent: true })\n * ```\n */\nexport function createEventBus(opts: CreateBusOptions): EventBus {\n  // In-memory listeners for immediate event delivery\n  const listeners = new Map<string, Set<SubscriberHandler>>()\n\n  // Determine queue strategy from options or environment\n  const queueStrategy = opts.queueStrategy ??\n    (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  // Lazy-initialized queue for persistent events\n  let queue: Queue<EventJobData> | null = null\n\n  /**\n   * Gets or creates the queue instance for persistent events.\n   */\n  function getQueue(): Queue<EventJobData> {\n    if (!queue) {\n      if (queueStrategy === 'async') {\n        queue = createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'async', {\n          connection: { url: getRedisUrl('QUEUE') }\n        })\n      } else {\n        queue = createQueue<EventJobData>(EVENTS_QUEUE_NAME, 'local')\n      }\n    }\n    return queue\n  }\n\n  /**\n   * Delivers an event to all registered in-memory handlers.\n   * Supports wildcard pattern matching for event patterns.\n   */\n  async function deliver(event: string, payload: EventPayload): Promise<void> {\n    // Check all registered patterns (including wildcards)\n    for (const [pattern, handlers] of listeners) {\n      if (!matchEventPattern(event, pattern)) continue\n      if (!handlers || handlers.size === 0) continue\n\n      for (const handler of handlers) {\n        try {\n          // Pass eventName in context for wildcard handlers\n          await Promise.resolve(handler(payload, {\n            resolve: opts.resolve,\n            eventName: event,\n          }))\n        } catch (error) {\n          console.error(`[events] Handler error for \"${event}\" (pattern: \"${pattern}\"):`, error)\n        }\n      }\n    }\n  }\n\n  /**\n   * Registers a handler for an event.\n   */\n  function on(event: string, handler: SubscriberHandler): void {\n    if (!listeners.has(event)) {\n      listeners.set(event, new Set())\n    }\n    listeners.get(event)!.add(handler)\n  }\n\n  /**\n   * Registers multiple module subscribers at once.\n   */\n  function registerModuleSubscribers(subs: SubscriberDescriptor[]): void {\n    for (const sub of subs) {\n      on(sub.event, sub.handler)\n    }\n  }\n\n  /**\n   * Emits an event to all registered handlers.\n   *\n   * If `persistent: true`, also enqueues the event for async processing.\n   */\n  async function emit(\n    event: string,\n    payload: EventPayload,\n    options?: EmitOptions\n  ): Promise<void> {\n    const taps = getGlobalEventTaps()\n    for (const tap of taps) {\n      try {\n        await Promise.resolve(tap(event, payload, options))\n      } catch (error) {\n        console.error(`[events] Global tap error for \"${event}\":`, error)\n      }\n    }\n\n    // Always deliver to in-memory handlers first\n    await deliver(event, payload)\n\n    // If persistent, also enqueue for async processing\n    if (options?.persistent) {\n      const q = getQueue()\n      await q.enqueue({ event, payload })\n    }\n  }\n\n  /**\n   * Clears all events from the persistent queue.\n   */\n  async function clearQueue(): Promise<{ removed: number }> {\n    const q = getQueue()\n    return q.clear()\n  }\n\n  // Backward compatibility alias\n  const emitEvent = emit\n\n  return {\n    emit,\n    emitEvent, // Alias for backward compatibility\n    on,\n    registerModuleSubscribers,\n    clearQueue,\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/modules/events/api/stream/route.js

@@ -0,0 +1,214 @@
+import { resolveRequestContext } from "@open-mercato/shared/lib/api/context";
+import { isBroadcastEvent } from "@open-mercato/shared/modules/events";
+import { registerGlobalEventTap } from "../../../../bus.js";
+const metadata = {
+  GET: { requireAuth: true }
+};
+const HEARTBEAT_INTERVAL_MS = 3e4;
+const MAX_PAYLOAD_BYTES = 4096;
+function collectStringValues(input) {
+  if (!Array.isArray(input)) return [];
+  const values = [];
+  for (const value of input) {
+    if (typeof value !== "string") continue;
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    values.push(trimmed);
+  }
+  return values;
+}
+function normalizeAudience(data) {
+  const tenantId = typeof data.tenantId === "string" ? data.tenantId : null;
+  const organizationScopes = /* @__PURE__ */ new Set();
+  if (typeof data.organizationId === "string" && data.organizationId.trim().length > 0) {
+    organizationScopes.add(data.organizationId.trim());
+  }
+  for (const organizationId of collectStringValues(data.organizationIds)) {
+    organizationScopes.add(organizationId);
+  }
+  const recipientUserScopes = /* @__PURE__ */ new Set();
+  if (typeof data.recipientUserId === "string" && data.recipientUserId.trim().length > 0) {
+    recipientUserScopes.add(data.recipientUserId.trim());
+  }
+  for (const userId of collectStringValues(data.recipientUserIds)) {
+    recipientUserScopes.add(userId);
+  }
+  const recipientRoleScopes = /* @__PURE__ */ new Set();
+  if (typeof data.recipientRoleId === "string" && data.recipientRoleId.trim().length > 0) {
+    recipientRoleScopes.add(data.recipientRoleId.trim());
+  }
+  for (const roleId of collectStringValues(data.recipientRoleIds)) {
+    recipientRoleScopes.add(roleId);
+  }
+  return {
+    tenantId,
+    organizationScopes: Array.from(organizationScopes),
+    recipientUserScopes: Array.from(recipientUserScopes),
+    recipientRoleScopes: Array.from(recipientRoleScopes)
+  };
+}
+function matchesAudience(conn, audience) {
+  if (!audience.tenantId) return false;
+  if (conn.tenantId !== audience.tenantId) return false;
+  if (audience.organizationScopes.length > 0) {
+    if (!conn.organizationId) return false;
+    if (!audience.organizationScopes.includes(conn.organizationId)) return false;
+  }
+  if (audience.recipientUserScopes.length > 0 && !audience.recipientUserScopes.includes(conn.userId)) {
+    return false;
+  }
+  if (audience.recipientRoleScopes.length > 0) {
+    const roleMatched = conn.roleIds.some((roleId) => audience.recipientRoleScopes.includes(roleId));
+    if (!roleMatched) return false;
+  }
+  return true;
+}
+const connections = /* @__PURE__ */ new Set();
+let globalTapRegistered = false;
+function buildSsePayload(eventName, data, organizationId) {
+  return JSON.stringify({
+    id: eventName,
+    payload: data,
+    timestamp: Date.now(),
+    organizationId
+  });
+}
+function buildTruncatedPayload(eventName, data, organizationId) {
+  const entityRef = {
+    truncated: true
+  };
+  if (typeof data.id === "string" && data.id.trim().length > 0) {
+    entityRef.id = data.id.trim();
+  }
+  if (typeof data.entityId === "string" && data.entityId.trim().length > 0) {
+    entityRef.entityId = data.entityId.trim();
+  }
+  if (typeof data.entityType === "string" && data.entityType.trim().length > 0) {
+    entityRef.entityType = data.entityType.trim();
+  }
+  return JSON.stringify({
+    id: eventName,
+    payload: entityRef,
+    timestamp: Date.now(),
+    organizationId
+  });
+}
+function ensureGlobalTapSubscription() {
+  if (globalTapRegistered) return;
+  globalTapRegistered = true;
+  registerGlobalEventTap(async (eventName, payload) => {
+    if (!eventName || connections.size === 0) return;
+    if (!isBroadcastEvent(eventName)) return;
+    const data = payload ?? {};
+    const audience = normalizeAudience(data);
+    const organizationId = audience.organizationScopes[0] ?? "";
+    let ssePayload = buildSsePayload(eventName, data, organizationId);
+    if (new TextEncoder().encode(ssePayload).length > MAX_PAYLOAD_BYTES) {
+      ssePayload = buildTruncatedPayload(eventName, data, organizationId);
+      if (new TextEncoder().encode(ssePayload).length > MAX_PAYLOAD_BYTES) {
+        console.warn(`[events:stream] Event ${eventName} payload exceeds ${MAX_PAYLOAD_BYTES} bytes, skipping`);
+        return;
+      }
+    }
+    for (const conn of connections) {
+      if (!matchesAudience(conn, audience)) continue;
+      try {
+        conn.send(ssePayload);
+      } catch {
+      }
+    }
+  });
+}
+async function GET(req) {
+  const { ctx } = await resolveRequestContext(req);
+  if (!ctx.auth?.tenantId || !ctx.auth?.sub) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+  const tenantId = ctx.auth.tenantId;
+  const organizationId = ctx.selectedOrganizationId ?? ctx.auth.orgId ?? null;
+  const userId = ctx.auth.sub;
+  const roleIds = Array.isArray(ctx.auth.roles) ? ctx.auth.roles.filter((role) => typeof role === "string" && role.trim().length > 0) : [];
+  ensureGlobalTapSubscription();
+  const encoder = new TextEncoder();
+  let heartbeatTimer = null;
+  let connection = null;
+  const stream = new ReadableStream({
+    start(controller) {
+      const send = (data) => {
+        controller.enqueue(encoder.encode(`data: ${data}
+
+`));
+      };
+      connection = {
+        tenantId,
+        organizationId,
+        userId,
+        roleIds,
+        send,
+        close: () => controller.close()
+      };
+      connections.add(connection);
+      heartbeatTimer = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(":heartbeat\n\n"));
+        } catch {
+        }
+      }, HEARTBEAT_INTERVAL_MS);
+    },
+    cancel() {
+      cleanup();
+    }
+  });
+  function cleanup() {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    if (connection) {
+      connections.delete(connection);
+      connection = null;
+    }
+  }
+  req.signal.addEventListener("abort", cleanup);
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no"
+    }
+  });
+}
+const openApi = {
+  GET: {
+    summary: "Subscribe to server events via SSE (DOM Event Bridge)",
+    description: "Long-lived SSE connection that receives server-side events marked with clientBroadcast: true. Events are server-filtered by tenant, organization, recipient user, and recipient role.",
+    tags: ["Events"],
+    responses: {
+      200: {
+        description: "Event stream (text/event-stream)",
+        content: {
+          "text/event-stream": {
+            schema: {
+              type: "object",
+              properties: {
+                id: { type: "string", description: "Event identifier (e.g., example.todo.created)" },
+                payload: { type: "object", description: "Event-specific data" },
+                timestamp: { type: "number", description: "Server timestamp (ms since epoch)" },
+                organizationId: { type: "string", description: "Organization scope" }
+              }
+            }
+          }
+        }
+      },
+      401: { description: "Not authenticated" }
+    }
+  }
+};
+export {
+  GET,
+  metadata,
+  openApi
+};
+//# sourceMappingURL=route.js.map

package/dist/modules/events/api/stream/route.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/modules/events/api/stream/route.ts"],
+  "sourcesContent": ["/**\n * SSE Event Stream \u2014 DOM Event Bridge\n *\n * Server-Sent Events endpoint that bridges server-side events to the browser.\n * Only events with `clientBroadcast: true` in their EventDefinition are sent.\n * Events are scoped to the authenticated user's tenant.\n *\n * Client consumer: `packages/ui/src/backend/injection/eventBridge.ts`\n */\n\nimport { resolveRequestContext } from '@open-mercato/shared/lib/api/context'\nimport { isBroadcastEvent } from '@open-mercato/shared/modules/events'\nimport { registerGlobalEventTap } from '../../../../bus'\n\nexport const metadata = {\n  GET: { requireAuth: true },\n}\n\nconst HEARTBEAT_INTERVAL_MS = 30_000\nconst MAX_PAYLOAD_BYTES = 4096\n\ntype SseConnection = {\n  tenantId: string\n  organizationId: string | null\n  userId: string\n  roleIds: string[]\n  send: (data: string) => void\n  close: () => void\n}\n\nfunction collectStringValues(input: unknown): string[] {\n  if (!Array.isArray(input)) return []\n  const values: string[] = []\n  for (const value of input) {\n    if (typeof value !== 'string') continue\n    const trimmed = value.trim()\n    if (!trimmed) continue\n    values.push(trimmed)\n  }\n  return values\n}\n\nfunction normalizeAudience(data: Record<string, unknown>): {\n  tenantId: string | null\n  organizationScopes: string[]\n  recipientUserScopes: string[]\n  recipientRoleScopes: string[]\n} {\n  const tenantId = typeof data.tenantId === 'string' ? data.tenantId : null\n  const organizationScopes = new Set<string>()\n  if (typeof data.organizationId === 'string' && data.organizationId.trim().length > 0) {\n    organizationScopes.add(data.organizationId.trim())\n  }\n  for (const organizationId of collectStringValues(data.organizationIds)) {\n    organizationScopes.add(organizationId)\n  }\n\n  const recipientUserScopes = new Set<string>()\n  if (typeof data.recipientUserId === 'string' && data.recipientUserId.trim().length > 0) {\n    recipientUserScopes.add(data.recipientUserId.trim())\n  }\n  for (const userId of collectStringValues(data.recipientUserIds)) {\n    recipientUserScopes.add(userId)\n  }\n\n  const recipientRoleScopes = new Set<string>()\n  if (typeof data.recipientRoleId === 'string' && data.recipientRoleId.trim().length > 0) {\n    recipientRoleScopes.add(data.recipientRoleId.trim())\n  }\n  for (const roleId of collectStringValues(data.recipientRoleIds)) {\n    recipientRoleScopes.add(roleId)\n  }\n\n  return {\n    tenantId,\n    organizationScopes: Array.from(organizationScopes),\n    recipientUserScopes: Array.from(recipientUserScopes),\n    recipientRoleScopes: Array.from(recipientRoleScopes),\n  }\n}\n\nfunction matchesAudience(conn: SseConnection, audience: ReturnType<typeof normalizeAudience>): boolean {\n  if (!audience.tenantId) return false\n  if (conn.tenantId !== audience.tenantId) return false\n\n  if (audience.organizationScopes.length > 0) {\n    if (!conn.organizationId) return false\n    if (!audience.organizationScopes.includes(conn.organizationId)) return false\n  }\n\n  if (audience.recipientUserScopes.length > 0 && !audience.recipientUserScopes.includes(conn.userId)) {\n    return false\n  }\n\n  if (audience.recipientRoleScopes.length > 0) {\n    const roleMatched = conn.roleIds.some((roleId) => audience.recipientRoleScopes.includes(roleId))\n    if (!roleMatched) return false\n  }\n\n  return true\n}\n\n/**\n * Global connection registry.\n * All active SSE connections are tracked here.\n * The event bus subscriber iterates this set on each broadcast event.\n */\nconst connections = new Set<SseConnection>()\n\nlet globalTapRegistered = false\n\nfunction buildSsePayload(eventName: string, data: Record<string, unknown>, organizationId: string): string {\n  return JSON.stringify({\n    id: eventName,\n    payload: data,\n    timestamp: Date.now(),\n    organizationId,\n  })\n}\n\nfunction buildTruncatedPayload(eventName: string, data: Record<string, unknown>, organizationId: string): string {\n  const entityRef: Record<string, unknown> = {\n    truncated: true,\n  }\n  if (typeof data.id === 'string' && data.id.trim().length > 0) {\n    entityRef.id = data.id.trim()\n  }\n  if (typeof data.entityId === 'string' && data.entityId.trim().length > 0) {\n    entityRef.entityId = data.entityId.trim()\n  }\n  if (typeof data.entityType === 'string' && data.entityType.trim().length > 0) {\n    entityRef.entityType = data.entityType.trim()\n  }\n  return JSON.stringify({\n    id: eventName,\n    payload: entityRef,\n    timestamp: Date.now(),\n    organizationId,\n  })\n}\n\n/**\n * Ensure a process-wide event tap is registered (once).\n * This captures emits from all request-scoped EventBus instances.\n */\nfunction ensureGlobalTapSubscription(): void {\n  if (globalTapRegistered) return\n  globalTapRegistered = true\n\n  registerGlobalEventTap(async (eventName, payload) => {\n    if (!eventName || connections.size === 0) return\n\n    // Only bridge events with clientBroadcast: true\n    if (!isBroadcastEvent(eventName)) return\n\n    const data = (payload ?? {}) as Record<string, unknown>\n    const audience = normalizeAudience(data)\n\n    const organizationId = audience.organizationScopes[0] ?? ''\n    let ssePayload = buildSsePayload(eventName, data, organizationId)\n\n    // Enforce max payload size\n    if (new TextEncoder().encode(ssePayload).length > MAX_PAYLOAD_BYTES) {\n      ssePayload = buildTruncatedPayload(eventName, data, organizationId)\n      if (new TextEncoder().encode(ssePayload).length > MAX_PAYLOAD_BYTES) {\n        console.warn(`[events:stream] Event ${eventName} payload exceeds ${MAX_PAYLOAD_BYTES} bytes, skipping`)\n        return\n      }\n    }\n\n    for (const conn of connections) {\n      if (!matchesAudience(conn, audience)) continue\n\n      try {\n        conn.send(ssePayload)\n      } catch {\n        // Connection may have been closed; cleanup happens via abort handler\n      }\n    }\n  })\n}\n\nexport async function GET(req: Request): Promise<Response> {\n  const { ctx } = await resolveRequestContext(req)\n\n  if (!ctx.auth?.tenantId || !ctx.auth?.sub) {\n    return new Response('Unauthorized', { status: 401 })\n  }\n\n  const tenantId = ctx.auth.tenantId\n  const organizationId = (ctx.selectedOrganizationId as string) ?? ctx.auth.orgId ?? null\n  const userId = ctx.auth.sub\n  const roleIds = Array.isArray(ctx.auth.roles)\n    ? ctx.auth.roles.filter((role): role is string => typeof role === 'string' && role.trim().length > 0)\n    : []\n\n  ensureGlobalTapSubscription()\n\n  const encoder = new TextEncoder()\n  let heartbeatTimer: ReturnType<typeof setInterval> | null = null\n  let connection: SseConnection | null = null\n\n  const stream = new ReadableStream({\n    start(controller) {\n      const send = (data: string) => {\n        controller.enqueue(encoder.encode(`data: ${data}\\n\\n`))\n      }\n\n      connection = {\n        tenantId,\n        organizationId,\n        userId,\n        roleIds,\n        send,\n        close: () => controller.close(),\n      }\n      connections.add(connection)\n\n      // Start heartbeat to keep connection alive\n      heartbeatTimer = setInterval(() => {\n        try {\n          controller.enqueue(encoder.encode(':heartbeat\\n\\n'))\n        } catch {\n          // Stream may have been closed\n        }\n      }, HEARTBEAT_INTERVAL_MS)\n    },\n    cancel() {\n      cleanup()\n    },\n  })\n\n  function cleanup() {\n    if (heartbeatTimer) {\n      clearInterval(heartbeatTimer)\n      heartbeatTimer = null\n    }\n    if (connection) {\n      connections.delete(connection)\n      connection = null\n    }\n  }\n\n  // Clean up when client disconnects\n  req.signal.addEventListener('abort', cleanup)\n\n  return new Response(stream, {\n    status: 200,\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache, no-transform',\n      'Connection': 'keep-alive',\n      'X-Accel-Buffering': 'no',\n    },\n  })\n}\n\nexport const openApi = {\n  GET: {\n    summary: 'Subscribe to server events via SSE (DOM Event Bridge)',\n    description: 'Long-lived SSE connection that receives server-side events marked with clientBroadcast: true. Events are server-filtered by tenant, organization, recipient user, and recipient role.',\n    tags: ['Events'],\n    responses: {\n      200: {\n        description: 'Event stream (text/event-stream)',\n        content: {\n          'text/event-stream': {\n            schema: {\n              type: 'object',\n              properties: {\n                id: { type: 'string', description: 'Event identifier (e.g., example.todo.created)' },\n                payload: { type: 'object', description: 'Event-specific data' },\n                timestamp: { type: 'number', description: 'Server timestamp (ms since epoch)' },\n                organizationId: { type: 'string', description: 'Organization scope' },\n              },\n            },\n          },\n        },\n      },\n      401: { description: 'Not authenticated' },\n    },\n  },\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/events",
-  "version": "0.4.5-develop-6bdcebbece",
+  "version": "0.4.5-develop-0c30cb4b11",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -32,7 +32,7 @@
     }
   },
   "dependencies": {
-    "@open-mercato/queue": "0.4.5-develop-6bdcebbece"
+    "@open-mercato/queue": "0.4.5-develop-0c30cb4b11"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",

package/src/bus.ts

@@ -13,6 +13,27 @@ import type {
 /** Queue name for persistent events */
 const EVENTS_QUEUE_NAME = 'events'
 
+type GlobalEventTap = (event: string, payload: EventPayload, options?: EmitOptions) => void | Promise<void>
+const GLOBAL_EVENT_TAPS_KEY = '__openMercatoEventBusGlobalTaps__'
+
+function getGlobalEventTaps(): Set<GlobalEventTap> {
+  const existing = (globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY]
+  if (existing instanceof Set) {
+    return existing as Set<GlobalEventTap>
+  }
+  const created = new Set<GlobalEventTap>()
+  ;(globalThis as Record<string, unknown>)[GLOBAL_EVENT_TAPS_KEY] = created
+  return created
+}
+
+export function registerGlobalEventTap(handler: GlobalEventTap): () => void {
+  const taps = getGlobalEventTaps()
+  taps.add(handler)
+  return () => {
+    taps.delete(handler)
+  }
+}
+
 /**
  * Match an event name against a pattern.
  *
@@ -161,6 +182,15 @@ export function createEventBus(opts: CreateBusOptions): EventBus {
     payload: EventPayload,
     options?: EmitOptions
   ): Promise<void> {
+    const taps = getGlobalEventTaps()
+    for (const tap of taps) {
+      try {
+        await Promise.resolve(tap(event, payload, options))
+      } catch (error) {
+        console.error(`[events] Global tap error for "${event}":`, error)
+      }
+    }
+
     // Always deliver to in-memory handlers first
     await deliver(event, payload)
 

package/src/modules/events/api/stream/route.ts

@@ -0,0 +1,283 @@
+/**
+ * SSE Event Stream — DOM Event Bridge
+ *
+ * Server-Sent Events endpoint that bridges server-side events to the browser.
+ * Only events with `clientBroadcast: true` in their EventDefinition are sent.
+ * Events are scoped to the authenticated user's tenant.
+ *
+ * Client consumer: `packages/ui/src/backend/injection/eventBridge.ts`
+ */
+
+import { resolveRequestContext } from '@open-mercato/shared/lib/api/context'
+import { isBroadcastEvent } from '@open-mercato/shared/modules/events'
+import { registerGlobalEventTap } from '../../../../bus'
+
+export const metadata = {
+  GET: { requireAuth: true },
+}
+
+const HEARTBEAT_INTERVAL_MS = 30_000
+const MAX_PAYLOAD_BYTES = 4096
+
+type SseConnection = {
+  tenantId: string
+  organizationId: string | null
+  userId: string
+  roleIds: string[]
+  send: (data: string) => void
+  close: () => void
+}
+
+function collectStringValues(input: unknown): string[] {
+  if (!Array.isArray(input)) return []
+  const values: string[] = []
+  for (const value of input) {
+    if (typeof value !== 'string') continue
+    const trimmed = value.trim()
+    if (!trimmed) continue
+    values.push(trimmed)
+  }
+  return values
+}
+
+function normalizeAudience(data: Record<string, unknown>): {
+  tenantId: string | null
+  organizationScopes: string[]
+  recipientUserScopes: string[]
+  recipientRoleScopes: string[]
+} {
+  const tenantId = typeof data.tenantId === 'string' ? data.tenantId : null
+  const organizationScopes = new Set<string>()
+  if (typeof data.organizationId === 'string' && data.organizationId.trim().length > 0) {
+    organizationScopes.add(data.organizationId.trim())
+  }
+  for (const organizationId of collectStringValues(data.organizationIds)) {
+    organizationScopes.add(organizationId)
+  }
+
+  const recipientUserScopes = new Set<string>()
+  if (typeof data.recipientUserId === 'string' && data.recipientUserId.trim().length > 0) {
+    recipientUserScopes.add(data.recipientUserId.trim())
+  }
+  for (const userId of collectStringValues(data.recipientUserIds)) {
+    recipientUserScopes.add(userId)
+  }
+
+  const recipientRoleScopes = new Set<string>()
+  if (typeof data.recipientRoleId === 'string' && data.recipientRoleId.trim().length > 0) {
+    recipientRoleScopes.add(data.recipientRoleId.trim())
+  }
+  for (const roleId of collectStringValues(data.recipientRoleIds)) {
+    recipientRoleScopes.add(roleId)
+  }
+
+  return {
+    tenantId,
+    organizationScopes: Array.from(organizationScopes),
+    recipientUserScopes: Array.from(recipientUserScopes),
+    recipientRoleScopes: Array.from(recipientRoleScopes),
+  }
+}
+
+function matchesAudience(conn: SseConnection, audience: ReturnType<typeof normalizeAudience>): boolean {
+  if (!audience.tenantId) return false
+  if (conn.tenantId !== audience.tenantId) return false
+
+  if (audience.organizationScopes.length > 0) {
+    if (!conn.organizationId) return false
+    if (!audience.organizationScopes.includes(conn.organizationId)) return false
+  }
+
+  if (audience.recipientUserScopes.length > 0 && !audience.recipientUserScopes.includes(conn.userId)) {
+    return false
+  }
+
+  if (audience.recipientRoleScopes.length > 0) {
+    const roleMatched = conn.roleIds.some((roleId) => audience.recipientRoleScopes.includes(roleId))
+    if (!roleMatched) return false
+  }
+
+  return true
+}
+
+/**
+ * Global connection registry.
+ * All active SSE connections are tracked here.
+ * The event bus subscriber iterates this set on each broadcast event.
+ */
+const connections = new Set<SseConnection>()
+
+let globalTapRegistered = false
+
+function buildSsePayload(eventName: string, data: Record<string, unknown>, organizationId: string): string {
+  return JSON.stringify({
+    id: eventName,
+    payload: data,
+    timestamp: Date.now(),
+    organizationId,
+  })
+}
+
+function buildTruncatedPayload(eventName: string, data: Record<string, unknown>, organizationId: string): string {
+  const entityRef: Record<string, unknown> = {
+    truncated: true,
+  }
+  if (typeof data.id === 'string' && data.id.trim().length > 0) {
+    entityRef.id = data.id.trim()
+  }
+  if (typeof data.entityId === 'string' && data.entityId.trim().length > 0) {
+    entityRef.entityId = data.entityId.trim()
+  }
+  if (typeof data.entityType === 'string' && data.entityType.trim().length > 0) {
+    entityRef.entityType = data.entityType.trim()
+  }
+  return JSON.stringify({
+    id: eventName,
+    payload: entityRef,
+    timestamp: Date.now(),
+    organizationId,
+  })
+}
+
+/**
+ * Ensure a process-wide event tap is registered (once).
+ * This captures emits from all request-scoped EventBus instances.
+ */
+function ensureGlobalTapSubscription(): void {
+  if (globalTapRegistered) return
+  globalTapRegistered = true
+
+  registerGlobalEventTap(async (eventName, payload) => {
+    if (!eventName || connections.size === 0) return
+
+    // Only bridge events with clientBroadcast: true
+    if (!isBroadcastEvent(eventName)) return
+
+    const data = (payload ?? {}) as Record<string, unknown>
+    const audience = normalizeAudience(data)
+
+    const organizationId = audience.organizationScopes[0] ?? ''
+    let ssePayload = buildSsePayload(eventName, data, organizationId)
+
+    // Enforce max payload size
+    if (new TextEncoder().encode(ssePayload).length > MAX_PAYLOAD_BYTES) {
+      ssePayload = buildTruncatedPayload(eventName, data, organizationId)
+      if (new TextEncoder().encode(ssePayload).length > MAX_PAYLOAD_BYTES) {
+        console.warn(`[events:stream] Event ${eventName} payload exceeds ${MAX_PAYLOAD_BYTES} bytes, skipping`)
+        return
+      }
+    }
+
+    for (const conn of connections) {
+      if (!matchesAudience(conn, audience)) continue
+
+      try {
+        conn.send(ssePayload)
+      } catch {
+        // Connection may have been closed; cleanup happens via abort handler
+      }
+    }
+  })
+}
+
+export async function GET(req: Request): Promise<Response> {
+  const { ctx } = await resolveRequestContext(req)
+
+  if (!ctx.auth?.tenantId || !ctx.auth?.sub) {
+    return new Response('Unauthorized', { status: 401 })
+  }
+
+  const tenantId = ctx.auth.tenantId
+  const organizationId = (ctx.selectedOrganizationId as string) ?? ctx.auth.orgId ?? null
+  const userId = ctx.auth.sub
+  const roleIds = Array.isArray(ctx.auth.roles)
+    ? ctx.auth.roles.filter((role): role is string => typeof role === 'string' && role.trim().length > 0)
+    : []
+
+  ensureGlobalTapSubscription()
+
+  const encoder = new TextEncoder()
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null
+  let connection: SseConnection | null = null
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const send = (data: string) => {
+        controller.enqueue(encoder.encode(`data: ${data}\n\n`))
+      }
+
+      connection = {
+        tenantId,
+        organizationId,
+        userId,
+        roleIds,
+        send,
+        close: () => controller.close(),
+      }
+      connections.add(connection)
+
+      // Start heartbeat to keep connection alive
+      heartbeatTimer = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(':heartbeat\n\n'))
+        } catch {
+          // Stream may have been closed
+        }
+      }, HEARTBEAT_INTERVAL_MS)
+    },
+    cancel() {
+      cleanup()
+    },
+  })
+
+  function cleanup() {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer)
+      heartbeatTimer = null
+    }
+    if (connection) {
+      connections.delete(connection)
+      connection = null
+    }
+  }
+
+  // Clean up when client disconnects
+  req.signal.addEventListener('abort', cleanup)
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      'Connection': 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    },
+  })
+}
+
+export const openApi = {
+  GET: {
+    summary: 'Subscribe to server events via SSE (DOM Event Bridge)',
+    description: 'Long-lived SSE connection that receives server-side events marked with clientBroadcast: true. Events are server-filtered by tenant, organization, recipient user, and recipient role.',
+    tags: ['Events'],
+    responses: {
+      200: {
+        description: 'Event stream (text/event-stream)',
+        content: {
+          'text/event-stream': {
+            schema: {
+              type: 'object',
+              properties: {
+                id: { type: 'string', description: 'Event identifier (e.g., example.todo.created)' },
+                payload: { type: 'object', description: 'Event-specific data' },
+                timestamp: { type: 'number', description: 'Server timestamp (ms since epoch)' },
+                organizationId: { type: 'string', description: 'Organization scope' },
+              },
+            },
+          },
+        },
+      },
+      401: { description: 'Not authenticated' },
+    },
+  },
+}