@campfire-interactive/platform-events 0.1.0 → 0.3.0

package/dist/consumer.d.ts

@@ -1,5 +1,6 @@
 import { Envelope } from './envelope';
 import { MasterDataEventType, MasterDataPayload } from './events/master-data';
+import { AiHubEventType, AiHubPayload } from './events/ai-hub';
 /**
  * Consumer-side helpers (ADR §10: consumers need the types as much as
  * producers). The eventId dedup helper and replay-drop default land in
@@ -17,3 +18,14 @@ export declare function isMasterDataEventType(type: string): type is MasterDataE
  * both envelope and payload and narrows the payload type on `type`.
  */
 export declare function parseMasterDataEvent(detail: unknown): MasterDataEvent;
+export interface AiHubEvent<T extends AiHubEventType = AiHubEventType> {
+    type: T;
+    envelope: Envelope<AiHubPayload<T>>;
+}
+export declare function isAiHubEventType(type: string): type is AiHubEventType;
+/**
+ * Parse a message known to come from the ai-hub catalog; validates both
+ * envelope and payload and narrows the payload type on `type`. This is what
+ * forecast (the consumer) uses on its `forecast-events` queue.
+ */
+export declare function parseAiHubEvent(detail: unknown): AiHubEvent;

package/dist/consumer.js

@@ -3,8 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseEnvelope = parseEnvelope;
 exports.isMasterDataEventType = isMasterDataEventType;
 exports.parseMasterDataEvent = parseMasterDataEvent;
+exports.isAiHubEventType = isAiHubEventType;
+exports.parseAiHubEvent = parseAiHubEvent;
 const envelope_1 = require("./envelope");
 const master_data_1 = require("./events/master-data");
+const ai_hub_1 = require("./events/ai-hub");
 /**
  * Consumer-side helpers (ADR §10: consumers need the types as much as
  * producers). The eventId dedup helper and replay-drop default land in
@@ -34,3 +37,23 @@ function parseMasterDataEvent(detail) {
         envelope: { ...envelope, payload },
     };
 }
+function isAiHubEventType(type) {
+    return type in ai_hub_1.aiHubEvents;
+}
+/**
+ * Parse a message known to come from the ai-hub catalog; validates both
+ * envelope and payload and narrows the payload type on `type`. This is what
+ * forecast (the consumer) uses on its `forecast-events` queue.
+ */
+function parseAiHubEvent(detail) {
+    const envelope = parseEnvelope(detail);
+    if (!isAiHubEventType(envelope.type)) {
+        throw new Error(`platform-events: '${envelope.type}' is not a catalogued ai-hub event`);
+    }
+    const def = ai_hub_1.aiHubEvents[envelope.type];
+    const payload = def.payload.parse(envelope.payload);
+    return {
+        type: envelope.type,
+        envelope: { ...envelope, payload },
+    };
+}

package/dist/envelope.d.ts

@@ -14,8 +14,8 @@ import { z } from 'zod';
  * union — hyphenated `master-data`, settled at ratification (plan
  * decision 3; the ADR uses this spelling).
  */
-export declare const PRODUCERS: readonly ["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity"];
-export declare const producerSchema: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity"]>;
+export declare const PRODUCERS: readonly ["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications", "ai-hub"];
+export declare const producerSchema: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications", "ai-hub"]>;
 export type Producer = z.infer<typeof producerSchema>;
 export declare const ENVELOPE_SCHEMA_VERSION: 2;
 /** Envelope with an unvalidated payload — use `envelopeFor(schema)` when the payload shape is known. */
@@ -25,7 +25,7 @@ export declare const envelopeSchema: z.ZodObject<{
     eventId: z.ZodString;
     /** ISO-8601 instant the state change committed at the producer */
     occurredAt: z.ZodString;
-    producer: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity"]>;
+    producer: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications", "ai-hub"]>;
     /** = EventBridge detail-type, `<entity>.<action>` (or `<verb>.<noun>` for commands) */
     type: z.ZodString;
     entityType: z.ZodString;
@@ -43,7 +43,7 @@ export declare const envelopeSchema: z.ZodObject<{
     /** acting user, when the change was user-initiated */
     userId: z.ZodOptional<z.ZodString>;
     /** commands only: the app whose inbox this is routed to */
-    recipient: z.ZodOptional<z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity"]>>;
+    recipient: z.ZodOptional<z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications", "ai-hub"]>>;
     /** commands only: async request/reply correlation */
     correlationId: z.ZodOptional<z.ZodString>;
     /** commands only: sender's inbox identifier for the reply */
@@ -65,14 +65,14 @@ export declare const envelopeSchema: z.ZodObject<{
     schemaVersion: 2;
     eventId: string;
     occurredAt: string;
-    producer: "master-data" | "cpq" | "omsf" | "pim" | "erfq" | "forecast" | "identity";
+    producer: "master-data" | "cpq" | "omsf" | "pim" | "erfq" | "forecast" | "identity" | "notifications" | "ai-hub";
     entityType: string;
     entityId: string;
     tenantId: string | null;
     traceId: string;
     entityVersion?: number | undefined;
     userId?: string | undefined;
-    recipient?: "master-data" | "cpq" | "omsf" | "pim" | "erfq" | "forecast" | "identity" | undefined;
+    recipient?: "master-data" | "cpq" | "omsf" | "pim" | "erfq" | "forecast" | "identity" | "notifications" | "ai-hub" | undefined;
     correlationId?: string | undefined;
     replyTo?: string | undefined;
     sagaId?: string | undefined;
@@ -85,14 +85,14 @@ export declare const envelopeSchema: z.ZodObject<{
     schemaVersion: 2;
     eventId: string;
     occurredAt: string;
-    producer: "master-data" | "cpq" | "omsf" | "pim" | "erfq" | "forecast" | "identity";
+    producer: "master-data" | "cpq" | "omsf" | "pim" | "erfq" | "forecast" | "identity" | "notifications" | "ai-hub";
     entityType: string;
     entityId: string;
     tenantId: string | null;
     traceId: string;
     entityVersion?: number | undefined;
     userId?: string | undefined;
-    recipient?: "master-data" | "cpq" | "omsf" | "pim" | "erfq" | "forecast" | "identity" | undefined;
+    recipient?: "master-data" | "cpq" | "omsf" | "pim" | "erfq" | "forecast" | "identity" | "notifications" | "ai-hub" | undefined;
     correlationId?: string | undefined;
     replyTo?: string | undefined;
     sagaId?: string | undefined;
@@ -111,7 +111,7 @@ export declare function envelopeFor<TSchema extends z.ZodTypeAny>(payload: TSche
     eventId: z.ZodString;
     /** ISO-8601 instant the state change committed at the producer */
     occurredAt: z.ZodString;
-    producer: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity"]>;
+    producer: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications", "ai-hub"]>;
     /** = EventBridge detail-type, `<entity>.<action>` (or `<verb>.<noun>` for commands) */
     type: z.ZodString;
     entityType: z.ZodString;
@@ -129,7 +129,7 @@ export declare function envelopeFor<TSchema extends z.ZodTypeAny>(payload: TSche
     /** acting user, when the change was user-initiated */
     userId: z.ZodOptional<z.ZodString>;
     /** commands only: the app whose inbox this is routed to */
-    recipient: z.ZodOptional<z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity"]>>;
+    recipient: z.ZodOptional<z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications", "ai-hub"]>>;
     /** commands only: async request/reply correlation */
     correlationId: z.ZodOptional<z.ZodString>;
     /** commands only: sender's inbox identifier for the reply */
@@ -152,7 +152,7 @@ export declare function envelopeFor<TSchema extends z.ZodTypeAny>(payload: TSche
     eventId: z.ZodString;
     /** ISO-8601 instant the state change committed at the producer */
     occurredAt: z.ZodString;
-    producer: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity"]>;
+    producer: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications", "ai-hub"]>;
     /** = EventBridge detail-type, `<entity>.<action>` (or `<verb>.<noun>` for commands) */
     type: z.ZodString;
     entityType: z.ZodString;
@@ -170,7 +170,7 @@ export declare function envelopeFor<TSchema extends z.ZodTypeAny>(payload: TSche
     /** acting user, when the change was user-initiated */
     userId: z.ZodOptional<z.ZodString>;
     /** commands only: the app whose inbox this is routed to */
-    recipient: z.ZodOptional<z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity"]>>;
+    recipient: z.ZodOptional<z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications", "ai-hub"]>>;
     /** commands only: async request/reply correlation */
     correlationId: z.ZodOptional<z.ZodString>;
     /** commands only: sender's inbox identifier for the reply */
@@ -193,7 +193,7 @@ export declare function envelopeFor<TSchema extends z.ZodTypeAny>(payload: TSche
     eventId: z.ZodString;
     /** ISO-8601 instant the state change committed at the producer */
     occurredAt: z.ZodString;
-    producer: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity"]>;
+    producer: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications", "ai-hub"]>;
     /** = EventBridge detail-type, `<entity>.<action>` (or `<verb>.<noun>` for commands) */
     type: z.ZodString;
     entityType: z.ZodString;
@@ -211,7 +211,7 @@ export declare function envelopeFor<TSchema extends z.ZodTypeAny>(payload: TSche
     /** acting user, when the change was user-initiated */
     userId: z.ZodOptional<z.ZodString>;
     /** commands only: the app whose inbox this is routed to */
-    recipient: z.ZodOptional<z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity"]>>;
+    recipient: z.ZodOptional<z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications", "ai-hub"]>>;
     /** commands only: async request/reply correlation */
     correlationId: z.ZodOptional<z.ZodString>;
     /** commands only: sender's inbox identifier for the reply */

package/dist/envelope.js

@@ -26,6 +26,8 @@ exports.PRODUCERS = [
     'erfq',
     'forecast',
     'identity',
+    'notifications',
+    'ai-hub',
 ];
 exports.producerSchema = zod_1.z.enum(exports.PRODUCERS);
 exports.ENVELOPE_SCHEMA_VERSION = 2;

package/dist/events/ai-hub.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * ai-hub event catalog — owned by the cfi-ai-hub team (ADR §10).
+ *
+ * The AI-hub runs long forecast batches for the forecast (Volume Intelligence)
+ * app. It emits `forecast.run_completed` when a batch job finishes, so forecast
+ * reacts to a durable bus event instead of the lossy `callback_url` + 60s poll
+ * it uses today. See
+ * `cfi-ai-hub/docs/plans/2026-06-30-publish-forecast-completion-events.md`.
+ *
+ * MINIMAL trigger payload (meta ADR 2026-06-30 §2): it carries only the job
+ * identity + outcome. forecast re-reads the full result via its existing
+ * `GET /forecast/jobs/{progressId}` — the forecast timeline never travels on
+ * the bus (it exceeds the 256 KB transport limit and needs no claim-check this
+ * way).
+ */
+export interface AiHubEventDef<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    entityType: string;
+    /** payload field holding the affected entity's id */
+    entityIdField: string;
+    /** false → platform-global event; envelope tenantId must be null */
+    tenantScoped: boolean;
+    payload: TSchema;
+}
+export declare const aiHubEvents: {
+    readonly 'forecast.run_completed': AiHubEventDef<z.ZodObject<{
+        /** the hub batch job id forecast polls / re-reads the result by */
+        progressId: z.ZodString;
+        /** terminal outcome of the batch run */
+        status: z.ZodEnum<["done", "done_with_errors", "failed"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "done" | "done_with_errors" | "failed";
+        progressId: string;
+    }, {
+        status: "done" | "done_with_errors" | "failed";
+        progressId: string;
+    }>>;
+};
+export type AiHubEventType = keyof typeof aiHubEvents;
+export type AiHubPayload<T extends AiHubEventType> = z.infer<(typeof aiHubEvents)[T]['payload']>;

package/dist/events/ai-hub.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiHubEvents = void 0;
+const zod_1 = require("zod");
+function defineEvent(def) {
+    return def;
+}
+exports.aiHubEvents = {
+    'forecast.run_completed': defineEvent({
+        entityType: 'forecast_run',
+        entityIdField: 'progressId',
+        tenantScoped: true,
+        payload: zod_1.z.object({
+            /** the hub batch job id forecast polls / re-reads the result by */
+            progressId: zod_1.z.string(),
+            /** terminal outcome of the batch run */
+            status: zod_1.z.enum(['done', 'done_with_errors', 'failed']),
+        }),
+        // Ordering is carried by the standard envelope field `entityVersion`
+        // (§5), supplied via the publish context — not duplicated in the payload.
+    }),
+};

package/dist/events/notifications.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+/**
+ * platform-notifications event catalog — owned by the platform-notifications
+ * team (ADR §10). Emitted when a non-email (in-app / bell) notification is
+ * created, so the recipient's shell-header bell updates in real time
+ * instead of waiting for its poll.
+ *
+ * SECURITY — payload is deliberately MINIMAL. It carries NO title/body:
+ * the event only signals "you have a new notification (id/type)", and the
+ * browser fetches the content over the user-scoped REST endpoint
+ * (`/v1/notifications/me`). Notification content never travels on the bus,
+ * so the realtime path can't leak it. See
+ * `platform-notifications/docs/plans/2026-06-25-realtime-notification-delivery.md`.
+ *
+ * Routing note: the envelope's `userId` is the RECIPIENT (not an actor),
+ * which is exactly the audience a notification needs — the socket fanout
+ * routes notification events to the recipient's user topic ONLY (never a
+ * tenant-scoped resource topic). `tenantId` is nullable: a null tenant is
+ * a platform-level notification (no realtime in v1 — poll fallback).
+ */
+export interface NotificationEventDef<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
+    entityType: string;
+    /** payload field holding the notification's id */
+    entityIdField: string;
+    payload: TSchema;
+}
+export declare const notificationEvents: {
+    readonly 'notification.created': NotificationEventDef<z.ZodObject<{
+        notificationId: z.ZodString;
+        /** the notification's stable type, e.g. "rfq.new_response" */
+        type: z.ZodString;
+        /** the app that emitted it */
+        source: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        notificationId: string;
+        source: string;
+    }, {
+        type: string;
+        notificationId: string;
+        source: string;
+    }>>;
+};
+export type NotificationEventType = keyof typeof notificationEvents;
+export type NotificationPayload<T extends NotificationEventType> = z.infer<(typeof notificationEvents)[T]['payload']>;

package/dist/events/notifications.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notificationEvents = void 0;
+const zod_1 = require("zod");
+function defineEvent(def) {
+    return def;
+}
+exports.notificationEvents = {
+    'notification.created': defineEvent({
+        entityType: 'notification',
+        entityIdField: 'notificationId',
+        payload: zod_1.z.object({
+            notificationId: zod_1.z.string(),
+            /** the notification's stable type, e.g. "rfq.new_response" */
+            type: zod_1.z.string(),
+            /** the app that emitted it */
+            source: zod_1.z.string(),
+        }),
+    }),
+};

package/dist/index.d.ts

@@ -2,10 +2,14 @@ export { ENVELOPE_SCHEMA_VERSION, PRODUCERS, envelopeFor, envelopeSchema, produc
 export type { Envelope, Producer } from './envelope';
 export { masterDataEvents } from './events/master-data';
 export type { EventDef, MasterDataEventType, MasterDataPayload } from './events/master-data';
-export { buildMasterDataEnvelope, configurePublisher, publishMasterDataEvent, sendCommand, } from './publisher';
-export type { PublishContext, PublisherConfig, SendCommandContext } from './publisher';
-export { isMasterDataEventType, parseEnvelope, parseMasterDataEvent } from './consumer';
-export type { MasterDataEvent } from './consumer';
+export { notificationEvents } from './events/notifications';
+export type { NotificationEventDef, NotificationEventType, NotificationPayload, } from './events/notifications';
+export { aiHubEvents } from './events/ai-hub';
+export type { AiHubEventDef, AiHubEventType, AiHubPayload } from './events/ai-hub';
+export { buildAiHubEnvelope, buildMasterDataEnvelope, buildNotificationEnvelope, configurePublisher, publishAiHubEvent, publishMasterDataEvent, publishNotificationEvent, sendCommand, } from './publisher';
+export type { NotificationPublishContext, PublishContext, PublisherConfig, SendCommandContext, } from './publisher';
+export { isAiHubEventType, isMasterDataEventType, parseAiHubEvent, parseEnvelope, parseMasterDataEvent } from './consumer';
+export type { AiHubEvent, MasterDataEvent } from './consumer';
 export { DynamoDbDedupStore, isReplay, withIdempotency } from './dedup';
 export type { DedupStore, DynamoDbDedupStoreOptions, HandleResult, WithIdempotencyOptions } from './dedup';
 export { relayOutbox, toOutboxRecord } from './outbox';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startSaga = exports.publishCompensation = exports.childContext = exports.toOutboxRecord = exports.relayOutbox = exports.withIdempotency = exports.isReplay = exports.DynamoDbDedupStore = exports.parseMasterDataEvent = exports.parseEnvelope = exports.isMasterDataEventType = exports.sendCommand = exports.publishMasterDataEvent = exports.configurePublisher = exports.buildMasterDataEnvelope = exports.masterDataEvents = exports.producerSchema = exports.envelopeSchema = exports.envelopeFor = exports.PRODUCERS = exports.ENVELOPE_SCHEMA_VERSION = void 0;
+exports.startSaga = exports.publishCompensation = exports.childContext = exports.toOutboxRecord = exports.relayOutbox = exports.withIdempotency = exports.isReplay = exports.DynamoDbDedupStore = exports.parseMasterDataEvent = exports.parseEnvelope = exports.parseAiHubEvent = exports.isMasterDataEventType = exports.isAiHubEventType = exports.sendCommand = exports.publishNotificationEvent = exports.publishMasterDataEvent = exports.publishAiHubEvent = exports.configurePublisher = exports.buildNotificationEnvelope = exports.buildMasterDataEnvelope = exports.buildAiHubEnvelope = exports.aiHubEvents = exports.notificationEvents = exports.masterDataEvents = exports.producerSchema = exports.envelopeSchema = exports.envelopeFor = exports.PRODUCERS = exports.ENVELOPE_SCHEMA_VERSION = void 0;
 var envelope_1 = require("./envelope");
 Object.defineProperty(exports, "ENVELOPE_SCHEMA_VERSION", { enumerable: true, get: function () { return envelope_1.ENVELOPE_SCHEMA_VERSION; } });
 Object.defineProperty(exports, "PRODUCERS", { enumerable: true, get: function () { return envelope_1.PRODUCERS; } });
@@ -9,13 +9,23 @@ Object.defineProperty(exports, "envelopeSchema", { enumerable: true, get: functi
 Object.defineProperty(exports, "producerSchema", { enumerable: true, get: function () { return envelope_1.producerSchema; } });
 var master_data_1 = require("./events/master-data");
 Object.defineProperty(exports, "masterDataEvents", { enumerable: true, get: function () { return master_data_1.masterDataEvents; } });
+var notifications_1 = require("./events/notifications");
+Object.defineProperty(exports, "notificationEvents", { enumerable: true, get: function () { return notifications_1.notificationEvents; } });
+var ai_hub_1 = require("./events/ai-hub");
+Object.defineProperty(exports, "aiHubEvents", { enumerable: true, get: function () { return ai_hub_1.aiHubEvents; } });
 var publisher_1 = require("./publisher");
+Object.defineProperty(exports, "buildAiHubEnvelope", { enumerable: true, get: function () { return publisher_1.buildAiHubEnvelope; } });
 Object.defineProperty(exports, "buildMasterDataEnvelope", { enumerable: true, get: function () { return publisher_1.buildMasterDataEnvelope; } });
+Object.defineProperty(exports, "buildNotificationEnvelope", { enumerable: true, get: function () { return publisher_1.buildNotificationEnvelope; } });
 Object.defineProperty(exports, "configurePublisher", { enumerable: true, get: function () { return publisher_1.configurePublisher; } });
+Object.defineProperty(exports, "publishAiHubEvent", { enumerable: true, get: function () { return publisher_1.publishAiHubEvent; } });
 Object.defineProperty(exports, "publishMasterDataEvent", { enumerable: true, get: function () { return publisher_1.publishMasterDataEvent; } });
+Object.defineProperty(exports, "publishNotificationEvent", { enumerable: true, get: function () { return publisher_1.publishNotificationEvent; } });
 Object.defineProperty(exports, "sendCommand", { enumerable: true, get: function () { return publisher_1.sendCommand; } });
 var consumer_1 = require("./consumer");
+Object.defineProperty(exports, "isAiHubEventType", { enumerable: true, get: function () { return consumer_1.isAiHubEventType; } });
 Object.defineProperty(exports, "isMasterDataEventType", { enumerable: true, get: function () { return consumer_1.isMasterDataEventType; } });
+Object.defineProperty(exports, "parseAiHubEvent", { enumerable: true, get: function () { return consumer_1.parseAiHubEvent; } });
 Object.defineProperty(exports, "parseEnvelope", { enumerable: true, get: function () { return consumer_1.parseEnvelope; } });
 Object.defineProperty(exports, "parseMasterDataEvent", { enumerable: true, get: function () { return consumer_1.parseMasterDataEvent; } });
 var dedup_1 = require("./dedup");

package/dist/publisher.d.ts

@@ -1,6 +1,8 @@
 import { EventBridgeClient } from '@aws-sdk/client-eventbridge';
 import { Envelope, Producer } from './envelope';
 import { MasterDataEventType, MasterDataPayload } from './events/master-data';
+import { NotificationEventType, NotificationPayload } from './events/notifications';
+import { AiHubEventType, AiHubPayload } from './events/ai-hub';
 /**
  * Publisher core. Mirrors the deployed master-data publisher's posture:
  * fire-and-forget, console fallback when EVENT_BUS_NAME is unset, never
@@ -50,6 +52,25 @@ export declare function buildMasterDataEnvelope<T extends MasterDataEventType>(t
  * logged, never thrown into the caller (until the outbox lands).
  */
 export declare function publishMasterDataEvent<T extends MasterDataEventType>(type: T, payload: MasterDataPayload<T>, ctx: PublishContext): Promise<void>;
+/** Build + validate the full envelope for a catalogued ai-hub event. */
+export declare function buildAiHubEnvelope<T extends AiHubEventType>(type: T, payload: AiHubPayload<T>, ctx: PublishContext, producer?: Producer): Envelope<AiHubPayload<T>>;
+/**
+ * Publish a catalogued ai-hub event. Fire-and-forget: failures are logged,
+ * never thrown into the caller (until the outbox lands — hub plan fast-follow).
+ */
+export declare function publishAiHubEvent<T extends AiHubEventType>(type: T, payload: AiHubPayload<T>, ctx: PublishContext): Promise<void>;
+export interface NotificationPublishContext extends Omit<PublishContext, 'userId'> {
+    /** The RECIPIENT user (identity sub) — required: it is the routing key. */
+    userId: string;
+}
+/** Build + validate the envelope for a catalogued notification event. */
+export declare function buildNotificationEnvelope<T extends NotificationEventType>(type: T, payload: NotificationPayload<T>, ctx: NotificationPublishContext, producer?: Producer): Envelope<NotificationPayload<T>>;
+/**
+ * Publish a catalogued notification event (the realtime bell signal).
+ * Fire-and-forget like the master-data publisher — a bus failure is
+ * logged, never thrown into the notification write.
+ */
+export declare function publishNotificationEvent<T extends NotificationEventType>(type: T, payload: NotificationPayload<T>, ctx: NotificationPublishContext): Promise<void>;
 /**
  * Send a point-to-point command to one app's inbox, routed through the bus
  * on `detail.recipient` (ADR §3, default path). Command payloads are not

package/dist/publisher.js

@@ -3,11 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.configurePublisher = configurePublisher;
 exports.buildMasterDataEnvelope = buildMasterDataEnvelope;
 exports.publishMasterDataEvent = publishMasterDataEvent;
+exports.buildAiHubEnvelope = buildAiHubEnvelope;
+exports.publishAiHubEvent = publishAiHubEvent;
+exports.buildNotificationEnvelope = buildNotificationEnvelope;
+exports.publishNotificationEvent = publishNotificationEvent;
 exports.sendCommand = sendCommand;
 const node_crypto_1 = require("node:crypto");
 const client_eventbridge_1 = require("@aws-sdk/client-eventbridge");
 const envelope_1 = require("./envelope");
 const master_data_1 = require("./events/master-data");
+const notifications_1 = require("./events/notifications");
+const ai_hub_1 = require("./events/ai-hub");
 let config = {};
 let client;
 function configurePublisher(next) {
@@ -94,6 +100,99 @@ async function publishMasterDataEvent(type, payload, ctx) {
         console.error(`[platform-events] publish failed for ${type}`, err);
     }
 }
+/** Build + validate the full envelope for a catalogued ai-hub event. */
+function buildAiHubEnvelope(type, payload, ctx, producer = 'ai-hub') {
+    const def = ai_hub_1.aiHubEvents[type];
+    const parsedPayload = def.payload.parse(payload);
+    if (def.tenantScoped && ctx.tenantId == null) {
+        throw new Error(`platform-events: ${type} is tenant-scoped but tenantId is null`);
+    }
+    if (!def.tenantScoped && ctx.tenantId != null) {
+        throw new Error(`platform-events: ${type} is platform-global but tenantId was provided`);
+    }
+    const entityId = parsedPayload[def.entityIdField];
+    if (typeof entityId !== 'string' || entityId.length === 0) {
+        throw new Error(`platform-events: ${type} payload is missing entity id field '${def.entityIdField}'`);
+    }
+    const envelope = {
+        schemaVersion: envelope_1.ENVELOPE_SCHEMA_VERSION,
+        eventId: ctx.eventId ?? (0, node_crypto_1.randomUUID)(),
+        occurredAt: ctx.occurredAt ?? new Date().toISOString(),
+        producer,
+        type,
+        entityType: def.entityType,
+        entityId,
+        entityVersion: ctx.entityVersion,
+        tenantId: ctx.tenantId,
+        userId: ctx.userId,
+        sagaId: ctx.sagaId,
+        causationId: ctx.causationId,
+        compensation: ctx.compensation,
+        traceId: ctx.traceId ?? (0, node_crypto_1.randomUUID)(),
+        payload: parsedPayload,
+    };
+    envelope_1.envelopeSchema.parse(envelope);
+    return envelope;
+}
+/**
+ * Publish a catalogued ai-hub event. Fire-and-forget: failures are logged,
+ * never thrown into the caller (until the outbox lands — hub plan fast-follow).
+ */
+async function publishAiHubEvent(type, payload, ctx) {
+    try {
+        const envelope = buildAiHubEnvelope(type, payload, ctx, resolveProducer());
+        await putOnBus(envelope, envelope.producer);
+    }
+    catch (err) {
+        console.error(`[platform-events] publish failed for ${type}`, err);
+    }
+}
+/** Build + validate the envelope for a catalogued notification event. */
+function buildNotificationEnvelope(type, payload, ctx, producer = 'notifications') {
+    const def = notifications_1.notificationEvents[type];
+    const parsedPayload = def.payload.parse(payload);
+    if (!ctx.userId) {
+        // No recipient → no user topic → undeliverable. Fail loud at build.
+        throw new Error(`platform-events: ${type} requires a recipient userId`);
+    }
+    const entityId = parsedPayload[def.entityIdField];
+    if (typeof entityId !== 'string' || entityId.length === 0) {
+        throw new Error(`platform-events: ${type} payload is missing id field '${def.entityIdField}'`);
+    }
+    const envelope = {
+        schemaVersion: envelope_1.ENVELOPE_SCHEMA_VERSION,
+        eventId: ctx.eventId ?? (0, node_crypto_1.randomUUID)(),
+        occurredAt: ctx.occurredAt ?? new Date().toISOString(),
+        producer,
+        type,
+        entityType: def.entityType,
+        entityId,
+        entityVersion: ctx.entityVersion,
+        // nullable: null = platform-level notification (poll-only, no realtime topic).
+        tenantId: ctx.tenantId,
+        userId: ctx.userId,
+        sagaId: ctx.sagaId,
+        causationId: ctx.causationId,
+        traceId: ctx.traceId ?? (0, node_crypto_1.randomUUID)(),
+        payload: parsedPayload,
+    };
+    envelope_1.envelopeSchema.parse(envelope);
+    return envelope;
+}
+/**
+ * Publish a catalogued notification event (the realtime bell signal).
+ * Fire-and-forget like the master-data publisher — a bus failure is
+ * logged, never thrown into the notification write.
+ */
+async function publishNotificationEvent(type, payload, ctx) {
+    try {
+        const envelope = buildNotificationEnvelope(type, payload, ctx, resolveProducer());
+        await putOnBus(envelope, envelope.producer);
+    }
+    catch (err) {
+        console.error(`[platform-events] publish failed for ${type}`, err);
+    }
+}
 /**
  * Send a point-to-point command to one app's inbox, routed through the bus
  * on `detail.recipient` (ADR §3, default path). Command payloads are not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@campfire-interactive/platform-events",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Publisher/consumer SDK for the platform-events bus: envelope v2, typed event schemas, publish helpers, sendCommand. 0.x during the Phase 2 dual-publish window; 1.0.0 at cutover (nextgen/docs/plans/2026-06-10-platform-async-messaging.md).",
   "license": "UNLICENSED",
   "publishConfig": {