@brightchain/brightchain-api-lib 0.25.0 → 0.27.0

package/src/lib/services/emailGateway/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Email Gateway module barrel export.
+ *
+ * Re-exports all public gateway components so consumers can import from
+ * `@brightchain/brightchain-api-lib` (via the services barrel) with a
+ * single import path.
+ *
+ * @see Requirements 11.2, 11.3
+ * @module emailGateway
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./antiSpamFilter"), exports);
+tslib_1.__exportStar(require("./bounceProcessor"), exports);
+tslib_1.__exportStar(require("./emailAuthVerifier"), exports);
+tslib_1.__exportStar(require("./emailGatewayConfig"), exports);
+tslib_1.__exportStar(require("./emailGatewayService"), exports);
+tslib_1.__exportStar(require("./gatewayObservability"), exports);
+tslib_1.__exportStar(require("./inboundProcessor"), exports);
+tslib_1.__exportStar(require("./outboundDeliveryWorker"), exports);
+tslib_1.__exportStar(require("./outboundQueue"), exports);
+tslib_1.__exportStar(require("./outboundQueueStore"), exports);
+tslib_1.__exportStar(require("./recipientLookupService"), exports);
+tslib_1.__exportStar(require("./retryBackoff"), exports);
+//# sourceMappingURL=index.js.map

package/src/lib/services/emailGateway/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,2DAAiC;AACjC,4DAAkC;AAClC,8DAAoC;AACpC,+DAAqC;AACrC,gEAAsC;AACtC,iEAAuC;AACvC,6DAAmC;AACnC,mEAAyC;AACzC,0DAAgC;AAChC,+DAAqC;AACrC,mEAAyC;AACzC,yDAA+B"}

package/src/lib/services/emailGateway/outboundDeliveryWorker.d.ts

@@ -0,0 +1,122 @@
+/**
+ * OutboundDeliveryWorker — dequeues messages from the OutboundQueue,
+ * serializes them to RFC 5322 format, applies DKIM signing, and
+ * delegates delivery to Postfix via sendmail or LMTP.
+ *
+ * The worker registers itself as the OutboundQueue's handler so that
+ * each dequeued item flows through the delivery pipeline:
+ *   1. Enforce max message size
+ *   2. Serialize IEmailMetadata → RFC 5322 via EmailSerializer
+ *   3. Apply DKIM signature
+ *   4. Send via Postfix transport
+ *   5. Update queue status on success/failure
+ *
+ * Transport and DKIM signing are injected as interfaces so the worker
+ * can be tested without real Postfix or key material.
+ *
+ * @see Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 6.1
+ * @module outboundDeliveryWorker
+ */
+import type { IEmailGatewayConfig } from './emailGatewayConfig';
+import type { IDomainAwareComponent } from './emailGatewayService';
+import type { IOutboundQueueItem } from './emailGatewayService';
+import type { OutboundQueue } from './outboundQueue';
+import type { IOutboundQueueStore } from './outboundQueueStore';
+/**
+ * Result returned by the Postfix transport after attempting delivery.
+ */
+export interface IPostfixTransportResult {
+    /** Whether the delivery succeeded. */
+    success: boolean;
+    /** SMTP response code (e.g. 250 for success, 4xx for temp failure, 5xx for permanent). */
+    responseCode: number;
+    /** Human-readable response message from the MTA. */
+    responseMessage: string;
+}
+/**
+ * Interface for delegating email delivery to Postfix via sendmail or LMTP.
+ *
+ * Implementations wrap the actual transport mechanism (child_process sendmail,
+ * LMTP socket, etc.) behind a simple async interface.
+ *
+ * @see Requirement 2.4
+ */
+export interface IPostfixTransport {
+    /**
+     * Send a raw RFC 5322 message to the specified recipients.
+     *
+     * @param from - Envelope sender address
+     * @param to - Envelope recipient addresses
+     * @param rawMessage - Complete RFC 5322 message bytes (with DKIM signature)
+     * @returns Delivery result with SMTP response code
+     */
+    send(from: string, to: string[], rawMessage: Uint8Array): Promise<IPostfixTransportResult>;
+}
+/**
+ * Interface for applying DKIM signatures to outbound messages.
+ *
+ * Implementations read the private key from the configured path and
+ * produce a signed message with the DKIM-Signature header prepended.
+ *
+ * @see Requirement 6.1
+ */
+export interface IDkimSigner {
+    /**
+     * Sign a raw RFC 5322 message with DKIM.
+     *
+     * @param rawMessage - The unsigned RFC 5322 message bytes
+     * @param domain - The signing domain (canonical domain)
+     * @param selector - The DKIM selector for DNS lookup
+     * @returns The signed message bytes with DKIM-Signature header prepended
+     */
+    sign(rawMessage: Uint8Array, domain: string, selector: string): Promise<Uint8Array>;
+}
+/**
+ * Worker that processes outbound email delivery from the queue.
+ *
+ * Registers as the OutboundQueue's handler and processes each dequeued
+ * item through the serialization → DKIM → transport pipeline.
+ *
+ * @see Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 6.1
+ */
+export declare class OutboundDeliveryWorker implements IDomainAwareComponent {
+    private readonly queue;
+    private readonly store;
+    private readonly config;
+    private readonly transport;
+    private readonly dkimSigner;
+    private readonly serializer;
+    /** Current DKIM signing domain — updated via `updateCanonicalDomain()`. */
+    private signingDomain;
+    /**
+     * @param queue - The outbound queue to register as handler on
+     * @param store - Queue store for updating item status on success/failure
+     * @param config - Gateway configuration (max message size, DKIM settings)
+     * @param transport - Postfix transport for actual SMTP delivery
+     * @param dkimSigner - DKIM signer for message authentication
+     */
+    constructor(queue: OutboundQueue, store: IOutboundQueueStore, config: IEmailGatewayConfig, transport: IPostfixTransport, dkimSigner: IDkimSigner);
+    /**
+     * Update the DKIM signing domain for outbound messages.
+     *
+     * @param newDomain - The new canonical domain for DKIM signing
+     *
+     * @see Requirement 8.5 — hot-reload canonical domain without restart
+     */
+    updateCanonicalDomain(newDomain: string): void;
+    /**
+     * Handle a single dequeued outbound queue item.
+     *
+     * Pipeline:
+     * 1. Serialize IEmailMetadata → RFC 5322 via EmailSerializer
+     * 2. Enforce max message size (Req 2.5)
+     * 3. Apply DKIM signature (Req 6.1)
+     * 4. Delegate to Postfix transport (Req 2.4)
+     * 5. Mark completed or failed in the store
+     *
+     * @param item - The dequeued outbound queue item
+     * @throws Re-throws transport errors so the OutboundQueue can requeue
+     */
+    handleItem(item: IOutboundQueueItem): Promise<void>;
+}
+//# sourceMappingURL=outboundDeliveryWorker.d.ts.map

package/src/lib/services/emailGateway/outboundDeliveryWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outboundDeliveryWorker.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/outboundDeliveryWorker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAIhE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,0FAA0F;IAC1F,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EAAE,EACZ,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,IAAI,CACF,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CAAC;CACxB;AAID;;;;;;;GAOG;AACH,qBAAa,sBAAuB,YAAW,qBAAqB;IAchE,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAjB7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAE7C,2EAA2E;IAC3E,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;;OAMG;gBAEgB,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,mBAAmB,EAC3B,SAAS,EAAE,iBAAiB,EAC5B,UAAU,EAAE,WAAW;IAQ1C;;;;;;OAMG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9C;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;CAuC1D"}

package/src/lib/services/emailGateway/outboundDeliveryWorker.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * OutboundDeliveryWorker — dequeues messages from the OutboundQueue,
+ * serializes them to RFC 5322 format, applies DKIM signing, and
+ * delegates delivery to Postfix via sendmail or LMTP.
+ *
+ * The worker registers itself as the OutboundQueue's handler so that
+ * each dequeued item flows through the delivery pipeline:
+ *   1. Enforce max message size
+ *   2. Serialize IEmailMetadata → RFC 5322 via EmailSerializer
+ *   3. Apply DKIM signature
+ *   4. Send via Postfix transport
+ *   5. Update queue status on success/failure
+ *
+ * Transport and DKIM signing are injected as interfaces so the worker
+ * can be tested without real Postfix or key material.
+ *
+ * @see Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 6.1
+ * @module outboundDeliveryWorker
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboundDeliveryWorker = void 0;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+// ─── OutboundDeliveryWorker ─────────────────────────────────────────────────
+/**
+ * Worker that processes outbound email delivery from the queue.
+ *
+ * Registers as the OutboundQueue's handler and processes each dequeued
+ * item through the serialization → DKIM → transport pipeline.
+ *
+ * @see Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 6.1
+ */
+class OutboundDeliveryWorker {
+    queue;
+    store;
+    config;
+    transport;
+    dkimSigner;
+    serializer;
+    /** Current DKIM signing domain — updated via `updateCanonicalDomain()`. */
+    signingDomain;
+    /**
+     * @param queue - The outbound queue to register as handler on
+     * @param store - Queue store for updating item status on success/failure
+     * @param config - Gateway configuration (max message size, DKIM settings)
+     * @param transport - Postfix transport for actual SMTP delivery
+     * @param dkimSigner - DKIM signer for message authentication
+     */
+    constructor(queue, store, config, transport, dkimSigner) {
+        this.queue = queue;
+        this.store = store;
+        this.config = config;
+        this.transport = transport;
+        this.dkimSigner = dkimSigner;
+        this.serializer = new brightchain_lib_1.EmailSerializer();
+        this.signingDomain = config.canonicalDomain;
+        // Register this worker as the queue's handler.
+        this.queue.setHandler(this.handleItem.bind(this));
+    }
+    /**
+     * Update the DKIM signing domain for outbound messages.
+     *
+     * @param newDomain - The new canonical domain for DKIM signing
+     *
+     * @see Requirement 8.5 — hot-reload canonical domain without restart
+     */
+    updateCanonicalDomain(newDomain) {
+        this.signingDomain = newDomain;
+    }
+    /**
+     * Handle a single dequeued outbound queue item.
+     *
+     * Pipeline:
+     * 1. Serialize IEmailMetadata → RFC 5322 via EmailSerializer
+     * 2. Enforce max message size (Req 2.5)
+     * 3. Apply DKIM signature (Req 6.1)
+     * 4. Delegate to Postfix transport (Req 2.4)
+     * 5. Mark completed or failed in the store
+     *
+     * @param item - The dequeued outbound queue item
+     * @throws Re-throws transport errors so the OutboundQueue can requeue
+     */
+    async handleItem(item) {
+        // 1. Serialize metadata to RFC 5322
+        const rawMessage = this.serializer.serialize(item.metadata);
+        // 2. Enforce max message size (Req 2.5)
+        if (rawMessage.byteLength > this.config.maxMessageSizeBytes) {
+            await this.store.markFailed(item.messageId, `Message size ${rawMessage.byteLength} bytes exceeds maximum ${this.config.maxMessageSizeBytes} bytes`);
+            return;
+        }
+        // 3. Apply DKIM signature (Req 6.1)
+        const signedMessage = await this.dkimSigner.sign(rawMessage, this.signingDomain, this.config.dkimSelector);
+        // 4. Delegate to Postfix transport (Req 2.4)
+        const result = await this.transport.send(item.from, item.to, signedMessage);
+        // 5. Update status based on transport result
+        if (result.success) {
+            await this.store.markCompleted(item.messageId);
+        }
+        else if (result.responseCode >= 500) {
+            // Permanent failure (5xx) — mark failed, do not retry
+            await this.store.markFailed(item.messageId, `Permanent failure (${result.responseCode}): ${result.responseMessage}`);
+        }
+        else {
+            // Temporary failure (4xx) — throw so OutboundQueue requeues with retry logic
+            throw new Error(`Temporary failure (${result.responseCode}): ${result.responseMessage}`);
+        }
+    }
+}
+exports.OutboundDeliveryWorker = OutboundDeliveryWorker;
+//# sourceMappingURL=outboundDeliveryWorker.js.map

package/src/lib/services/emailGateway/outboundDeliveryWorker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outboundDeliveryWorker.js","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/outboundDeliveryWorker.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAEH,kEAA+D;AAsE/D,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAa,sBAAsB;IAcd;IACA;IACA;IACA;IACA;IAjBF,UAAU,CAAkB;IAE7C,2EAA2E;IACnE,aAAa,CAAS;IAE9B;;;;;;OAMG;IACH,YACmB,KAAoB,EACpB,KAA0B,EAC1B,MAA2B,EAC3B,SAA4B,EAC5B,UAAuB;QAJvB,UAAK,GAAL,KAAK,CAAe;QACpB,UAAK,GAAL,KAAK,CAAqB;QAC1B,WAAM,GAAN,MAAM,CAAqB;QAC3B,cAAS,GAAT,SAAS,CAAmB;QAC5B,eAAU,GAAV,UAAU,CAAa;QAExC,IAAI,CAAC,UAAU,GAAG,IAAI,iCAAe,EAAE,CAAC;QACxC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,eAAe,CAAC;QAC5C,+CAA+C;QAC/C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,CAAC;IAED;;;;;;OAMG;IACH,qBAAqB,CAAC,SAAiB;QACrC,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,UAAU,CAAC,IAAwB;QACvC,oCAAoC;QACpC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE5D,wCAAwC;QACxC,IAAI,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;YAC5D,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CACzB,IAAI,CAAC,SAAS,EACd,gBAAgB,UAAU,CAAC,UAAU,0BAA0B,IAAI,CAAC,MAAM,CAAC,mBAAmB,QAAQ,CACvG,CAAC;YACF,OAAO;QACT,CAAC;QAED,oCAAoC;QACpC,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,CAC9C,UAAU,EACV,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,MAAM,CAAC,YAAY,CACzB,CAAC;QAEF,6CAA6C;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;QAE5E,6CAA6C;QAC7C,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACjD,CAAC;aAAM,IAAI,MAAM,CAAC,YAAY,IAAI,GAAG,EAAE,CAAC;YACtC,sDAAsD;YACtD,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CACzB,IAAI,CAAC,SAAS,EACd,sBAAsB,MAAM,CAAC,YAAY,MAAM,MAAM,CAAC,eAAe,EAAE,CACxE,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,6EAA6E;YAC7E,MAAM,IAAI,KAAK,CACb,sBAAsB,MAAM,CAAC,YAAY,MAAM,MAAM,CAAC,eAAe,EAAE,CACxE,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAzFD,wDAyFC"}

package/src/lib/services/emailGateway/outboundQueue.d.ts

@@ -0,0 +1,135 @@
+/**
+ * OutboundQueue — persistent FIFO queue with concurrency control for
+ * outbound email delivery.
+ *
+ * Wraps an `IOutboundQueueStore` for persistence and enforces a configurable
+ * concurrency limit on simultaneous deliveries. The processing loop dequeues
+ * items and passes them to a handler callback.
+ *
+ * On `start()`, the queue resumes processing any previously queued messages
+ * that have not exceeded the maximum retry duration (Req 9.2).
+ *
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5
+ * @module outboundQueue
+ */
+import type { IEmailGatewayConfig } from './emailGatewayConfig';
+import type { IOutboundQueue, IOutboundQueueItem } from './emailGatewayService';
+import type { IOutboundQueueStore } from './outboundQueueStore';
+/**
+ * Callback invoked for each dequeued item. The handler is responsible for
+ * performing the actual SMTP delivery (or delegating to a worker).
+ *
+ * @param item - The dequeued outbound queue item
+ * @returns Resolves when the handler has finished processing the item
+ */
+export type OutboundQueueHandler = (item: IOutboundQueueItem) => Promise<void>;
+/**
+ * Persistent FIFO outbound email queue with concurrency control.
+ *
+ * Implements `IOutboundQueue` so the `EmailGatewayService` orchestrator
+ * can enqueue messages without knowing about concurrency or persistence
+ * internals.
+ *
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5
+ */
+export declare class OutboundQueue implements IOutboundQueue {
+    private readonly store;
+    private readonly config;
+    private handler?;
+    /** Whether the processing loop is active. */
+    private running;
+    /** Number of items currently being processed by the handler. */
+    private activeCount;
+    /** Handle for the polling interval so we can clear it on stop(). */
+    private pollTimer;
+    /** Polling interval in milliseconds for the processing loop. */
+    private readonly pollIntervalMs;
+    /**
+     * @param store   - Persistence backend for queue items
+     * @param config  - Gateway configuration (concurrency, retry settings)
+     * @param handler - Callback invoked for each dequeued item
+     * @param pollIntervalMs - How often to poll the store for ready items (default: 1000ms)
+     */
+    constructor(store: IOutboundQueueStore, config: IEmailGatewayConfig, handler?: OutboundQueueHandler | undefined, pollIntervalMs?: number);
+    /**
+     * Set or replace the delivery handler callback.
+     */
+    setHandler(handler: OutboundQueueHandler): void;
+    /**
+     * Enqueue a message for outbound delivery.
+     *
+     * Persists the item to the store. Rejects with an error if the store
+     * is unavailable (Req 9.5).
+     *
+     * @param item - The outbound queue item to enqueue
+     * @throws Error if the store is unavailable
+     *
+     * @see Requirement 9.5
+     */
+    enqueue(item: IOutboundQueueItem): Promise<void>;
+    /**
+     * Start the processing loop.
+     *
+     * On startup, resumes processing any previously queued messages that
+     * have not exceeded the maximum retry duration (Req 9.2). Then begins
+     * polling the store for new items.
+     *
+     * @see Requirements 9.2, 9.4
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the processing loop.
+     *
+     * Clears the polling timer. In-flight handler invocations are allowed
+     * to complete but no new items will be dequeued.
+     */
+    stop(): void;
+    /**
+     * Whether the queue processing loop is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * The number of items currently being processed (in-flight).
+     */
+    getActiveCount(): number;
+    /**
+     * The current queue depth (delegated to the store).
+     */
+    getQueueDepth(): Promise<number>;
+    /**
+     * Resume processing items that were queued before the last shutdown.
+     *
+     * Walks the store and expires any items that have exceeded the maximum
+     * retry duration, then triggers a processing pass for the rest.
+     *
+     * @see Requirement 9.2
+     */
+    private resumeExistingItems;
+    /**
+     * Dequeue and process items up to the concurrency limit.
+     *
+     * Each dequeued item is handed to the handler callback. The concurrency
+     * limit (Req 9.4) is enforced by tracking `activeCount`.
+     */
+    private processAvailable;
+    /**
+     * Process a single dequeued item by invoking the handler.
+     *
+     * If the handler throws, the item is checked against retry limits.
+     * If eligible for retry, it is requeued with an exponential back-off
+     * delay. If limits are exceeded, it is marked as permanently failed.
+     *
+     * @see Requirements 3.1, 3.3, 3.4
+     */
+    private processItem;
+    /**
+     * Determine whether a queue item has exceeded the maximum retry duration.
+     *
+     * @param item - The queue item to check
+     * @returns `true` if the item's age exceeds `config.retryMaxDurationMs`
+     *
+     * @see Requirement 9.2
+     */
+    private isExpired;
+}
+//# sourceMappingURL=outboundQueue.d.ts.map

package/src/lib/services/emailGateway/outboundQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outboundQueue.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/outboundQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGhE;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/E;;;;;;;;GAQG;AACH,qBAAa,aAAc,YAAW,cAAc;IAoBhD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,OAAO,CAAC;IArBlB,6CAA6C;IAC7C,OAAO,CAAC,OAAO,CAAS;IAExB,gEAAgE;IAChE,OAAO,CAAC,WAAW,CAAK;IAExB,oEAAoE;IACpE,OAAO,CAAC,SAAS,CAA+C;IAEhE,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC;;;;;OAKG;gBAEgB,KAAK,EAAE,mBAAmB,EAC1B,MAAM,EAAE,mBAAmB,EACpC,OAAO,CAAC,EAAE,oBAAoB,YAAA,EACtC,cAAc,CAAC,EAAE,MAAM;IAOzB;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAI/C;;;;;;;;;;OAUG;IACG,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUtD;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;;;OAKG;IACH,IAAI,IAAI,IAAI;IAWZ;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAMtC;;;;;;;OAOG;YACW,mBAAmB;IAMjC;;;;;OAKG;YACW,gBAAgB;IA6B9B;;;;;;;;OAQG;YACW,WAAW;IAmCzB;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;CAIlB"}

package/src/lib/services/emailGateway/outboundQueue.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * OutboundQueue — persistent FIFO queue with concurrency control for
+ * outbound email delivery.
+ *
+ * Wraps an `IOutboundQueueStore` for persistence and enforces a configurable
+ * concurrency limit on simultaneous deliveries. The processing loop dequeues
+ * items and passes them to a handler callback.
+ *
+ * On `start()`, the queue resumes processing any previously queued messages
+ * that have not exceeded the maximum retry duration (Req 9.2).
+ *
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5
+ * @module outboundQueue
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboundQueue = void 0;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+const retryBackoff_1 = require("./retryBackoff");
+/**
+ * Persistent FIFO outbound email queue with concurrency control.
+ *
+ * Implements `IOutboundQueue` so the `EmailGatewayService` orchestrator
+ * can enqueue messages without knowing about concurrency or persistence
+ * internals.
+ *
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5
+ */
+class OutboundQueue {
+    store;
+    config;
+    handler;
+    /** Whether the processing loop is active. */
+    running = false;
+    /** Number of items currently being processed by the handler. */
+    activeCount = 0;
+    /** Handle for the polling interval so we can clear it on stop(). */
+    pollTimer = null;
+    /** Polling interval in milliseconds for the processing loop. */
+    pollIntervalMs;
+    /**
+     * @param store   - Persistence backend for queue items
+     * @param config  - Gateway configuration (concurrency, retry settings)
+     * @param handler - Callback invoked for each dequeued item
+     * @param pollIntervalMs - How often to poll the store for ready items (default: 1000ms)
+     */
+    constructor(store, config, handler, pollIntervalMs) {
+        this.store = store;
+        this.config = config;
+        this.handler = handler;
+        this.pollIntervalMs = pollIntervalMs ?? 1000;
+    }
+    // ─── Public API ─────────────────────────────────────────────────────
+    /**
+     * Set or replace the delivery handler callback.
+     */
+    setHandler(handler) {
+        this.handler = handler;
+    }
+    /**
+     * Enqueue a message for outbound delivery.
+     *
+     * Persists the item to the store. Rejects with an error if the store
+     * is unavailable (Req 9.5).
+     *
+     * @param item - The outbound queue item to enqueue
+     * @throws Error if the store is unavailable
+     *
+     * @see Requirement 9.5
+     */
+    async enqueue(item) {
+        try {
+            await this.store.enqueue(item);
+        }
+        catch (err) {
+            throw new Error(`Outbound queue store unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Start the processing loop.
+     *
+     * On startup, resumes processing any previously queued messages that
+     * have not exceeded the maximum retry duration (Req 9.2). Then begins
+     * polling the store for new items.
+     *
+     * @see Requirements 9.2, 9.4
+     */
+    async start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        // Resume: process any items already in the store that are still valid.
+        await this.resumeExistingItems();
+        // Start the polling loop.
+        this.pollTimer = setInterval(() => {
+            void this.processAvailable();
+        }, this.pollIntervalMs);
+    }
+    /**
+     * Stop the processing loop.
+     *
+     * Clears the polling timer. In-flight handler invocations are allowed
+     * to complete but no new items will be dequeued.
+     */
+    stop() {
+        if (!this.running) {
+            return;
+        }
+        this.running = false;
+        if (this.pollTimer !== null) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    /**
+     * Whether the queue processing loop is currently running.
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * The number of items currently being processed (in-flight).
+     */
+    getActiveCount() {
+        return this.activeCount;
+    }
+    /**
+     * The current queue depth (delegated to the store).
+     */
+    async getQueueDepth() {
+        return this.store.getQueueDepth();
+    }
+    // ─── Internal Processing ────────────────────────────────────────────
+    /**
+     * Resume processing items that were queued before the last shutdown.
+     *
+     * Walks the store and expires any items that have exceeded the maximum
+     * retry duration, then triggers a processing pass for the rest.
+     *
+     * @see Requirement 9.2
+     */
+    async resumeExistingItems() {
+        // We process available items which will naturally skip expired ones
+        // via the dequeue + expiry check in processItem.
+        await this.processAvailable();
+    }
+    /**
+     * Dequeue and process items up to the concurrency limit.
+     *
+     * Each dequeued item is handed to the handler callback. The concurrency
+     * limit (Req 9.4) is enforced by tracking `activeCount`.
+     */
+    async processAvailable() {
+        if (!this.running || !this.handler) {
+            return;
+        }
+        while (this.activeCount < this.config.queueConcurrency && this.running) {
+            const item = await this.store.dequeue();
+            if (!item) {
+                // No more items ready for processing.
+                break;
+            }
+            // Check if the item has exceeded the max retry duration (Req 9.2).
+            if (this.isExpired(item)) {
+                await this.store.markFailed(item.messageId, 'Maximum retry duration exceeded');
+                continue;
+            }
+            // Process the item with concurrency tracking.
+            this.activeCount++;
+            void this.processItem(item).finally(() => {
+                this.activeCount--;
+            });
+        }
+    }
+    /**
+     * Process a single dequeued item by invoking the handler.
+     *
+     * If the handler throws, the item is checked against retry limits.
+     * If eligible for retry, it is requeued with an exponential back-off
+     * delay. If limits are exceeded, it is marked as permanently failed.
+     *
+     * @see Requirements 3.1, 3.3, 3.4
+     */
+    async processItem(item) {
+        if (!this.handler) {
+            return;
+        }
+        try {
+            await this.handler(item);
+        }
+        catch {
+            // Handler failed — check if the item is eligible for retry.
+            const nextRetryCount = item.retryCount + 1;
+            const retryCandidate = { retryCount: nextRetryCount, enqueuedAt: item.enqueuedAt };
+            if ((0, retryBackoff_1.shouldRetry)(retryCandidate, this.config)) {
+                // Eligible for retry — requeue with back-off delay.
+                const nextAttemptAt = (0, retryBackoff_1.computeNextAttemptAt)(this.config.retryBaseIntervalMs, item.retryCount);
+                const requeued = {
+                    ...item,
+                    status: brightchain_lib_1.OutboundDeliveryStatus.Queued,
+                    retryCount: nextRetryCount,
+                    nextAttemptAt,
+                };
+                await this.store.requeue(requeued);
+            }
+            else {
+                // Retry limits exceeded — mark permanently failed (Req 3.4).
+                await this.store.markFailed(item.messageId, `Retry limits exceeded (retryCount=${nextRetryCount}, maxCount=${this.config.retryMaxCount}, maxDuration=${this.config.retryMaxDurationMs}ms)`);
+            }
+        }
+    }
+    /**
+     * Determine whether a queue item has exceeded the maximum retry duration.
+     *
+     * @param item - The queue item to check
+     * @returns `true` if the item's age exceeds `config.retryMaxDurationMs`
+     *
+     * @see Requirement 9.2
+     */
+    isExpired(item) {
+        const age = Date.now() - item.enqueuedAt.getTime();
+        return age > this.config.retryMaxDurationMs;
+    }
+}
+exports.OutboundQueue = OutboundQueue;
+//# sourceMappingURL=outboundQueue.js.map

package/src/lib/services/emailGateway/outboundQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outboundQueue.js","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/outboundQueue.ts"],"names":[],"mappings":"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"}