@brightchain/brightchain-api-lib 0.25.0 → 0.27.0

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

@@ -0,0 +1,209 @@
+/**
+ * EmailGatewayService — orchestrator that bridges BrightChain's internal
+ * gossip-based messaging with external SMTP email delivery via Postfix.
+ *
+ * Responsibilities:
+ * - Listen for gossip announcements containing outbound email
+ * - Extract message blocks from the Block Store
+ * - Detect external recipients by comparing domain against canonicalDomain
+ * - Enqueue outbound messages for SMTP delivery
+ *
+ * @see Requirements 1.1, 1.2, 1.4
+ * @module emailGatewayService
+ */
+import type { IBlockStore, IEmailMetadata, IGossipService } from '@brightchain/brightchain-lib';
+import { EmailMessageService, OutboundDeliveryStatus } from '@brightchain/brightchain-lib';
+import type { IEmailGatewayConfig } from './emailGatewayConfig';
+/**
+ * Minimal interface for the outbound email queue.
+ *
+ * The full `OutboundQueue` class (task 4.2) will implement this.
+ * Using an interface here keeps the orchestrator decoupled from the
+ * queue's internal persistence and concurrency details.
+ */
+export interface IOutboundQueue {
+    /**
+     * Add a message to the outbound delivery queue.
+     *
+     * @param message - Outbound message payload with recipient, content, and retry metadata
+     */
+    enqueue(message: IOutboundQueueItem): Promise<void>;
+}
+/**
+ * Interface for gateway components that support hot-reload of the canonical domain.
+ *
+ * Components implementing this interface can be registered with the
+ * `EmailGatewayService` so that when the canonical domain changes,
+ * all components are updated without requiring a restart.
+ *
+ * @see Requirement 8.5 — dynamic configuration reload
+ */
+export interface IDomainAwareComponent {
+    /**
+     * Update the canonical domain used by this component.
+     *
+     * Implementations should apply the new domain immediately and clear
+     * any caches that depend on the old domain value.
+     *
+     * @param newDomain - The new canonical email domain
+     */
+    updateCanonicalDomain(newDomain: string): void;
+}
+/**
+ * A single item placed on the outbound delivery queue.
+ */
+export interface IOutboundQueueItem {
+    /** RFC 5322 Message-ID */
+    messageId: string;
+    /** Sender email address */
+    from: string;
+    /** External recipient email addresses */
+    to: string[];
+    /** Email subject */
+    subject?: string;
+    /** Full email metadata for serialization */
+    metadata: IEmailMetadata;
+    /** Timestamp when the item was enqueued */
+    enqueuedAt: Date;
+    /** Current delivery status */
+    status: OutboundDeliveryStatus;
+    /** Number of delivery attempts so far */
+    retryCount: number;
+    /** Earliest time at which the next delivery attempt should be made */
+    nextAttemptAt?: Date;
+}
+/**
+ * Orchestrator service for the Email Gateway.
+ *
+ * Listens for gossip announcements that carry outbound email, extracts the
+ * message content from the Block Store, identifies external recipients by
+ * comparing their domain against the configured `canonicalDomain`, and
+ * enqueues qualifying messages in the OutboundQueue for SMTP delivery.
+ *
+ * Lifecycle:
+ * - `start()` registers the gossip announcement listener
+ * - `stop()` removes the listener and performs cleanup
+ *
+ * @see Requirements 1.1, 1.2, 1.4
+ */
+export declare class EmailGatewayService {
+    private readonly config;
+    private readonly gossipService;
+    private readonly blockStore;
+    private readonly emailMessageService;
+    private outboundQueue?;
+    /** Bound reference kept so we can unsubscribe on stop(). */
+    private readonly boundAnnouncementHandler;
+    /** Whether the service is currently running. */
+    private running;
+    /**
+     * Registered domain-aware child components that receive canonical domain
+     * updates when `updateCanonicalDomain()` is called.
+     *
+     * @see Requirement 8.5 — hot-reload canonical domain without restart
+     */
+    private readonly domainAwareComponents;
+    /**
+     * @param config          - Gateway configuration (canonical domain, limits, etc.)
+     * @param gossipService   - Gossip protocol service for subscribing to announcements
+     * @param blockStore      - Block store for retrieving message content blocks
+     * @param emailMessageService - Email message service for retrieving email metadata
+     * @param outboundQueue   - Queue for outbound SMTP delivery (optional; set later via `setOutboundQueue`)
+     */
+    constructor(config: IEmailGatewayConfig, gossipService: IGossipService, blockStore: IBlockStore, emailMessageService: EmailMessageService, outboundQueue?: IOutboundQueue | undefined);
+    /**
+     * Start the gateway service.
+     *
+     * Registers a gossip announcement listener that intercepts outbound
+     * email announcements and delegates them to the outbound queue.
+     */
+    start(): void;
+    /**
+     * Stop the gateway service.
+     *
+     * Removes the gossip listener and marks the service as stopped.
+     */
+    stop(): void;
+    /**
+     * Whether the service is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Wire the outbound queue after construction.
+     *
+     * Useful when the queue is created after the gateway service (e.g.
+     * during staged initialisation).
+     */
+    setOutboundQueue(queue: IOutboundQueue): void;
+    /**
+     * Register a child component that should be notified when the
+     * canonical domain changes.
+     *
+     * @param component - A component implementing `IDomainAwareComponent`
+     *
+     * @see Requirement 8.5 — hot-reload canonical domain without restart
+     */
+    registerDomainAwareComponent(component: IDomainAwareComponent): void;
+    /**
+     * Update the canonical domain across the gateway and all registered
+     * child components without requiring a restart.
+     *
+     * This method:
+     * 1. Updates the shared `IEmailGatewayConfig.canonicalDomain`
+     * 2. Propagates the new domain to all registered `IDomainAwareComponent`s
+     *    (e.g. OutboundDeliveryWorker for DKIM signing, RecipientLookupService
+     *    for inbound validation, BounceProcessor for VERP parsing)
+     *
+     * @param newDomain - The new canonical email domain
+     *
+     * @see Requirement 8.5 — when the canonical domain changes, update all
+     *   gateway components for outbound signing and inbound recipient
+     *   validation without requiring a restart
+     */
+    updateCanonicalDomain(newDomain: string): void;
+    /**
+     * Get the current canonical domain.
+     */
+    getCanonicalDomain(): string;
+    /**
+     * Determine whether an email address is external (not on the canonical domain).
+     *
+     * Extracts the domain portion of the address and compares it
+     * case-insensitively against `config.canonicalDomain`.
+     *
+     * @param emailAddress - A full email address (e.g. `alice@example.com`)
+     * @returns `true` when the address belongs to an external domain
+     *
+     * @see Requirement 1.1 — detect recipients whose domain ≠ canonical domain
+     */
+    isExternalRecipient(emailAddress: string): boolean;
+    /**
+     * Partition a list of email addresses into internal and external groups.
+     *
+     * @param addresses - Array of email addresses
+     * @returns Object with `internal` and `external` arrays
+     *
+     * @see Requirement 1.4 — mixed internal/external recipient handling
+     */
+    partitionRecipients(addresses: string[]): {
+        internal: string[];
+        external: string[];
+    };
+    /**
+     * Handle a gossip message-delivery announcement.
+     *
+     * When an announcement carries `messageDelivery` metadata the handler:
+     * 1. Retrieves the email metadata from the EmailMessageService
+     * 2. Identifies external recipients
+     * 3. Enqueues the message in the OutboundQueue for SMTP delivery
+     *
+     * Internal-only messages are ignored — they are already delivered via gossip.
+     *
+     * @param announcement - The gossip BlockAnnouncement with messageDelivery metadata
+     *
+     * @see Requirement 1.2 — extract message from Block Store and enqueue
+     * @see Requirement 1.4 — route external recipients to gateway
+     */
+    private handleAnnouncement;
+}
+//# sourceMappingURL=emailGatewayService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emailGatewayService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/emailGatewayService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAEV,WAAW,EACX,cAAc,EACd,cAAc,EACf,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAOhE;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAElB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,yCAAyC;IACzC,EAAE,EAAE,MAAM,EAAE,CAAC;IAEb,oBAAoB;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,4CAA4C;IAC5C,QAAQ,EAAE,cAAc,CAAC;IAEzB,2CAA2C;IAC3C,UAAU,EAAE,IAAI,CAAC;IAEjB,8BAA8B;IAC9B,MAAM,EAAE,sBAAsB,CAAC;IAE/B,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IAEnB,sEAAsE;IACtE,aAAa,CAAC,EAAE,IAAI,CAAC;CACtB;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAmB;IAyB5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,aAAa,CAAC;IA5BxB,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAE/B;IAEV,gDAAgD;IAChD,OAAO,CAAC,OAAO,CAAS;IAExB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA+B;IAErE;;;;;;OAMG;gBAEgB,MAAM,EAAE,mBAAmB,EAC3B,aAAa,EAAE,cAAc,EAC7B,UAAU,EAAE,WAAW,EACvB,mBAAmB,EAAE,mBAAmB,EACjD,aAAa,CAAC,EAAE,cAAc,YAAA;IAQxC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAQb;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAQZ;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAM7C;;;;;;;OAOG;IACH,4BAA4B,CAAC,SAAS,EAAE,qBAAqB,GAAG,IAAI;IAIpE;;;;;;;;;;;;;;;OAeG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAe9C;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAM5B;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAUlD;;;;;;;OAOG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG;QACxC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB;IAeD;;;;;;;;;;;;;;OAcG;YACW,kBAAkB;CAoDjC"}

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

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * EmailGatewayService — orchestrator that bridges BrightChain's internal
+ * gossip-based messaging with external SMTP email delivery via Postfix.
+ *
+ * Responsibilities:
+ * - Listen for gossip announcements containing outbound email
+ * - Extract message blocks from the Block Store
+ * - Detect external recipients by comparing domain against canonicalDomain
+ * - Enqueue outbound messages for SMTP delivery
+ *
+ * @see Requirements 1.1, 1.2, 1.4
+ * @module emailGatewayService
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailGatewayService = void 0;
+const brightchain_lib_1 = require("@brightchain/brightchain-lib");
+// ─── EmailGatewayService ────────────────────────────────────────────────────
+/**
+ * Orchestrator service for the Email Gateway.
+ *
+ * Listens for gossip announcements that carry outbound email, extracts the
+ * message content from the Block Store, identifies external recipients by
+ * comparing their domain against the configured `canonicalDomain`, and
+ * enqueues qualifying messages in the OutboundQueue for SMTP delivery.
+ *
+ * Lifecycle:
+ * - `start()` registers the gossip announcement listener
+ * - `stop()` removes the listener and performs cleanup
+ *
+ * @see Requirements 1.1, 1.2, 1.4
+ */
+class EmailGatewayService {
+    config;
+    gossipService;
+    blockStore;
+    emailMessageService;
+    outboundQueue;
+    /** Bound reference kept so we can unsubscribe on stop(). */
+    boundAnnouncementHandler;
+    /** Whether the service is currently running. */
+    running = false;
+    /**
+     * Registered domain-aware child components that receive canonical domain
+     * updates when `updateCanonicalDomain()` is called.
+     *
+     * @see Requirement 8.5 — hot-reload canonical domain without restart
+     */
+    domainAwareComponents = [];
+    /**
+     * @param config          - Gateway configuration (canonical domain, limits, etc.)
+     * @param gossipService   - Gossip protocol service for subscribing to announcements
+     * @param blockStore      - Block store for retrieving message content blocks
+     * @param emailMessageService - Email message service for retrieving email metadata
+     * @param outboundQueue   - Queue for outbound SMTP delivery (optional; set later via `setOutboundQueue`)
+     */
+    constructor(config, gossipService, blockStore, emailMessageService, outboundQueue) {
+        this.config = config;
+        this.gossipService = gossipService;
+        this.blockStore = blockStore;
+        this.emailMessageService = emailMessageService;
+        this.outboundQueue = outboundQueue;
+        // Bind once so the same reference is used for on/off.
+        this.boundAnnouncementHandler = this.handleAnnouncement.bind(this);
+    }
+    // ─── Lifecycle ──────────────────────────────────────────────────────
+    /**
+     * Start the gateway service.
+     *
+     * Registers a gossip announcement listener that intercepts outbound
+     * email announcements and delegates them to the outbound queue.
+     */
+    start() {
+        if (this.running) {
+            return;
+        }
+        this.gossipService.onMessageDelivery(this.boundAnnouncementHandler);
+        this.running = true;
+    }
+    /**
+     * Stop the gateway service.
+     *
+     * Removes the gossip listener and marks the service as stopped.
+     */
+    stop() {
+        if (!this.running) {
+            return;
+        }
+        this.gossipService.offMessageDelivery(this.boundAnnouncementHandler);
+        this.running = false;
+    }
+    /**
+     * Whether the service is currently running.
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Wire the outbound queue after construction.
+     *
+     * Useful when the queue is created after the gateway service (e.g.
+     * during staged initialisation).
+     */
+    setOutboundQueue(queue) {
+        this.outboundQueue = queue;
+    }
+    // ─── Hot-Reload: Canonical Domain ──────────────────────────────────
+    /**
+     * Register a child component that should be notified when the
+     * canonical domain changes.
+     *
+     * @param component - A component implementing `IDomainAwareComponent`
+     *
+     * @see Requirement 8.5 — hot-reload canonical domain without restart
+     */
+    registerDomainAwareComponent(component) {
+        this.domainAwareComponents.push(component);
+    }
+    /**
+     * Update the canonical domain across the gateway and all registered
+     * child components without requiring a restart.
+     *
+     * This method:
+     * 1. Updates the shared `IEmailGatewayConfig.canonicalDomain`
+     * 2. Propagates the new domain to all registered `IDomainAwareComponent`s
+     *    (e.g. OutboundDeliveryWorker for DKIM signing, RecipientLookupService
+     *    for inbound validation, BounceProcessor for VERP parsing)
+     *
+     * @param newDomain - The new canonical email domain
+     *
+     * @see Requirement 8.5 — when the canonical domain changes, update all
+     *   gateway components for outbound signing and inbound recipient
+     *   validation without requiring a restart
+     */
+    updateCanonicalDomain(newDomain) {
+        const trimmed = newDomain.trim();
+        if (trimmed.length === 0) {
+            return; // Ignore empty domain updates
+        }
+        // Update the shared config object (all components hold a reference to it).
+        this.config.canonicalDomain = trimmed;
+        // Propagate to all registered domain-aware components.
+        for (const component of this.domainAwareComponents) {
+            component.updateCanonicalDomain(trimmed);
+        }
+    }
+    /**
+     * Get the current canonical domain.
+     */
+    getCanonicalDomain() {
+        return this.config.canonicalDomain;
+    }
+    // ─── Domain Check ──────────────────────────────────────────────────
+    /**
+     * Determine whether an email address is external (not on the canonical domain).
+     *
+     * Extracts the domain portion of the address and compares it
+     * case-insensitively against `config.canonicalDomain`.
+     *
+     * @param emailAddress - A full email address (e.g. `alice@example.com`)
+     * @returns `true` when the address belongs to an external domain
+     *
+     * @see Requirement 1.1 — detect recipients whose domain ≠ canonical domain
+     */
+    isExternalRecipient(emailAddress) {
+        const atIndex = emailAddress.lastIndexOf('@');
+        if (atIndex === -1) {
+            // Malformed address — treat as external to be safe.
+            return true;
+        }
+        const domain = emailAddress.slice(atIndex + 1).toLowerCase();
+        return domain !== this.config.canonicalDomain.toLowerCase();
+    }
+    /**
+     * Partition a list of email addresses into internal and external groups.
+     *
+     * @param addresses - Array of email addresses
+     * @returns Object with `internal` and `external` arrays
+     *
+     * @see Requirement 1.4 — mixed internal/external recipient handling
+     */
+    partitionRecipients(addresses) {
+        const internal = [];
+        const external = [];
+        for (const addr of addresses) {
+            if (this.isExternalRecipient(addr)) {
+                external.push(addr);
+            }
+            else {
+                internal.push(addr);
+            }
+        }
+        return { internal, external };
+    }
+    // ─── Gossip Announcement Handler ───────────────────────────────────
+    /**
+     * Handle a gossip message-delivery announcement.
+     *
+     * When an announcement carries `messageDelivery` metadata the handler:
+     * 1. Retrieves the email metadata from the EmailMessageService
+     * 2. Identifies external recipients
+     * 3. Enqueues the message in the OutboundQueue for SMTP delivery
+     *
+     * Internal-only messages are ignored — they are already delivered via gossip.
+     *
+     * @param announcement - The gossip BlockAnnouncement with messageDelivery metadata
+     *
+     * @see Requirement 1.2 — extract message from Block Store and enqueue
+     * @see Requirement 1.4 — route external recipients to gateway
+     */
+    async handleAnnouncement(announcement) {
+        const delivery = announcement.messageDelivery;
+        if (!delivery) {
+            return;
+        }
+        // Retrieve the email metadata via the message ID.
+        const metadata = await this.emailMessageService.getEmail(delivery.messageId);
+        if (!metadata) {
+            // Message not found — nothing to route.
+            return;
+        }
+        // Collect all recipient addresses from the metadata.
+        const allRecipients = [
+            ...metadata.to.map((m) => m.address),
+            ...(metadata.cc ?? []).map((m) => m.address),
+            ...(metadata.bcc ?? []).map((m) => m.address),
+        ];
+        // Partition into internal / external.
+        const { external } = this.partitionRecipients(allRecipients);
+        if (external.length === 0) {
+            // Purely internal delivery — nothing for the gateway to do.
+            return;
+        }
+        if (!this.outboundQueue) {
+            // Queue not wired yet — cannot enqueue. This is a configuration issue.
+            // In production this would be logged/alerted; for now we silently skip.
+            return;
+        }
+        // Build the queue item and enqueue.
+        const queueItem = {
+            messageId: metadata.messageId,
+            from: metadata.from.address,
+            to: external,
+            subject: metadata.subject,
+            metadata,
+            enqueuedAt: new Date(),
+            status: brightchain_lib_1.OutboundDeliveryStatus.Queued,
+            retryCount: 0,
+        };
+        await this.outboundQueue.enqueue(queueItem);
+    }
+}
+exports.EmailGatewayService = EmailGatewayService;
+//# sourceMappingURL=emailGatewayService.js.map

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

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

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

@@ -0,0 +1,123 @@
+/**
+ * Gateway Observability
+ *
+ * Provides unified logging, metrics collection, and alerting for all
+ * Email Gateway components. Wraps the existing `IMessageLogger`,
+ * `IMessageMetricsCollector`, and `AlertMonitor` services to add
+ * gateway-specific observability.
+ *
+ * @see Requirements 10.1, 10.2, 10.3, 10.4, 10.5
+ * @module gatewayObservability
+ */
+import type { IEmailAuthenticationResult } from '@brightchain/brightchain-lib';
+import { type IMessageLogger, type IMessageMetricsCollector, AlertMonitor } from '@brightchain/brightchain-lib';
+/**
+ * Gateway-specific metrics snapshot exposed by `GatewayObservability`.
+ *
+ * @see Requirement 10.3
+ */
+export interface IGatewayMetricsSnapshot {
+    /** Current number of messages in the outbound queue */
+    outboundQueueDepth: number;
+    /** Total successful deliveries since last reset */
+    deliverySuccessCount: number;
+    /** Total failed deliveries since last reset */
+    deliveryFailureCount: number;
+    /** Delivery success rate (0–1) */
+    deliverySuccessRate: number;
+    /** Delivery failure rate (0–1) */
+    deliveryFailureRate: number;
+    /** Average delivery latency in milliseconds */
+    averageDeliveryLatencyMs: number;
+    /** Total spam rejections since last reset */
+    spamRejectionCount: number;
+    /** Spam rejection rate (0–1, relative to total inbound) */
+    spamRejectionRate: number;
+    /** Total inbound messages processed since last reset */
+    totalInboundProcessed: number;
+}
+/**
+ * Centralised observability for the Email Gateway.
+ *
+ * Integrates with the existing `IMessageLogger`, `IMessageMetricsCollector`,
+ * and `AlertMonitor` services so that all gateway events flow through the
+ * same infrastructure used by the rest of BrightChain.
+ *
+ * @see Requirements 10.1, 10.2, 10.3, 10.4, 10.5
+ */
+export declare class GatewayObservability {
+    private readonly logger;
+    private readonly metrics;
+    private readonly alertMonitor;
+    private _outboundQueueDepth;
+    private _deliverySuccessCount;
+    private _deliveryFailureCount;
+    private _totalDeliveryLatencyMs;
+    private _spamRejectionCount;
+    private _totalInboundProcessed;
+    constructor(logger: IMessageLogger, metrics: IMessageMetricsCollector, alertMonitor: AlertMonitor);
+    /**
+     * Log an outbound delivery attempt.
+     *
+     * Delegates to `IMessageLogger.logMessageCreated` for consistent logging
+     * and records the attempt in the metrics collector.
+     *
+     * @see Requirement 10.1
+     */
+    logOutboundAttempt(recipient: string, statusCode: number, retryCount: number, timestamp: Date): void;
+    /**
+     * Log an inbound email processing event.
+     *
+     * @see Requirement 10.2
+     */
+    logInboundProcessing(sender: string, recipient: string, spamScore: number, authResults: IEmailAuthenticationResult, accepted: boolean): void;
+    /**
+     * Record the current outbound queue depth.
+     *
+     * @see Requirement 10.3
+     */
+    recordQueueDepth(depth: number): void;
+    /**
+     * Record a successful delivery and its latency.
+     *
+     * @see Requirement 10.3
+     */
+    recordDeliverySuccess(latencyMs?: number): void;
+    /**
+     * Record a delivery failure.
+     *
+     * @see Requirement 10.3
+     */
+    recordDeliveryFailure(): void;
+    /**
+     * Record delivery latency in milliseconds.
+     *
+     * @see Requirement 10.3
+     */
+    recordDeliveryLatency(ms: number): void;
+    /**
+     * Record a spam rejection.
+     *
+     * @see Requirement 10.3
+     */
+    recordSpamRejection(): void;
+    /**
+     * Emit an alert when delivery fails after all retries are exhausted.
+     *
+     * Delegates to the existing `AlertMonitor` for consistent alerting.
+     *
+     * @see Requirement 10.5
+     */
+    alertDeliveryExhausted(messageId: string, recipient: string, retryCount: number): void;
+    /**
+     * Return a point-in-time snapshot of all gateway-specific metrics.
+     *
+     * @see Requirement 10.3
+     */
+    getMetricsSnapshot(): IGatewayMetricsSnapshot;
+    /**
+     * Reset all gateway-specific counters.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=gatewayObservability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gatewayObservability.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/services/emailGateway/gatewayObservability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,YAAY,EACb,MAAM,8BAA8B,CAAC;AAEtC;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kCAAkC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kCAAkC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,wBAAwB,EAAE,MAAM,CAAC;IACjC,6CAA6C;IAC7C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;IAU7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAV/B,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,uBAAuB,CAAK;IACpC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,sBAAsB,CAAK;gBAGhB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,wBAAwB,EACjC,YAAY,EAAE,YAAY;IAK7C;;;;;;;OAOG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,IAAI,GACd,IAAI;IA2BP;;;;OAIG;IACH,oBAAoB,CAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,0BAA0B,EACvC,QAAQ,EAAE,OAAO,GAChB,IAAI;IAoBP;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKrC;;;;OAIG;IACH,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAU/C;;;;OAIG;IACH,qBAAqB,IAAI,IAAI;IAK7B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKvC;;;;OAIG;IACH,mBAAmB,IAAI,IAAI;IAQ3B;;;;;;OAMG;IACH,sBAAsB,CACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,IAAI;IAqBP;;;;OAIG;IACH,kBAAkB,IAAI,uBAAuB;IAwB7C;;OAEG;IACH,KAAK,IAAI,IAAI;CASd"}