@apso/domain-events 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @apso/domain-events
+
+Durable **domain-event spine** for NestJS + TypeORM — the standard
+**transactional outbox** pattern, surfaced with generic domain-event naming.
+
+State changes to opted-in entities write a `DomainEvent` row **in the same
+transaction**; a self-contained relay drains pending rows and fans them out to
+runtime-selected delivery destinations.
+
+See the cross-language [`CONTRACT.md`](../../../CONTRACT.md) for the behavior all
+language implementations honor (TypeScript is the reference).
+
+## Install
+
+```bash
+npm install @apso/domain-events
+```
+
+Peer deps: `@nestjs/common`, `@nestjs/core`, `@nestjs/typeorm`, `typeorm`,
+`rxjs`. Broker SDKs (`@nestjs/microservices` + `kafkajs`, `@aws-sdk/client-sqs`,
+`@aws-sdk/client-eventbridge`) are **optional** and loaded lazily — a
+webhook-only deployment needs none of them.
+
+## Wire it up
+
+```ts
+import { DomainEventsModule } from '@apso/domain-events';
+import { Product } from './product/product.entity';
+
+@Module({
+  imports: [
+    DomainEventsModule.forRoot({
+      entities: [Product], // the CLI-emitted manifest of opted-in entities
+      // mapper?: MyDomainEventMapper,  // optional override
+      // pollIntervalMs?: 5000,         // optional, default 5000
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`forRoot` is `@Global()`. The relay starts its own `setInterval` drain on
+application bootstrap and clears it on shutdown — **no external scheduler
+dependency**.
+
+## Delivery destinations
+
+Active destinations are chosen ENTIRELY at runtime from `EVENTS_DESTINATION`
+(comma-separated → fan-out). Unknown name → startup error.
+
+| name | env | dependency |
+|---|---|---|
+| `webhook` | `EVENTS_WEBHOOK_URL`, `EVENTS_WEBHOOK_SECRET` | none (native fetch + crypto) |
+| `kafka` | `EVENTS_KAFKA_BROKERS`, `EVENTS_KAFKA_TOPIC` | `@nestjs/microservices` + `kafkajs` (lazy) |
+| `sqs` | `AWS_REGION`, `EVENTS_SQS_QUEUE_URL` | `@aws-sdk/client-sqs` (lazy) |
+| `eventbridge` | `AWS_REGION`, `EVENTS_EVENTBRIDGE_BUS` | `@aws-sdk/client-eventbridge` (lazy) |
+
+The webhook adapter signs with [Standard Webhooks](https://www.standardwebhooks.com/)
+(`webhook-id`, `webhook-timestamp`, `webhook-signature: v1,<sig>`).
+
+## Duplicates — consumer-side dedupe is MANDATORY with multiple destinations
+
+Delivery is at-least-once and tracked at the **event grain** (a single
+`events.status`), NOT per (event × destination). With more than one active
+destination, a failure in any one destination retries the **whole** event, so
+healthy destinations receive it **again** on every retry. Consumers MUST dedupe
+on `event.id` whenever multiple destinations are active. (A single destination —
+the common case — never duplicates beyond ordinary at-least-once.)

package/dist/destinations/delivery-destination.d.ts

@@ -0,0 +1,25 @@
+import { DomainEvent } from '../domain-event.entity';
+/**
+ * DI token under which the active set of {@link DeliveryDestination} adapters is
+ * provided. The {@link DomainEventRelay} injects this (optionally) and fans each
+ * event out to every active destination.
+ */
+export declare const DOMAIN_EVENT_DESTINATIONS = "DOMAIN_EVENT_DESTINATIONS";
+/**
+ * A DeliveryDestination is a pure transport: it takes a fully-formed
+ * {@link DomainEvent} and pushes it to one external sink (a webhook URL, a Kafka
+ * topic, an SQS queue, an EventBridge bus, ...).
+ *
+ * Adapters carry NO application semantics — the event type and payload are set
+ * upstream by the {@link DomainEventMapper}. An adapter MUST throw on failure so
+ * the relay retries (at-least-once delivery; consumers dedupe on `event.id`).
+ */
+export interface DeliveryDestination {
+    /** The destination's stable name, matching its `EVENTS_DESTINATION` token. */
+    readonly name: string;
+    /**
+     * Deliver a single event. Throw on any non-success so the relay retries.
+     */
+    send(event: DomainEvent): Promise<void>;
+}
+//# sourceMappingURL=delivery-destination.d.ts.map

package/dist/destinations/delivery-destination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-destination.d.ts","sourceRoot":"","sources":["../../src/destinations/delivery-destination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAErE;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC"}

package/dist/destinations/delivery-destination.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOMAIN_EVENT_DESTINATIONS = void 0;
+/**
+ * DI token under which the active set of {@link DeliveryDestination} adapters is
+ * provided. The {@link DomainEventRelay} injects this (optionally) and fans each
+ * event out to every active destination.
+ */
+exports.DOMAIN_EVENT_DESTINATIONS = 'DOMAIN_EVENT_DESTINATIONS';
+//# sourceMappingURL=delivery-destination.js.map

package/dist/destinations/delivery-destination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-destination.js","sourceRoot":"","sources":["../../src/destinations/delivery-destination.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AACU,QAAA,yBAAyB,GAAG,2BAA2B,CAAC"}

package/dist/destinations/eventbridge.destination.d.ts

@@ -0,0 +1,23 @@
+import { DomainEvent } from '../domain-event.entity';
+import { DeliveryDestination } from './delivery-destination';
+/**
+ * EventBridgeDestination puts each domain event onto an Amazon EventBridge bus.
+ *
+ * The AWS SDK is loaded LAZILY (require) so it is only needed when this
+ * destination is actually activated at runtime (EVENTS_DESTINATION=eventbridge).
+ * Install it in the deploying service: `npm install @aws-sdk/client-eventbridge`.
+ *
+ * Each event is put with `Source='apso.domain-events'` and
+ * `DetailType=event.type`.
+ *
+ * Env:
+ *   AWS_REGION             — AWS region (required)
+ *   EVENTS_EVENTBRIDGE_BUS — target event bus name (required)
+ */
+export declare class EventBridgeDestination implements DeliveryDestination {
+    readonly name = "eventbridge";
+    private client?;
+    private load;
+    send(event: DomainEvent): Promise<void>;
+}
+//# sourceMappingURL=eventbridge.destination.d.ts.map

package/dist/destinations/eventbridge.destination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventbridge.destination.d.ts","sourceRoot":"","sources":["../../src/destinations/eventbridge.destination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,YAAW,mBAAmB;IAChE,QAAQ,CAAC,IAAI,iBAAiB;IAG9B,OAAO,CAAC,MAAM,CAAC,CAAM;IAGrB,OAAO,CAAC,IAAI;IAYN,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAsB9C"}

package/dist/destinations/eventbridge.destination.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBridgeDestination = void 0;
+/**
+ * EventBridgeDestination puts each domain event onto an Amazon EventBridge bus.
+ *
+ * The AWS SDK is loaded LAZILY (require) so it is only needed when this
+ * destination is actually activated at runtime (EVENTS_DESTINATION=eventbridge).
+ * Install it in the deploying service: `npm install @aws-sdk/client-eventbridge`.
+ *
+ * Each event is put with `Source='apso.domain-events'` and
+ * `DetailType=event.type`.
+ *
+ * Env:
+ *   AWS_REGION             — AWS region (required)
+ *   EVENTS_EVENTBRIDGE_BUS — target event bus name (required)
+ */
+class EventBridgeDestination {
+    constructor() {
+        this.name = 'eventbridge';
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    load() {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+            return require('@aws-sdk/client-eventbridge');
+        }
+        catch {
+            throw new Error("EVENTS_DESTINATION=eventbridge requires '@aws-sdk/client-eventbridge' — run " +
+                '`npm install @aws-sdk/client-eventbridge`');
+        }
+    }
+    async send(event) {
+        const busName = process.env.EVENTS_EVENTBRIDGE_BUS;
+        if (!busName) {
+            throw new Error('EVENTS_EVENTBRIDGE_BUS is not set');
+        }
+        const { EventBridgeClient, PutEventsCommand } = this.load();
+        if (!this.client) {
+            this.client = new EventBridgeClient({ region: process.env.AWS_REGION });
+        }
+        await this.client.send(new PutEventsCommand({
+            Entries: [
+                {
+                    EventBusName: busName,
+                    Source: 'apso.domain-events',
+                    DetailType: event.type,
+                    Detail: JSON.stringify(event),
+                },
+            ],
+        }));
+    }
+}
+exports.EventBridgeDestination = EventBridgeDestination;
+//# sourceMappingURL=eventbridge.destination.js.map

package/dist/destinations/eventbridge.destination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventbridge.destination.js","sourceRoot":"","sources":["../../src/destinations/eventbridge.destination.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;GAaG;AACH,MAAa,sBAAsB;IAAnC;QACW,SAAI,GAAG,aAAa,CAAC;IAwChC,CAAC;IAnCC,8DAA8D;IACtD,IAAI;QACV,IAAI,CAAC;YACH,8EAA8E;YAC9E,OAAO,OAAO,CAAC,6BAA6B,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CACb,8EAA8E;gBAC5E,2CAA2C,CAC9C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAkB;QAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;QACD,MAAM,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5D,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,GAAG,IAAI,iBAAiB,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;QAC1E,CAAC;QACD,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACpB,IAAI,gBAAgB,CAAC;YACnB,OAAO,EAAE;gBACP;oBACE,YAAY,EAAE,OAAO;oBACrB,MAAM,EAAE,oBAAoB;oBAC5B,UAAU,EAAE,KAAK,CAAC,IAAI;oBACtB,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;iBAC9B;aACF;SACF,CAAC,CACH,CAAC;IACJ,CAAC;CACF;AAzCD,wDAyCC"}

package/dist/destinations/index.d.ts

@@ -0,0 +1,22 @@
+import { DeliveryDestination, DOMAIN_EVENT_DESTINATIONS } from './delivery-destination';
+export { DeliveryDestination, DOMAIN_EVENT_DESTINATIONS };
+export { signWebhook, WebhookDestination } from './webhook.destination';
+export { KafkaDestination } from './kafka.destination';
+export { SqsDestination } from './sqs.destination';
+export { EventBridgeDestination } from './eventbridge.destination';
+/**
+ * Builds the ACTIVE set of destinations from the runtime `EVENTS_DESTINATION`
+ * env var (comma-separated, trimmed). This is the ONLY place delivery is
+ * selected — there is no build-time/`.apsorc` delivery config. An empty
+ * EVENTS_DESTINATION means nothing is delivered (events stay `pending`).
+ *
+ * Broker client libraries are loaded lazily inside each adapter, so a service
+ * only needs the dependency for the destination(s) it actually activates here.
+ *
+ * Delivery is at-least-once and, with multiple active destinations, re-sends to
+ * ALL of them on retry — consumers MUST dedupe on `event.id`.
+ *
+ * An unknown EVENTS_DESTINATION value is a startup error.
+ */
+export declare function buildDestinations(): DeliveryDestination[];
+//# sourceMappingURL=index.d.ts.map

package/dist/destinations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/destinations/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EAC1B,MAAM,wBAAwB,CAAC;AAMhC,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAcnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,EAAE,CAiBzD"}

package/dist/destinations/index.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventBridgeDestination = exports.SqsDestination = exports.KafkaDestination = exports.WebhookDestination = exports.signWebhook = exports.DOMAIN_EVENT_DESTINATIONS = void 0;
+exports.buildDestinations = buildDestinations;
+const delivery_destination_1 = require("./delivery-destination");
+Object.defineProperty(exports, "DOMAIN_EVENT_DESTINATIONS", { enumerable: true, get: function () { return delivery_destination_1.DOMAIN_EVENT_DESTINATIONS; } });
+const webhook_destination_1 = require("./webhook.destination");
+const kafka_destination_1 = require("./kafka.destination");
+const sqs_destination_1 = require("./sqs.destination");
+const eventbridge_destination_1 = require("./eventbridge.destination");
+var webhook_destination_2 = require("./webhook.destination");
+Object.defineProperty(exports, "signWebhook", { enumerable: true, get: function () { return webhook_destination_2.signWebhook; } });
+Object.defineProperty(exports, "WebhookDestination", { enumerable: true, get: function () { return webhook_destination_2.WebhookDestination; } });
+var kafka_destination_2 = require("./kafka.destination");
+Object.defineProperty(exports, "KafkaDestination", { enumerable: true, get: function () { return kafka_destination_2.KafkaDestination; } });
+var sqs_destination_2 = require("./sqs.destination");
+Object.defineProperty(exports, "SqsDestination", { enumerable: true, get: function () { return sqs_destination_2.SqsDestination; } });
+var eventbridge_destination_2 = require("./eventbridge.destination");
+Object.defineProperty(exports, "EventBridgeDestination", { enumerable: true, get: function () { return eventbridge_destination_2.EventBridgeDestination; } });
+/**
+ * Factory for every supported {@link DeliveryDestination} adapter, keyed by
+ * name. All adapters are always present; broker SDKs are loaded lazily inside
+ * the adapter only when it is actually activated.
+ */
+const DESTINATION_FACTORIES = {
+    webhook: () => new webhook_destination_1.WebhookDestination(),
+    kafka: () => new kafka_destination_1.KafkaDestination(),
+    sqs: () => new sqs_destination_1.SqsDestination(),
+    eventbridge: () => new eventbridge_destination_1.EventBridgeDestination(),
+};
+/**
+ * Builds the ACTIVE set of destinations from the runtime `EVENTS_DESTINATION`
+ * env var (comma-separated, trimmed). This is the ONLY place delivery is
+ * selected — there is no build-time/`.apsorc` delivery config. An empty
+ * EVENTS_DESTINATION means nothing is delivered (events stay `pending`).
+ *
+ * Broker client libraries are loaded lazily inside each adapter, so a service
+ * only needs the dependency for the destination(s) it actually activates here.
+ *
+ * Delivery is at-least-once and, with multiple active destinations, re-sends to
+ * ALL of them on retry — consumers MUST dedupe on `event.id`.
+ *
+ * An unknown EVENTS_DESTINATION value is a startup error.
+ */
+function buildDestinations() {
+    const raw = process.env.EVENTS_DESTINATION ?? '';
+    const names = raw
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean);
+    return names.map((name) => {
+        const factory = DESTINATION_FACTORIES[name];
+        if (!factory) {
+            throw new Error(`EVENTS_DESTINATION '${name}' is not a known destination. ` +
+                `Valid values: [${Object.keys(DESTINATION_FACTORIES).join(', ')}]`);
+        }
+        return factory();
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/destinations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/destinations/index.ts"],"names":[],"mappings":";;;AAyCA,8CAiBC;AA1DD,iEAGgC;AAMF,0GAP5B,gDAAyB,OAO4B;AALvD,+DAA2D;AAC3D,2DAAuD;AACvD,uDAAmD;AACnD,uEAAmE;AAGnE,6DAAwE;AAA/D,kHAAA,WAAW,OAAA;AAAE,yHAAA,kBAAkB,OAAA;AACxC,yDAAuD;AAA9C,qHAAA,gBAAgB,OAAA;AACzB,qDAAmD;AAA1C,iHAAA,cAAc,OAAA;AACvB,qEAAmE;AAA1D,iIAAA,sBAAsB,OAAA;AAE/B;;;;GAIG;AACH,MAAM,qBAAqB,GAA8C;IACvE,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,wCAAkB,EAAE;IACvC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,oCAAgB,EAAE;IACnC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,gCAAc,EAAE;IAC/B,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,gDAAsB,EAAE;CAChD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,SAAgB,iBAAiB;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAC;IACjD,MAAM,KAAK,GAAG,GAAG;SACd,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,uBAAuB,IAAI,gCAAgC;gBACzD,kBAAkB,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACrE,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,EAAE,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/destinations/kafka.destination.d.ts

@@ -0,0 +1,24 @@
+import { DomainEvent } from '../domain-event.entity';
+import { DeliveryDestination } from './delivery-destination';
+/**
+ * KafkaDestination emits each domain event onto a Kafka topic using the
+ * idiomatic `@nestjs/microservices` ClientProxy.
+ *
+ * `@nestjs/microservices`, `kafkajs` and `rxjs` are loaded LAZILY (require) so
+ * they are only needed when this destination is actually activated at runtime
+ * (EVENTS_DESTINATION=kafka). Install them in the deploying service:
+ * `npm install @nestjs/microservices kafkajs rxjs`.
+ *
+ * Env:
+ *   EVENTS_KAFKA_BROKERS — comma-separated broker list (required)
+ *   EVENTS_KAFKA_TOPIC   — topic to emit to (required)
+ */
+export declare class KafkaDestination implements DeliveryDestination {
+    readonly name = "kafka";
+    private client?;
+    private connected;
+    private loadDep;
+    private getClient;
+    send(event: DomainEvent): Promise<void>;
+}
+//# sourceMappingURL=kafka.destination.d.ts.map

package/dist/destinations/kafka.destination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kafka.destination.d.ts","sourceRoot":"","sources":["../../src/destinations/kafka.destination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAiB,YAAW,mBAAmB;IAC1D,QAAQ,CAAC,IAAI,WAAW;IAGxB,OAAO,CAAC,MAAM,CAAC,CAAM;IACrB,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,SAAS;IAoBX,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAa9C"}

package/dist/destinations/kafka.destination.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KafkaDestination = void 0;
+/**
+ * KafkaDestination emits each domain event onto a Kafka topic using the
+ * idiomatic `@nestjs/microservices` ClientProxy.
+ *
+ * `@nestjs/microservices`, `kafkajs` and `rxjs` are loaded LAZILY (require) so
+ * they are only needed when this destination is actually activated at runtime
+ * (EVENTS_DESTINATION=kafka). Install them in the deploying service:
+ * `npm install @nestjs/microservices kafkajs rxjs`.
+ *
+ * Env:
+ *   EVENTS_KAFKA_BROKERS — comma-separated broker list (required)
+ *   EVENTS_KAFKA_TOPIC   — topic to emit to (required)
+ */
+class KafkaDestination {
+    constructor() {
+        this.name = 'kafka';
+        this.connected = false;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    loadDep(pkg) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+            return require(pkg);
+        }
+        catch {
+            throw new Error("EVENTS_DESTINATION=kafka requires '@nestjs/microservices', 'kafkajs' " +
+                "and 'rxjs' — run `npm install @nestjs/microservices kafkajs rxjs`");
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getClient() {
+        if (!this.client) {
+            const brokers = (process.env.EVENTS_KAFKA_BROKERS ?? '')
+                .split(',')
+                .map((broker) => broker.trim())
+                .filter(Boolean);
+            if (brokers.length === 0) {
+                throw new Error('EVENTS_KAFKA_BROKERS is not set');
+            }
+            const { ClientProxyFactory, Transport } = this.loadDep('@nestjs/microservices');
+            this.client = ClientProxyFactory.create({
+                transport: Transport.KAFKA,
+                options: { client: { brokers } },
+            });
+        }
+        return this.client;
+    }
+    async send(event) {
+        if (!process.env.EVENTS_KAFKA_TOPIC) {
+            throw new Error('EVENTS_KAFKA_TOPIC is not set');
+        }
+        const topic = process.env.EVENTS_KAFKA_TOPIC;
+        const { lastValueFrom } = this.loadDep('rxjs');
+        const client = this.getClient();
+        if (!this.connected) {
+            await client.connect();
+            this.connected = true;
+        }
+        await lastValueFrom(client.emit(topic, event));
+    }
+}
+exports.KafkaDestination = KafkaDestination;
+//# sourceMappingURL=kafka.destination.js.map

package/dist/destinations/kafka.destination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kafka.destination.js","sourceRoot":"","sources":["../../src/destinations/kafka.destination.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;GAYG;AACH,MAAa,gBAAgB;IAA7B;QACW,SAAI,GAAG,OAAO,CAAC;QAIhB,cAAS,GAAG,KAAK,CAAC;IAiD5B,CAAC;IA/CC,8DAA8D;IACtD,OAAO,CAAC,GAAW;QACzB,IAAI,CAAC;YACH,8EAA8E;YAC9E,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CACb,uEAAuE;gBACrE,mEAAmE,CACtE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,8DAA8D;IACtD,SAAS;QACf,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC;iBACrD,KAAK,CAAC,GAAG,CAAC;iBACV,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;iBAC9B,MAAM,CAAC,OAAO,CAAC,CAAC;YACnB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;YACrD,CAAC;YACD,MAAM,EAAE,kBAAkB,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,OAAO,CACpD,uBAAuB,CACxB,CAAC;YACF,IAAI,CAAC,MAAM,GAAG,kBAAkB,CAAC,MAAM,CAAC;gBACtC,SAAS,EAAE,SAAS,CAAC,KAAK;gBAC1B,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE;aACjC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAkB;QAC3B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;QAC7C,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;YACvB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,CAAC;QACD,MAAM,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;CACF;AAtDD,4CAsDC"}

package/dist/destinations/sqs.destination.d.ts

@@ -0,0 +1,20 @@
+import { DomainEvent } from '../domain-event.entity';
+import { DeliveryDestination } from './delivery-destination';
+/**
+ * SqsDestination sends each domain event to an Amazon SQS queue.
+ *
+ * The AWS SDK is loaded LAZILY (require) so it is only needed when this
+ * destination is actually activated at runtime (EVENTS_DESTINATION=sqs). Install
+ * it in the deploying service: `npm install @aws-sdk/client-sqs`.
+ *
+ * Env:
+ *   AWS_REGION           — AWS region (required)
+ *   EVENTS_SQS_QUEUE_URL — target queue URL (required)
+ */
+export declare class SqsDestination implements DeliveryDestination {
+    readonly name = "sqs";
+    private client?;
+    private load;
+    send(event: DomainEvent): Promise<void>;
+}
+//# sourceMappingURL=sqs.destination.d.ts.map

package/dist/destinations/sqs.destination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs.destination.d.ts","sourceRoot":"","sources":["../../src/destinations/sqs.destination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,YAAW,mBAAmB;IACxD,QAAQ,CAAC,IAAI,SAAS;IAGtB,OAAO,CAAC,MAAM,CAAC,CAAM;IAGrB,OAAO,CAAC,IAAI;IAYN,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAgB9C"}

package/dist/destinations/sqs.destination.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqsDestination = void 0;
+/**
+ * SqsDestination sends each domain event to an Amazon SQS queue.
+ *
+ * The AWS SDK is loaded LAZILY (require) so it is only needed when this
+ * destination is actually activated at runtime (EVENTS_DESTINATION=sqs). Install
+ * it in the deploying service: `npm install @aws-sdk/client-sqs`.
+ *
+ * Env:
+ *   AWS_REGION           — AWS region (required)
+ *   EVENTS_SQS_QUEUE_URL — target queue URL (required)
+ */
+class SqsDestination {
+    constructor() {
+        this.name = 'sqs';
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    load() {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+            return require('@aws-sdk/client-sqs');
+        }
+        catch {
+            throw new Error("EVENTS_DESTINATION=sqs requires '@aws-sdk/client-sqs' — run " +
+                '`npm install @aws-sdk/client-sqs`');
+        }
+    }
+    async send(event) {
+        const queueUrl = process.env.EVENTS_SQS_QUEUE_URL;
+        if (!queueUrl) {
+            throw new Error('EVENTS_SQS_QUEUE_URL is not set');
+        }
+        const { SQSClient, SendMessageCommand } = this.load();
+        if (!this.client) {
+            this.client = new SQSClient({ region: process.env.AWS_REGION });
+        }
+        await this.client.send(new SendMessageCommand({
+            QueueUrl: queueUrl,
+            MessageBody: JSON.stringify(event),
+        }));
+    }
+}
+exports.SqsDestination = SqsDestination;
+//# sourceMappingURL=sqs.destination.js.map

package/dist/destinations/sqs.destination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqs.destination.js","sourceRoot":"","sources":["../../src/destinations/sqs.destination.ts"],"names":[],"mappings":";;;AAGA;;;;;;;;;;GAUG;AACH,MAAa,cAAc;IAA3B;QACW,SAAI,GAAG,KAAK,CAAC;IAkCxB,CAAC;IA7BC,8DAA8D;IACtD,IAAI;QACV,IAAI,CAAC;YACH,8EAA8E;YAC9E,OAAO,OAAO,CAAC,qBAAqB,CAAC,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CACb,8DAA8D;gBAC5D,mCAAmC,CACtC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAkB;QAC3B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QAClD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QACD,MAAM,EAAE,SAAS,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACtD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACpB,IAAI,kBAAkB,CAAC;YACrB,QAAQ,EAAE,QAAQ;YAClB,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;SACnC,CAAC,CACH,CAAC;IACJ,CAAC;CACF;AAnCD,wCAmCC"}

package/dist/destinations/webhook.destination.d.ts

@@ -0,0 +1,34 @@
+import { DomainEvent } from '../domain-event.entity';
+import { DeliveryDestination } from './delivery-destination';
+/**
+ * Computes a Standard Webhooks (https://www.standardwebhooks.com/) signature.
+ *
+ * Pure & deterministic: given the same id, timestamp, body and secret it always
+ * returns the same `v1,<base64>` signature header value. Extracted so it can be
+ * unit-tested in isolation from the HTTP transport.
+ *
+ * @param id        The webhook message id (here: the DomainEvent id).
+ * @param timestamp Unix timestamp in SECONDS.
+ * @param body      The exact request body string that will be POSTed.
+ * @param secret    The signing secret, in `whsec_<base64>` form.
+ */
+export declare function signWebhook(id: string, timestamp: number, body: string, secret: string): string;
+/**
+ * WebhookDestination POSTs each domain event to a SINGLE configured URL,
+ * HMAC-signed in the Standard Webhooks format. It is deliberately not a
+ * registry: fan-out to multiple subscribers is an application concern, not a
+ * library one. Reliability comes from the relay's retry loop — this adapter just
+ * throws on any non-2xx response.
+ *
+ * Uses native `fetch` and node `crypto`, so a webhook-only deployment needs zero
+ * extra dependencies.
+ *
+ * Env:
+ *   EVENTS_WEBHOOK_URL    — the single sink URL (required)
+ *   EVENTS_WEBHOOK_SECRET — signing secret as `whsec_<base64>` (required)
+ */
+export declare class WebhookDestination implements DeliveryDestination {
+    readonly name = "webhook";
+    send(event: DomainEvent): Promise<void>;
+}
+//# sourceMappingURL=webhook.destination.d.ts.map

package/dist/destinations/webhook.destination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.destination.d.ts","sourceRoot":"","sources":["../../src/destinations/webhook.destination.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM,CAOR;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAC5D,QAAQ,CAAC,IAAI,aAAa;IAEpB,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAgC9C"}

package/dist/destinations/webhook.destination.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookDestination = void 0;
+exports.signWebhook = signWebhook;
+const crypto_1 = require("crypto");
+/**
+ * Computes a Standard Webhooks (https://www.standardwebhooks.com/) signature.
+ *
+ * Pure & deterministic: given the same id, timestamp, body and secret it always
+ * returns the same `v1,<base64>` signature header value. Extracted so it can be
+ * unit-tested in isolation from the HTTP transport.
+ *
+ * @param id        The webhook message id (here: the DomainEvent id).
+ * @param timestamp Unix timestamp in SECONDS.
+ * @param body      The exact request body string that will be POSTed.
+ * @param secret    The signing secret, in `whsec_<base64>` form.
+ */
+function signWebhook(id, timestamp, body, secret) {
+    const signedContent = `${id}.${timestamp}.${body}`;
+    const secretBytes = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
+    const signature = (0, crypto_1.createHmac)('sha256', secretBytes)
+        .update(signedContent)
+        .digest('base64');
+    return `v1,${signature}`;
+}
+/**
+ * WebhookDestination POSTs each domain event to a SINGLE configured URL,
+ * HMAC-signed in the Standard Webhooks format. It is deliberately not a
+ * registry: fan-out to multiple subscribers is an application concern, not a
+ * library one. Reliability comes from the relay's retry loop — this adapter just
+ * throws on any non-2xx response.
+ *
+ * Uses native `fetch` and node `crypto`, so a webhook-only deployment needs zero
+ * extra dependencies.
+ *
+ * Env:
+ *   EVENTS_WEBHOOK_URL    — the single sink URL (required)
+ *   EVENTS_WEBHOOK_SECRET — signing secret as `whsec_<base64>` (required)
+ */
+class WebhookDestination {
+    constructor() {
+        this.name = 'webhook';
+    }
+    async send(event) {
+        const url = process.env.EVENTS_WEBHOOK_URL;
+        const secret = process.env.EVENTS_WEBHOOK_SECRET;
+        if (!url) {
+            throw new Error('EVENTS_WEBHOOK_URL is not set');
+        }
+        if (!secret) {
+            throw new Error('EVENTS_WEBHOOK_SECRET is not set');
+        }
+        const id = event.id;
+        const timestamp = Math.floor(Date.now() / 1000);
+        const body = JSON.stringify(event);
+        const signature = signWebhook(id, timestamp, body, secret);
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'webhook-id': id,
+                'webhook-timestamp': String(timestamp),
+                'webhook-signature': signature,
+            },
+            body,
+        });
+        if (!response.ok) {
+            throw new Error(`Webhook delivery to ${url} failed with status ${response.status}`);
+        }
+    }
+}
+exports.WebhookDestination = WebhookDestination;
+//# sourceMappingURL=webhook.destination.js.map

package/dist/destinations/webhook.destination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.destination.js","sourceRoot":"","sources":["../../src/destinations/webhook.destination.ts"],"names":[],"mappings":";;;AAgBA,kCAYC;AA5BD,mCAAoC;AAIpC;;;;;;;;;;;GAWG;AACH,SAAgB,WAAW,CACzB,EAAU,EACV,SAAiB,EACjB,IAAY,EACZ,MAAc;IAEd,MAAM,aAAa,GAAG,GAAG,EAAE,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;IACnD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,IAAA,mBAAU,EAAC,QAAQ,EAAE,WAAW,CAAC;SAChD,MAAM,CAAC,aAAa,CAAC;SACrB,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpB,OAAO,MAAM,SAAS,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAa,kBAAkB;IAA/B;QACW,SAAI,GAAG,SAAS,CAAC;IAkC5B,CAAC;IAhCC,KAAK,CAAC,IAAI,CAAC,KAAkB;QAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;QAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;QACjD,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtD,CAAC;QAED,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACnC,MAAM,SAAS,GAAG,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAE3D,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,YAAY,EAAE,EAAE;gBAChB,mBAAmB,EAAE,MAAM,CAAC,SAAS,CAAC;gBACtC,mBAAmB,EAAE,SAAS;aAC/B;YACD,IAAI;SACL,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,uBAAuB,GAAG,uBAAuB,QAAQ,CAAC,MAAM,EAAE,CACnE,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAnCD,gDAmCC"}

package/dist/domain-event.entity.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DomainEvent is a durable, append-only log of domain state changes.
+ *
+ * Rows are written in the SAME database transaction as the state change that
+ * produced them (see {@link DomainEventSubscriber}), which is what makes
+ * delivery durable. This implements the standard "transactional outbox"
+ * pattern, but is surfaced with generic domain-event naming — no public
+ * artifact is named "outbox".
+ *
+ * A separate {@link DomainEventRelay} polls pending rows and delivers them.
+ * Because the stable `id` is preserved across delivery attempts, consumers can
+ * dedupe on it for at-least-once delivery semantics.
+ */
+export declare class DomainEvent {
+    id: string;
+    /** Event type, e.g. "product.created". */
+    type: string;
+    /** Serialized event payload. */
+    payload: Record<string, unknown>;
+    /** Delivery lifecycle: pending -> published, or failed after max attempts. */
+    status: 'pending' | 'published' | 'failed';
+    /** Number of delivery attempts made by the relay. */
+    attempts: number;
+    created_at: Date;
+    /** When the event was successfully published; null until then. */
+    publishedAt: Date | null;
+}
+//# sourceMappingURL=domain-event.entity.d.ts.map

package/dist/domain-event.entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-event.entity.d.ts","sourceRoot":"","sources":["../src/domain-event.entity.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH,qBAEa,WAAW;IAEtB,EAAE,EAAG,MAAM,CAAC;IAEZ,0CAA0C;IAE1C,IAAI,EAAG,MAAM,CAAC;IAEd,gCAAgC;IAEhC,OAAO,EAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC,8EAA8E;IAE9E,MAAM,EAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAE5C,qDAAqD;IAErD,QAAQ,EAAG,MAAM,CAAC;IAGlB,UAAU,EAAG,IAAI,CAAC;IAElB,kEAAkE;IAElE,WAAW,EAAG,IAAI,GAAG,IAAI,CAAC;CAC3B"}