@brightchain/brightchain-api-lib 0.25.0 → 0.26.0

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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"}

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

@@ -0,0 +1,110 @@
+/**
+ * Outbound Queue Store — persistence interface and in-memory implementation
+ * for the outbound email delivery queue.
+ *
+ * The `IOutboundQueueStore` interface defines the contract for queue persistence,
+ * allowing different backends (in-memory for testing, database/filesystem for
+ * production) to be swapped without changing the queue logic.
+ *
+ * The `InMemoryOutboundQueueStore` provides a FIFO-ordered, Map-backed
+ * implementation suitable for unit/integration testing.
+ *
+ * @see Requirements 9.1, 9.3, 9.4
+ * @module outboundQueueStore
+ */
+import type { IOutboundQueueItem } from './emailGatewayService';
+/**
+ * Persistence interface for the outbound email delivery queue.
+ *
+ * Implementations must maintain FIFO ordering (Req 9.3) and support
+ * concurrent access patterns (Req 9.4). The store is responsible only
+ * for persistence — concurrency limiting and processing loops are
+ * handled by the `OutboundQueue` class (task 4.2).
+ *
+ * @see Requirements 9.1, 9.3, 9.4
+ */
+export interface IOutboundQueueStore {
+    /**
+     * Add a message to the end of the queue.
+     *
+     * @param item - The outbound queue item to enqueue
+     * @throws If the store is unavailable (Req 9.5)
+     */
+    enqueue(item: IOutboundQueueItem): Promise<void>;
+    /**
+     * Remove and return the next item from the front of the queue
+     * that is in `Queued` status and ready for delivery.
+     *
+     * @returns The next queue item, or `undefined` if the queue is empty
+     *          or no items are ready
+     */
+    dequeue(): Promise<IOutboundQueueItem | undefined>;
+    /**
+     * Return the next item from the front of the queue without removing it.
+     *
+     * @returns The next queue item, or `undefined` if the queue is empty
+     */
+    peek(): Promise<IOutboundQueueItem | undefined>;
+    /**
+     * Mark a message as successfully delivered and remove it from the queue.
+     *
+     * @param messageId - The RFC 5322 Message-ID of the completed message
+     */
+    markCompleted(messageId: string): Promise<void>;
+    /**
+     * Mark a message as permanently failed and remove it from the active queue.
+     *
+     * @param messageId - The RFC 5322 Message-ID of the failed message
+     * @param reason - Human-readable failure reason
+     */
+    markFailed(messageId: string, reason: string): Promise<void>;
+    /**
+     * Re-enqueue a message for retry with updated retry count and status.
+     *
+     * The item is placed at the end of the queue to maintain FIFO fairness
+     * among messages at the same priority level (Req 9.3).
+     *
+     * @param item - The updated queue item with incremented retryCount
+     */
+    requeue(item: IOutboundQueueItem): Promise<void>;
+    /**
+     * Return the current number of items in the queue.
+     *
+     * @returns The queue depth (number of pending items)
+     */
+    getQueueDepth(): Promise<number>;
+    /**
+     * Retrieve a queue item by its Message-ID.
+     *
+     * @param messageId - The RFC 5322 Message-ID to look up
+     * @returns The queue item, or `undefined` if not found
+     */
+    getByMessageId(messageId: string): Promise<IOutboundQueueItem | undefined>;
+}
+/**
+ * In-memory implementation of `IOutboundQueueStore` for testing.
+ *
+ * Uses a `Map` keyed by messageId for O(1) lookups and an insertion-ordered
+ * array (`queue`) to maintain strict FIFO ordering (Req 9.3).
+ *
+ * This implementation is NOT suitable for production — it does not survive
+ * process restarts (Req 9.1 requires durable storage). Use a database-backed
+ * or filesystem-backed implementation for production deployments.
+ *
+ * @see Requirements 9.1, 9.3, 9.4
+ */
+export declare class InMemoryOutboundQueueStore implements IOutboundQueueStore {
+    /** Ordered list of message IDs representing FIFO queue order. */
+    private readonly queue;
+    /** Map from messageId → queue item for O(1) lookups. */
+    private readonly items;
+    enqueue(item: IOutboundQueueItem): Promise<void>;
+    dequeue(): Promise<IOutboundQueueItem | undefined>;
+    peek(): Promise<IOutboundQueueItem | undefined>;
+    markCompleted(messageId: string): Promise<void>;
+    markFailed(messageId: string, _reason: string): Promise<void>;
+    requeue(item: IOutboundQueueItem): Promise<void>;
+    getQueueDepth(): Promise<number>;
+    getByMessageId(messageId: string): Promise<IOutboundQueueItem | undefined>;
+}
+//# sourceMappingURL=outboundQueueStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"outboundQueueStore.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/outboundQueueStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAEnD;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAEhD;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7D;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjC;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;CAC5E;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,0BAA2B,YAAW,mBAAmB;IACpE,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IAEtC,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8C;IAE9D,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD,OAAO,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC;IAoClD,IAAI,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC;IAW/C,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/C,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7D,OAAO,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUhD,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAWhC,cAAc,CAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC;CAI3C"}

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

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Outbound Queue Store — persistence interface and in-memory implementation
+ * for the outbound email delivery queue.
+ *
+ * The `IOutboundQueueStore` interface defines the contract for queue persistence,
+ * allowing different backends (in-memory for testing, database/filesystem for
+ * production) to be swapped without changing the queue logic.
+ *
+ * The `InMemoryOutboundQueueStore` provides a FIFO-ordered, Map-backed
+ * implementation suitable for unit/integration testing.
+ *
+ * @see Requirements 9.1, 9.3, 9.4
+ * @module outboundQueueStore
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryOutboundQueueStore = void 0;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+/**
+ * In-memory implementation of `IOutboundQueueStore` for testing.
+ *
+ * Uses a `Map` keyed by messageId for O(1) lookups and an insertion-ordered
+ * array (`queue`) to maintain strict FIFO ordering (Req 9.3).
+ *
+ * This implementation is NOT suitable for production — it does not survive
+ * process restarts (Req 9.1 requires durable storage). Use a database-backed
+ * or filesystem-backed implementation for production deployments.
+ *
+ * @see Requirements 9.1, 9.3, 9.4
+ */
+class InMemoryOutboundQueueStore {
+    /** Ordered list of message IDs representing FIFO queue order. */
+    queue = [];
+    /** Map from messageId → queue item for O(1) lookups. */
+    items = new Map();
+    async enqueue(item) {
+        // If an item with the same messageId already exists, replace it
+        // (this can happen on requeue after status update).
+        if (!this.items.has(item.messageId)) {
+            this.queue.push(item.messageId);
+        }
+        this.items.set(item.messageId, { ...item });
+    }
+    async dequeue() {
+        // Walk the queue front-to-back to find the first item in Queued status
+        // that is ready for processing (nextAttemptAt <= now or not set).
+        const now = Date.now();
+        for (let i = 0; i < this.queue.length; i++) {
+            const messageId = this.queue[i];
+            const item = this.items.get(messageId);
+            if (!item) {
+                // Stale entry — item was removed (markCompleted/markFailed).
+                this.queue.splice(i, 1);
+                i--;
+                continue;
+            }
+            if (item.status !== brightchain_lib_1.OutboundDeliveryStatus.Queued) {
+                // Item exists but is not in Queued status — remove stale entry.
+                this.queue.splice(i, 1);
+                i--;
+                continue;
+            }
+            // Respect nextAttemptAt: skip items that are not yet ready.
+            if (item.nextAttemptAt && item.nextAttemptAt.getTime() > now) {
+                continue;
+            }
+            // Item is ready — remove from queue and return.
+            this.queue.splice(i, 1);
+            this.items.delete(messageId);
+            return { ...item };
+        }
+        return undefined;
+    }
+    async peek() {
+        // Walk the queue front-to-back to find the first item in Queued status.
+        for (const messageId of this.queue) {
+            const item = this.items.get(messageId);
+            if (item && item.status === brightchain_lib_1.OutboundDeliveryStatus.Queued) {
+                return { ...item };
+            }
+        }
+        return undefined;
+    }
+    async markCompleted(messageId) {
+        const item = this.items.get(messageId);
+        if (item) {
+            item.status = brightchain_lib_1.OutboundDeliveryStatus.Delivered;
+            this.items.delete(messageId);
+            const idx = this.queue.indexOf(messageId);
+            if (idx !== -1) {
+                this.queue.splice(idx, 1);
+            }
+        }
+    }
+    async markFailed(messageId, _reason) {
+        const item = this.items.get(messageId);
+        if (item) {
+            item.status = brightchain_lib_1.OutboundDeliveryStatus.PermanentFailure;
+            this.items.delete(messageId);
+            const idx = this.queue.indexOf(messageId);
+            if (idx !== -1) {
+                this.queue.splice(idx, 1);
+            }
+        }
+    }
+    async requeue(item) {
+        // Remove old position if present, then append to end for FIFO fairness.
+        const existingIdx = this.queue.indexOf(item.messageId);
+        if (existingIdx !== -1) {
+            this.queue.splice(existingIdx, 1);
+        }
+        this.queue.push(item.messageId);
+        this.items.set(item.messageId, { ...item });
+    }
+    async getQueueDepth() {
+        // Count only items that are still in the items map (not stale references).
+        let count = 0;
+        for (const messageId of this.queue) {
+            if (this.items.has(messageId)) {
+                count++;
+            }
+        }
+        return count;
+    }
+    async getByMessageId(messageId) {
+        const item = this.items.get(messageId);
+        return item ? { ...item } : undefined;
+    }
+}
+exports.InMemoryOutboundQueueStore = InMemoryOutboundQueueStore;
+//# sourceMappingURL=outboundQueueStore.js.map

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

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