@campfire-interactive/platform-events 0.1.0

package/dist/saga.d.ts

@@ -0,0 +1,30 @@
+import { Envelope } from './envelope';
+import { PublishContext } from './publisher';
+import { MasterDataEventType, MasterDataPayload } from './events/master-data';
+/**
+ * Saga-context propagation (ADR §"Cross-app workflows", Mode A
+ * choreography): when a handler emits a follow-on event while processing
+ * a saga message, the same sagaId rides along and causationId points at
+ * the triggering event. Developers derive the child context instead of
+ * threading ids by hand.
+ */
+export interface SagaContext {
+    sagaId: string;
+    causationId: string;
+    traceId: string;
+}
+/** Start a new saga (the first event in a choreographed chain). */
+export declare function startSaga(traceId?: string): SagaContext;
+/**
+ * Derive the publish context for an event emitted while handling
+ * `triggering`. Joins the existing saga if there is one, otherwise the
+ * triggering event becomes the saga root. Trace and tenant carry over.
+ */
+export declare function childContext(triggering: Envelope, overrides?: Partial<PublishContext>): PublishContext;
+/**
+ * Emit a compensating ("undo") event for a failed saga step (ADR Mode A:
+ * "compensation as a first-class event class"). Rides the producer's
+ * normal channel with `compensation: true`; upstream consumers subscribe
+ * with the same rule mechanics they already use.
+ */
+export declare function publishCompensation<T extends MasterDataEventType>(forEvent: Envelope, type: T, payload: MasterDataPayload<T>, overrides?: Partial<PublishContext>): Promise<void>;

package/dist/saga.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startSaga = startSaga;
+exports.childContext = childContext;
+exports.publishCompensation = publishCompensation;
+const node_crypto_1 = require("node:crypto");
+const publisher_1 = require("./publisher");
+/** Start a new saga (the first event in a choreographed chain). */
+function startSaga(traceId) {
+    const sagaId = (0, node_crypto_1.randomUUID)();
+    return { sagaId, causationId: sagaId, traceId: traceId ?? (0, node_crypto_1.randomUUID)() };
+}
+/**
+ * Derive the publish context for an event emitted while handling
+ * `triggering`. Joins the existing saga if there is one, otherwise the
+ * triggering event becomes the saga root. Trace and tenant carry over.
+ */
+function childContext(triggering, overrides = {}) {
+    return {
+        tenantId: triggering.tenantId,
+        userId: triggering.userId,
+        traceId: triggering.traceId,
+        sagaId: triggering.sagaId ?? triggering.eventId,
+        causationId: triggering.eventId,
+        ...overrides,
+    };
+}
+/**
+ * Emit a compensating ("undo") event for a failed saga step (ADR Mode A:
+ * "compensation as a first-class event class"). Rides the producer's
+ * normal channel with `compensation: true`; upstream consumers subscribe
+ * with the same rule mechanics they already use.
+ */
+async function publishCompensation(forEvent, type, payload, overrides = {}) {
+    await (0, publisher_1.publishMasterDataEvent)(type, payload, {
+        ...childContext(forEvent, overrides),
+        compensation: true,
+    });
+}

package/package.json

@@ -0,0 +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"
+  }
+}