@campfire-interactive/platform-events 0.1.0 → 0.2.0

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"];
+export declare const producerSchema: z.ZodEnum<["master-data", "cpq", "omsf", "pim", "erfq", "forecast", "identity", "notifications"]>;
 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"]>;
     /** = 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"]>>;
     /** 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";
     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" | 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";
     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" | 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"]>;
     /** = 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"]>>;
     /** 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"]>;
     /** = 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"]>>;
     /** 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"]>;
     /** = 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"]>>;
     /** 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,7 @@ exports.PRODUCERS = [
     'erfq',
     'forecast',
     'identity',
+    'notifications',
 ];
 exports.producerSchema = zod_1.z.enum(exports.PRODUCERS);
 exports.ENVELOPE_SCHEMA_VERSION = 2;

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,8 +2,10 @@ 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 { notificationEvents } from './events/notifications';
+export type { NotificationEventDef, NotificationEventType, NotificationPayload, } from './events/notifications';
+export { buildMasterDataEnvelope, buildNotificationEnvelope, configurePublisher, publishMasterDataEvent, publishNotificationEvent, sendCommand, } from './publisher';
+export type { NotificationPublishContext, PublishContext, PublisherConfig, SendCommandContext, } from './publisher';
 export { isMasterDataEventType, parseEnvelope, parseMasterDataEvent } from './consumer';
 export type { MasterDataEvent } from './consumer';
 export { DynamoDbDedupStore, isReplay, withIdempotency } from './dedup';

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.isMasterDataEventType = exports.sendCommand = exports.publishNotificationEvent = exports.publishMasterDataEvent = exports.configurePublisher = exports.buildNotificationEnvelope = exports.buildMasterDataEnvelope = 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,10 +9,14 @@ 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 publisher_1 = require("./publisher");
 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, "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, "isMasterDataEventType", { enumerable: true, get: function () { return consumer_1.isMasterDataEventType; } });

package/dist/publisher.d.ts

@@ -1,6 +1,7 @@
 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';
 /**
  * Publisher core. Mirrors the deployed master-data publisher's posture:
  * fire-and-forget, console fallback when EVENT_BUS_NAME is unset, never
@@ -50,6 +51,18 @@ 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>;
+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,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.configurePublisher = configurePublisher;
 exports.buildMasterDataEnvelope = buildMasterDataEnvelope;
 exports.publishMasterDataEvent = publishMasterDataEvent;
+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");
 let config = {};
 let client;
 function configurePublisher(next) {
@@ -94,6 +97,52 @@ async function publishMasterDataEvent(type, payload, ctx) {
         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,30 +1,30 @@
-{
-  "name": "@campfire-interactive/platform-events",
-  "version": "0.1.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": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@aws-sdk/client-dynamodb": "^3.600.0",
-    "@aws-sdk/client-eventbridge": "^3.600.0",
-    "zod": "^3.23.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.14.0",
-    "typescript": "^5.5.0",
-    "vitest": "^2.0.0"
-  }
-}
+{
+  "name": "@campfire-interactive/platform-events",
+  "version": "0.2.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": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.600.0",
+    "@aws-sdk/client-eventbridge": "^3.600.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}