@campfire-interactive/platform-events 0.1.0

package/dist/consumer.d.ts

@@ -0,0 +1,19 @@
+import { Envelope } from './envelope';
+import { MasterDataEventType, MasterDataPayload } from './events/master-data';
+/**
+ * Consumer-side helpers (ADR §10: consumers need the types as much as
+ * producers). The eventId dedup helper and replay-drop default land in
+ * plan Phase 1b.
+ */
+/** Parse + validate the envelope of any message off the bus (payload untyped). */
+export declare function parseEnvelope(detail: unknown): Envelope;
+export interface MasterDataEvent<T extends MasterDataEventType = MasterDataEventType> {
+    type: T;
+    envelope: Envelope<MasterDataPayload<T>>;
+}
+export declare function isMasterDataEventType(type: string): type is MasterDataEventType;
+/**
+ * Parse a message known to come from the master-data catalog; validates
+ * both envelope and payload and narrows the payload type on `type`.
+ */
+export declare function parseMasterDataEvent(detail: unknown): MasterDataEvent;

package/dist/consumer.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvelope = parseEnvelope;
+exports.isMasterDataEventType = isMasterDataEventType;
+exports.parseMasterDataEvent = parseMasterDataEvent;
+const envelope_1 = require("./envelope");
+const master_data_1 = require("./events/master-data");
+/**
+ * Consumer-side helpers (ADR §10: consumers need the types as much as
+ * producers). The eventId dedup helper and replay-drop default land in
+ * plan Phase 1b.
+ */
+/** Parse + validate the envelope of any message off the bus (payload untyped). */
+function parseEnvelope(detail) {
+    const raw = typeof detail === 'string' ? JSON.parse(detail) : detail;
+    return envelope_1.envelopeSchema.parse(raw);
+}
+function isMasterDataEventType(type) {
+    return type in master_data_1.masterDataEvents;
+}
+/**
+ * Parse a message known to come from the master-data catalog; validates
+ * both envelope and payload and narrows the payload type on `type`.
+ */
+function parseMasterDataEvent(detail) {
+    const envelope = parseEnvelope(detail);
+    if (!isMasterDataEventType(envelope.type)) {
+        throw new Error(`platform-events: '${envelope.type}' is not a catalogued master-data event`);
+    }
+    const def = master_data_1.masterDataEvents[envelope.type];
+    const payload = def.payload.parse(envelope.payload);
+    return {
+        type: envelope.type,
+        envelope: { ...envelope, payload },
+    };
+}

package/dist/dedup.d.ts

@@ -0,0 +1,59 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { Envelope } from './envelope';
+/**
+ * Consumer-side eventId dedup (ADR open problem 1, resolution per plan
+ * decision 6.1): a shared store claims `consumerApp#eventId` BEFORE side
+ * effects run, so at-least-once delivery doesn't double-execute them.
+ *
+ * Apps with natural state-machine idempotency (e.g. OMSF's
+ * processRoutedQuote status guard) may skip this — the obligation is
+ * idempotency, not this table.
+ */
+export interface DedupStore {
+    /**
+     * Atomically claim an eventId for a consumer. Returns true if this is
+     * the first claim (proceed), false if already claimed (skip).
+     */
+    claim(consumerApp: string, eventId: string): Promise<boolean>;
+}
+export interface DynamoDbDedupStoreOptions {
+    /** e.g. 'platform-events-processed' — provisioned per environment in Phase 2 infra */
+    tableName: string;
+    client?: DynamoDBClient;
+    /** Retention for claims; default 14 days. */
+    ttlSeconds?: number;
+    /** Test seam; defaults to Date.now. */
+    now?: () => number;
+}
+/**
+ * DynamoDB-backed store: conditional put on `pk = <consumerApp>#<eventId>`
+ * with a TTL attribute. Table schema: pk (S, partition key), ttl (N,
+ * enabled as the TTL attribute).
+ */
+export declare class DynamoDbDedupStore implements DedupStore {
+    private readonly client;
+    private readonly tableName;
+    private readonly ttlSeconds;
+    private readonly now;
+    constructor(opts: DynamoDbDedupStoreOptions);
+    claim(consumerApp: string, eventId: string): Promise<boolean>;
+}
+/** True when the message was re-emitted by the replay runbook (Phase 6). */
+export declare function isReplay(envelope: Envelope): boolean;
+export type HandleResult = 'handled' | 'duplicate' | 'replay-dropped';
+export interface WithIdempotencyOptions {
+    /**
+     * Whether replayed messages run the handler. Default false (ADR open
+     * problem 2: non-idempotent side effects must not double-execute on
+     * archive replay) — opt in per handler for replay-safe event types.
+     */
+    allowReplay?: boolean;
+}
+/**
+ * Claim-then-handle wrapper. Skips duplicates and (by default) replays.
+ * If the handler throws AFTER the claim, the message redelivers via SQS
+ * but the claim stands — so handlers must put their own side effects
+ * behind the claim only when they are all-or-nothing; otherwise rely on
+ * state-machine idempotency for the partial-failure window.
+ */
+export declare function withIdempotency(store: DedupStore, consumerApp: string, envelope: Envelope, handler: () => Promise<void>, opts?: WithIdempotencyOptions): Promise<HandleResult>;

package/dist/dedup.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDbDedupStore = void 0;
+exports.isReplay = isReplay;
+exports.withIdempotency = withIdempotency;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const DEFAULT_TTL_SECONDS = 14 * 24 * 60 * 60;
+/**
+ * DynamoDB-backed store: conditional put on `pk = <consumerApp>#<eventId>`
+ * with a TTL attribute. Table schema: pk (S, partition key), ttl (N,
+ * enabled as the TTL attribute).
+ */
+class DynamoDbDedupStore {
+    client;
+    tableName;
+    ttlSeconds;
+    now;
+    constructor(opts) {
+        this.client = opts.client ?? new client_dynamodb_1.DynamoDBClient({});
+        this.tableName = opts.tableName;
+        this.ttlSeconds = opts.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+        this.now = opts.now ?? Date.now;
+    }
+    async claim(consumerApp, eventId) {
+        try {
+            await this.client.send(new client_dynamodb_1.PutItemCommand({
+                TableName: this.tableName,
+                Item: {
+                    pk: { S: `${consumerApp}#${eventId}` },
+                    ttl: { N: String(Math.floor(this.now() / 1000) + this.ttlSeconds) },
+                },
+                ConditionExpression: 'attribute_not_exists(pk)',
+            }));
+            return true;
+        }
+        catch (err) {
+            if (err instanceof client_dynamodb_1.ConditionalCheckFailedException)
+                return false;
+            throw err;
+        }
+    }
+}
+exports.DynamoDbDedupStore = DynamoDbDedupStore;
+/** True when the message was re-emitted by the replay runbook (Phase 6). */
+function isReplay(envelope) {
+    return envelope.replay === true;
+}
+/**
+ * Claim-then-handle wrapper. Skips duplicates and (by default) replays.
+ * If the handler throws AFTER the claim, the message redelivers via SQS
+ * but the claim stands — so handlers must put their own side effects
+ * behind the claim only when they are all-or-nothing; otherwise rely on
+ * state-machine idempotency for the partial-failure window.
+ */
+async function withIdempotency(store, consumerApp, envelope, handler, opts = {}) {
+    if (isReplay(envelope) && !opts.allowReplay)
+        return 'replay-dropped';
+    const firstClaim = await store.claim(consumerApp, envelope.eventId);
+    if (!firstClaim)
+        return 'duplicate';
+    await handler();
+    return 'handled';
+}

package/dist/envelope.d.ts

@@ -0,0 +1,231 @@
+import { z } from 'zod';
+/**
+ * Envelope v2 — ADR 2026-06-05 §6 ("A mandatory event/command envelope").
+ *
+ * schemaVersion 1 is the shape master-data publishes on the legacy
+ * `master-data-events` bus ({ schemaVersion: 1, eventId, tenantId,
+ * entityType, action, actor, timestamp, payload }). It is NOT modeled
+ * here: v1 keeps flowing untouched on the legacy bus during the
+ * dual-publish window, and consumers migrate envelope shape at the same
+ * moment they migrate buses (plan decision 2).
+ */
+/**
+ * Known producers. Matches master-data's deployed `EventCallerService`
+ * 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 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. */
+export declare const envelopeSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    /** uuid — the idempotency/dedupe key */
+    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"]>;
+    /** = EventBridge detail-type, `<entity>.<action>` (or `<verb>.<noun>` for commands) */
+    type: z.ZodString;
+    entityType: z.ZodString;
+    /** id of the affected entity (the survivor id for merge events) */
+    entityId: z.ZodString;
+    /**
+     * Monotonic per-entity version for consumer-side ordering (§5).
+     * Optional in 0.x because master-data does not yet track one; becomes
+     * required before 1.0.0 — producers derive it (e.g. updatedAt epoch ms)
+     * if they have no version column. See plan Phase 2.
+     */
+    entityVersion: z.ZodOptional<z.ZodNumber>;
+    /** null only for platform-global entities (region, part_family) */
+    tenantId: z.ZodNullable<z.ZodString>;
+    /** 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"]>>;
+    /** commands only: async request/reply correlation */
+    correlationId: z.ZodOptional<z.ZodString>;
+    /** commands only: sender's inbox identifier for the reply */
+    replyTo: z.ZodOptional<z.ZodString>;
+    /** saga correlation — auto-propagated by the SDK across a choreographed chain */
+    sagaId: z.ZodOptional<z.ZodString>;
+    /** eventId of the message whose handling caused this one */
+    causationId: z.ZodOptional<z.ZodString>;
+    /** marks a saga compensating ("undo") event */
+    compensation: z.ZodOptional<z.ZodBoolean>;
+    /** stamped by the replay runbook's transformer; non-idempotent handlers drop these */
+    replay: z.ZodOptional<z.ZodBoolean>;
+    /** distributed-tracing id, producer → bus → queue → consumer → browser */
+    traceId: z.ZodString;
+} & {
+    payload: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    schemaVersion: 2;
+    eventId: string;
+    occurredAt: string;
+    producer: "master-data" | "cpq" | "omsf" | "pim" | "erfq" | "forecast" | "identity";
+    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;
+    correlationId?: string | undefined;
+    replyTo?: string | undefined;
+    sagaId?: string | undefined;
+    causationId?: string | undefined;
+    compensation?: boolean | undefined;
+    replay?: boolean | undefined;
+    payload?: unknown;
+}, {
+    type: string;
+    schemaVersion: 2;
+    eventId: string;
+    occurredAt: string;
+    producer: "master-data" | "cpq" | "omsf" | "pim" | "erfq" | "forecast" | "identity";
+    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;
+    correlationId?: string | undefined;
+    replyTo?: string | undefined;
+    sagaId?: string | undefined;
+    causationId?: string | undefined;
+    compensation?: boolean | undefined;
+    replay?: boolean | undefined;
+    payload?: unknown;
+}>;
+export type Envelope<TPayload = unknown> = Omit<z.infer<typeof envelopeSchema>, 'payload'> & {
+    payload: TPayload;
+};
+/** Envelope schema with a typed, validated payload. */
+export declare function envelopeFor<TSchema extends z.ZodTypeAny>(payload: TSchema): z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    /** uuid — the idempotency/dedupe key */
+    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"]>;
+    /** = EventBridge detail-type, `<entity>.<action>` (or `<verb>.<noun>` for commands) */
+    type: z.ZodString;
+    entityType: z.ZodString;
+    /** id of the affected entity (the survivor id for merge events) */
+    entityId: z.ZodString;
+    /**
+     * Monotonic per-entity version for consumer-side ordering (§5).
+     * Optional in 0.x because master-data does not yet track one; becomes
+     * required before 1.0.0 — producers derive it (e.g. updatedAt epoch ms)
+     * if they have no version column. See plan Phase 2.
+     */
+    entityVersion: z.ZodOptional<z.ZodNumber>;
+    /** null only for platform-global entities (region, part_family) */
+    tenantId: z.ZodNullable<z.ZodString>;
+    /** 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"]>>;
+    /** commands only: async request/reply correlation */
+    correlationId: z.ZodOptional<z.ZodString>;
+    /** commands only: sender's inbox identifier for the reply */
+    replyTo: z.ZodOptional<z.ZodString>;
+    /** saga correlation — auto-propagated by the SDK across a choreographed chain */
+    sagaId: z.ZodOptional<z.ZodString>;
+    /** eventId of the message whose handling caused this one */
+    causationId: z.ZodOptional<z.ZodString>;
+    /** marks a saga compensating ("undo") event */
+    compensation: z.ZodOptional<z.ZodBoolean>;
+    /** stamped by the replay runbook's transformer; non-idempotent handlers drop these */
+    replay: z.ZodOptional<z.ZodBoolean>;
+    /** distributed-tracing id, producer → bus → queue → consumer → browser */
+    traceId: z.ZodString;
+} & {
+    payload: TSchema;
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    schemaVersion: z.ZodLiteral<2>;
+    /** uuid — the idempotency/dedupe key */
+    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"]>;
+    /** = EventBridge detail-type, `<entity>.<action>` (or `<verb>.<noun>` for commands) */
+    type: z.ZodString;
+    entityType: z.ZodString;
+    /** id of the affected entity (the survivor id for merge events) */
+    entityId: z.ZodString;
+    /**
+     * Monotonic per-entity version for consumer-side ordering (§5).
+     * Optional in 0.x because master-data does not yet track one; becomes
+     * required before 1.0.0 — producers derive it (e.g. updatedAt epoch ms)
+     * if they have no version column. See plan Phase 2.
+     */
+    entityVersion: z.ZodOptional<z.ZodNumber>;
+    /** null only for platform-global entities (region, part_family) */
+    tenantId: z.ZodNullable<z.ZodString>;
+    /** 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"]>>;
+    /** commands only: async request/reply correlation */
+    correlationId: z.ZodOptional<z.ZodString>;
+    /** commands only: sender's inbox identifier for the reply */
+    replyTo: z.ZodOptional<z.ZodString>;
+    /** saga correlation — auto-propagated by the SDK across a choreographed chain */
+    sagaId: z.ZodOptional<z.ZodString>;
+    /** eventId of the message whose handling caused this one */
+    causationId: z.ZodOptional<z.ZodString>;
+    /** marks a saga compensating ("undo") event */
+    compensation: z.ZodOptional<z.ZodBoolean>;
+    /** stamped by the replay runbook's transformer; non-idempotent handlers drop these */
+    replay: z.ZodOptional<z.ZodBoolean>;
+    /** distributed-tracing id, producer → bus → queue → consumer → browser */
+    traceId: z.ZodString;
+} & {
+    payload: TSchema;
+}>, any> extends infer T ? { [k in keyof T]: T[k]; } : never, z.baseObjectInputType<{
+    schemaVersion: z.ZodLiteral<2>;
+    /** uuid — the idempotency/dedupe key */
+    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"]>;
+    /** = EventBridge detail-type, `<entity>.<action>` (or `<verb>.<noun>` for commands) */
+    type: z.ZodString;
+    entityType: z.ZodString;
+    /** id of the affected entity (the survivor id for merge events) */
+    entityId: z.ZodString;
+    /**
+     * Monotonic per-entity version for consumer-side ordering (§5).
+     * Optional in 0.x because master-data does not yet track one; becomes
+     * required before 1.0.0 — producers derive it (e.g. updatedAt epoch ms)
+     * if they have no version column. See plan Phase 2.
+     */
+    entityVersion: z.ZodOptional<z.ZodNumber>;
+    /** null only for platform-global entities (region, part_family) */
+    tenantId: z.ZodNullable<z.ZodString>;
+    /** 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"]>>;
+    /** commands only: async request/reply correlation */
+    correlationId: z.ZodOptional<z.ZodString>;
+    /** commands only: sender's inbox identifier for the reply */
+    replyTo: z.ZodOptional<z.ZodString>;
+    /** saga correlation — auto-propagated by the SDK across a choreographed chain */
+    sagaId: z.ZodOptional<z.ZodString>;
+    /** eventId of the message whose handling caused this one */
+    causationId: z.ZodOptional<z.ZodString>;
+    /** marks a saga compensating ("undo") event */
+    compensation: z.ZodOptional<z.ZodBoolean>;
+    /** stamped by the replay runbook's transformer; non-idempotent handlers drop these */
+    replay: z.ZodOptional<z.ZodBoolean>;
+    /** distributed-tracing id, producer → bus → queue → consumer → browser */
+    traceId: z.ZodString;
+} & {
+    payload: TSchema;
+}> extends infer T_1 ? { [k_1 in keyof T_1]: T_1[k_1]; } : never>;

package/dist/envelope.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envelopeSchema = exports.ENVELOPE_SCHEMA_VERSION = exports.producerSchema = exports.PRODUCERS = void 0;
+exports.envelopeFor = envelopeFor;
+const zod_1 = require("zod");
+/**
+ * Envelope v2 — ADR 2026-06-05 §6 ("A mandatory event/command envelope").
+ *
+ * schemaVersion 1 is the shape master-data publishes on the legacy
+ * `master-data-events` bus ({ schemaVersion: 1, eventId, tenantId,
+ * entityType, action, actor, timestamp, payload }). It is NOT modeled
+ * here: v1 keeps flowing untouched on the legacy bus during the
+ * dual-publish window, and consumers migrate envelope shape at the same
+ * moment they migrate buses (plan decision 2).
+ */
+/**
+ * Known producers. Matches master-data's deployed `EventCallerService`
+ * union — hyphenated `master-data`, settled at ratification (plan
+ * decision 3; the ADR uses this spelling).
+ */
+exports.PRODUCERS = [
+    'master-data',
+    'cpq',
+    'omsf',
+    'pim',
+    'erfq',
+    'forecast',
+    'identity',
+];
+exports.producerSchema = zod_1.z.enum(exports.PRODUCERS);
+exports.ENVELOPE_SCHEMA_VERSION = 2;
+const envelopeBase = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(exports.ENVELOPE_SCHEMA_VERSION),
+    /** uuid — the idempotency/dedupe key */
+    eventId: zod_1.z.string().uuid(),
+    /** ISO-8601 instant the state change committed at the producer */
+    occurredAt: zod_1.z.string().datetime(),
+    producer: exports.producerSchema,
+    /** = EventBridge detail-type, `<entity>.<action>` (or `<verb>.<noun>` for commands) */
+    type: zod_1.z.string().min(1),
+    entityType: zod_1.z.string().min(1),
+    /** id of the affected entity (the survivor id for merge events) */
+    entityId: zod_1.z.string().min(1),
+    /**
+     * Monotonic per-entity version for consumer-side ordering (§5).
+     * Optional in 0.x because master-data does not yet track one; becomes
+     * required before 1.0.0 — producers derive it (e.g. updatedAt epoch ms)
+     * if they have no version column. See plan Phase 2.
+     */
+    entityVersion: zod_1.z.number().int().nonnegative().optional(),
+    /** null only for platform-global entities (region, part_family) */
+    tenantId: zod_1.z.string().nullable(),
+    /** acting user, when the change was user-initiated */
+    userId: zod_1.z.string().optional(),
+    /** commands only: the app whose inbox this is routed to */
+    recipient: exports.producerSchema.optional(),
+    /** commands only: async request/reply correlation */
+    correlationId: zod_1.z.string().optional(),
+    /** commands only: sender's inbox identifier for the reply */
+    replyTo: zod_1.z.string().optional(),
+    /** saga correlation — auto-propagated by the SDK across a choreographed chain */
+    sagaId: zod_1.z.string().optional(),
+    /** eventId of the message whose handling caused this one */
+    causationId: zod_1.z.string().optional(),
+    /** marks a saga compensating ("undo") event */
+    compensation: zod_1.z.boolean().optional(),
+    /** stamped by the replay runbook's transformer; non-idempotent handlers drop these */
+    replay: zod_1.z.boolean().optional(),
+    /** distributed-tracing id, producer → bus → queue → consumer → browser */
+    traceId: zod_1.z.string().min(1),
+});
+/** Envelope with an unvalidated payload — use `envelopeFor(schema)` when the payload shape is known. */
+exports.envelopeSchema = envelopeBase.extend({ payload: zod_1.z.unknown() });
+/** Envelope schema with a typed, validated payload. */
+function envelopeFor(payload) {
+    return envelopeBase.extend({ payload });
+}