@push.rocks/smartmta 6.5.2 → 8.0.0

package/dist_ts/mail/delivery/classes.delivery.queue.d.ts

@@ -1,17 +1,47 @@
 import { EventEmitter } from 'node:events';
+import type { IBlobStorageManager } from '../interfaces.storage.js';
 import { type EmailProcessingMode } from './interfaces.js';
+import type { ISmtpTransactionAttempt } from './interfaces.js';
 import type { IEmailRoute } from '../routing/interfaces.js';
+import { Email } from '../core/classes.email.js';
 /**
  * Queue item status
  */
 export type QueueItemStatus = 'pending' | 'processing' | 'delivered' | 'failed' | 'deferred';
+export type TRecipientDeliveryState = 'unresolved' | 'delivered' | 'permanentFailure';
+export interface IRecipientDeliveryState {
+    recipient: string;
+    normalizedRecipient: string;
+    state: TRecipientDeliveryState;
+    smtpCode?: number;
+    smtpResponse?: string;
+    updatedAt: Date;
+}
+export interface IRecipientPermanentFailure {
+    recipient: string;
+    smtpCode: number;
+    smtpResponse: string;
+}
+export interface IBounceOperation {
+    operationId: string;
+    kind: 'smtpFailure';
+    recipient: string;
+    normalizedRecipient: string;
+    smtpCode: number;
+    smtpResponse: string;
+    state: 'pending' | 'completed';
+    attempts: number;
+    nextAttempt: Date;
+    lastError?: string;
+    completedAt?: Date;
+}
 /**
  * Queue item interface
  */
 export interface IQueueItem {
     id: string;
     processingMode: EmailProcessingMode;
-    processingResult: any;
+    processingResult: Email;
     route?: IEmailRoute;
     status: QueueItemStatus;
     attempts: number;
@@ -20,13 +50,31 @@ export interface IQueueItem {
     createdAt: Date;
     updatedAt: Date;
     deliveredAt?: Date;
+    deliveredRecipients?: string[];
+    terminalRecipients?: string[];
+    recipientStates?: IRecipientDeliveryState[];
+    bounceOperations?: IBounceOperation[];
+    smtpTransactions?: ISmtpTransactionAttempt[];
+}
+export interface IQueueFailureOptions {
+    /** Unknown failures default to retryable so temporary internal faults do not lose mail. */
+    retryable?: boolean;
+}
+export interface IQueueFailureTransition {
+    updated: boolean;
+    status?: 'deferred' | 'failed';
+    terminal: boolean;
+    terminalReason?: 'permanent' | 'retry_exhausted';
 }
 /**
  * Queue options interface
  */
 export interface IQueueOptions {
-    storageType?: 'memory' | 'disk';
-    persistentPath?: string;
+    /** Persistence is always an explicit caller choice. */
+    storageMode: 'memory' | 'managed';
+    /** Required when storageMode is managed. */
+    storageManager?: IBlobStorageManager;
+    storagePrefix?: string;
     checkInterval?: number;
     maxQueueSize?: number;
     maxPerDestination?: number;
@@ -34,9 +82,6 @@ export interface IQueueOptions {
     baseRetryDelay?: number;
     maxRetryDelay?: number;
 }
-/**
- * Queue statistics interface
- */
 export interface IQueueStats {
     queueSize: number;
     status: {
@@ -68,15 +113,24 @@ export declare class UnifiedDeliveryQueue extends EventEmitter {
     private stats;
     private processing;
     private totalProcessed;
+    private ownsManagedPrefix;
+    private lifecycleState;
     /**
      * Create a new unified delivery queue
      * @param options Queue options
      */
     constructor(options: IQueueOptions);
+    private assertMutable;
+    private createInitialRecipientStates;
+    private createBounceOperationId;
     /**
      * Initialize the queue
      */
-    initialize(): Promise<void>;
+    private claimManagedPrefix;
+    private releaseManagedPrefix;
+    initialize(optionsArg?: {
+        startProcessing?: boolean;
+    }): Promise<void>;
     /**
      * Start queue processing
      */
@@ -95,7 +149,7 @@ export declare class UnifiedDeliveryQueue extends EventEmitter {
      * @param mode Processing mode
      * @param route Email route
      */
-    enqueue(processingResult: any, mode: EmailProcessingMode, route?: IEmailRoute): Promise<string>;
+    enqueue(processingResult: Email, mode: EmailProcessingMode, route?: IEmailRoute): Promise<string>;
     /**
      * Get an item from the queue
      * @param id Item ID
@@ -117,26 +171,42 @@ export declare class UnifiedDeliveryQueue extends EventEmitter {
      * @param id Item ID
      * @param error Error message
      */
-    markFailed(id: string, error: string): Promise<boolean>;
+    markFailed(id: string, error: string, optionsArg?: IQueueFailureOptions): Promise<boolean>;
+    /** Rich internal disposition used by the delivery system without breaking markFailed(). */
+    markFailedWithTransition(id: string, error: string, optionsArg?: IQueueFailureOptions): Promise<IQueueFailureTransition>;
+    /** Persist a completed SMTP attempt before any queue status event is emitted. */
+    appendSmtpTransaction(id: string, transaction: ISmtpTransactionAttempt): Promise<boolean>;
+    /** Record recipients accepted after the SMTP final-response 250 checkpoint. */
+    markRecipientsDelivered(id: string, recipients: string[]): Promise<boolean>;
+    /**
+     * Atomically checkpoint permanent recipient failures together with their
+     * durable bounce work. This is the sole 5xx recipient transition.
+     */
+    markRecipientsTerminal(id: string, failures: Array<string | IRecipientPermanentFailure>): Promise<string[]>;
+    getRecipientDisposition(id: string): {
+        unresolved: string[];
+        delivered: string[];
+        permanentFailures: string[];
+    };
+    /** Includes terminal queue items because bounce work outlives delivery status. */
+    listPendingBounceOperations(now?: Date): Array<{
+        itemId: string;
+        operation: IBounceOperation;
+    }>;
+    markBounceOperationCompleted(itemId: string, operationId: string): Promise<boolean>;
+    markBounceOperationFailed(itemId: string, operationId: string, error: string): Promise<boolean>;
     /**
      * Remove an item from the queue
      * @param id Item ID
      */
     removeItem(id: string): Promise<boolean>;
-    /**
-     * Persist an item to disk
-     * @param item Item to persist
-     */
+    private storageKey;
     private persistItem;
-    /**
-     * Remove an item from disk
-     * @param id Item ID
-     */
-    private removeItemFromDisk;
-    /**
-     * Load queue items from disk
-     */
-    private loadFromDisk;
+    private serializeItem;
+    private applyPersistedMutation;
+    private removeItemFromStorage;
+    private deserializeItem;
+    private loadFromStorage;
     /**
      * Update queue statistics
      */