mailer/ts/mail/delivery/interfaces.ts

/**
 * SMTP and email delivery interface definitions
 */

import type { Email } from '../core/classes.email.ts';

/**
 * SMTP session state enumeration
 */
export enum SmtpState {
  GREETING = 'GREETING',
  AFTER_EHLO = 'AFTER_EHLO',
  MAIL_FROM = 'MAIL_FROM',
  RCPT_TO = 'RCPT_TO',
  DATA = 'DATA',
  DATA_RECEIVING = 'DATA_RECEIVING',
  FINISHED = 'FINISHED'
}

/**
 * Email processing mode type
 */
export type EmailProcessingMode = 'forward' | 'mta' | 'process';

/**
 * Envelope recipient information
 */
export interface IEnvelopeRecipient {
  /**
   * Email address of the recipient
   */
  address: string;
  
  /**
   * Additional SMTP command arguments
   */
  args: Record<string, string>;
}

/**
 * SMTP session envelope information
 */
export interface ISmtpEnvelope {
  /**
   * Envelope sender (MAIL FROM) information
   */
  mailFrom: {
    /**
     * Email address of the sender
     */
    address: string;
    
    /**
     * Additional SMTP command arguments
     */
    args: Record<string, string>;
  };
  
  /**
   * Envelope recipients (RCPT TO) information
   */
  rcptTo: IEnvelopeRecipient[];
}

/**
 * SMTP Session interface - represents an active SMTP connection
 */
export interface ISmtpSession {
  /**
   * Unique session identifier
   */
  id: string;
  
  /**
   * Current session state in the SMTP conversation
   */
  state: SmtpState;
  
  /**
   * Hostname provided by the client in EHLO/HELO command
   */
  clientHostname: string;
  
  /**
   * MAIL FROM email address (legacy format)
   */
  mailFrom: string;
  
  /**
   * RCPT TO email addresses (legacy format)
   */
  rcptTo: string[];
  
  /**
   * Raw email data being received
   */
  emailData: string;
  
  /**
   * Chunks of email data for more efficient buffer management
   */
  emailDataChunks?: string[];
  
  /**
   * Whether the connection is using TLS
   */
  useTLS: boolean;
  
  /**
   * Whether the connection has ended
   */
  connectionEnded: boolean;
  
  /**
   * Remote IP address of the client
   */
  remoteAddress: string;
  
  /**
   * Whether the connection is secure (TLS)
   */
  secure: boolean;
  
  /**
   * Whether the client has been authenticated
   */
  authenticated: boolean;
  
  /**
   * SMTP envelope information (structured format)
   */
  envelope: ISmtpEnvelope;
  
  /**
   * Email processing mode to use for this session
   */
  processingMode?: EmailProcessingMode;
  
  /**
   * Timestamp of last activity for session timeout tracking
   */
  lastActivity?: number;
  
  /**
   * Timeout ID for DATA command timeout
   */
  dataTimeoutId?: NodeJS.Timeout;
}

/**
 * SMTP authentication data
 */
export interface ISmtpAuth {
  /**
   * Authentication method used
   */
  method: 'PLAIN' | 'LOGIN' | 'OAUTH2' | string;
  
  /**
   * Username for authentication
   */
  username: string;
  
  /**
   * Password or token for authentication
   */
  password: string;
}

/**
 * SMTP server options
 */
export interface ISmtpServerOptions {
  /**
   * Port to listen on
   */
  port: number;
  
  /**
   * TLS private key (PEM format)
   */
  key: string;
  
  /**
   * TLS certificate (PEM format)
   */
  cert: string;
  
  /**
   * Server hostname for SMTP banner
   */
  hostname?: string;
  
  /**
   * Host address to bind to (defaults to all interfaces)
   */
  host?: string;
  
  /**
   * Secure port for dedicated TLS connections
   */
  securePort?: number;
  
  /**
   * CA certificates for TLS (PEM format)
   */
  ca?: string;
  
  /**
   * Maximum size of messages in bytes
   */
  maxSize?: number;
  
  /**
   * Maximum number of concurrent connections
   */
  maxConnections?: number;
  
  /**
   * Authentication options
   */
  auth?: {
    /**
     * Whether authentication is required
     */
    required: boolean;
    
    /**
     * Allowed authentication methods
     */
    methods: ('PLAIN' | 'LOGIN' | 'OAUTH2')[];
  };
  
  /**
   * Socket timeout in milliseconds (default: 5 minutes / 300000ms)
   */
  socketTimeout?: number;
  
  /**
   * Initial connection timeout in milliseconds (default: 30 seconds / 30000ms)
   */
  connectionTimeout?: number;
  
  /**
   * Interval for checking idle sessions in milliseconds (default: 5 seconds / 5000ms)
   * For testing, can be set lower (e.g. 1000ms) to detect timeouts more quickly
   */
  cleanupInterval?: number;
  
  /**
   * Maximum number of recipients allowed per message (default: 100)
   */
  maxRecipients?: number;
  
  /**
   * Maximum message size in bytes (default: 10MB / 10485760 bytes)
   * This is advertised in the EHLO SIZE extension
   */
  size?: number;
  
  /**
   * Timeout for the DATA command in milliseconds (default: 60000ms / 1 minute)
   * This controls how long to wait for the complete email data
   */
  dataTimeout?: number;
}

/**
 * Result of SMTP transaction
 */
export interface ISmtpTransactionResult {
  /**
   * Whether the transaction was successful
   */
  success: boolean;
  
  /**
   * Error message if failed
   */
  error?: string;
  
  /**
   * Message ID if successful
   */
  messageId?: string;
  
  /**
   * Resulting email if successful
   */
  email?: Email;
}