mailer/ts/mail/delivery/smtpclient/interfaces.ts

/**
 * SMTP Client Interfaces and Types
 * All interface definitions for the modular SMTP client
 */

import type * as tls from 'node:tls';
import type * as net from 'node:net';
import type { Email } from '../../core/classes.email.ts';

/**
 * SMTP client connection options
 */
export interface ISmtpClientOptions {
  /** Hostname of the SMTP server */
  host: string;
  
  /** Port to connect to */
  port: number;
  
  /** Whether to use TLS for the connection */
  secure?: boolean;
  
  /** Connection timeout in milliseconds */
  connectionTimeout?: number;
  
  /** Socket timeout in milliseconds */
  socketTimeout?: number;
  
  /** Domain name for EHLO command */
  domain?: string;
  
  /** Authentication options */
  auth?: ISmtpAuthOptions;
  
  /** TLS options */
  tls?: tls.ConnectionOptions;
  
  /** Maximum number of connections in pool */
  pool?: boolean;
  maxConnections?: number;
  maxMessages?: number;
  
  /** Enable debug logging */
  debug?: boolean;
  
  /** Proxy settings */
  proxy?: string;
}

/**
 * Authentication options for SMTP
 */
export interface ISmtpAuthOptions {
  /** Username */
  user?: string;
  
  /** Password */
  pass?: string;
  
  /** OAuth2 settings */
  oauth2?: IOAuth2Options;
  
  /** Authentication method preference */
  method?: 'PLAIN' | 'LOGIN' | 'OAUTH2' | 'AUTO';
}

/**
 * OAuth2 authentication options
 */
export interface IOAuth2Options {
  /** OAuth2 user identifier */
  user: string;
  
  /** OAuth2 client ID */
  clientId: string;
  
  /** OAuth2 client secret */
  clientSecret: string;
  
  /** OAuth2 refresh token */
  refreshToken: string;
  
  /** OAuth2 access token */
  accessToken?: string;
  
  /** Token expiry time */
  expires?: number;
}

/**
 * Result of an email send operation
 */
export interface ISmtpSendResult {
  /** Whether the send was successful */
  success: boolean;
  
  /** Message ID from server */
  messageId?: string;
  
  /** List of accepted recipients */
  acceptedRecipients: string[];
  
  /** List of rejected recipients */
  rejectedRecipients: string[];
  
  /** Error information if failed */
  error?: Error;
  
  /** Server response */
  response?: string;
  
  /** Envelope information */
  envelope?: ISmtpEnvelope;
}

/**
 * SMTP envelope information
 */
export interface ISmtpEnvelope {
  /** Sender address */
  from: string;
  
  /** Recipient addresses */
  to: string[];
}

/**
 * Connection pool status
 */
export interface IConnectionPoolStatus {
  /** Total connections in pool */
  total: number;
  
  /** Active connections */
  active: number;
  
  /** Idle connections */
  idle: number;
  
  /** Pending connection requests */
  pending: number;
}

/**
 * SMTP command response
 */
export interface ISmtpResponse {
  /** Response code */
  code: number;
  
  /** Response message */
  message: string;
  
  /** Enhanced status code */
  enhancedCode?: string;
  
  /** Raw response */
  raw: string;
}

/**
 * Connection state
 */
export enum ConnectionState {
  DISCONNECTED = 'disconnected',
  CONNECTING = 'connecting',
  CONNECTED = 'connected',
  AUTHENTICATED = 'authenticated',
  READY = 'ready',
  BUSY = 'busy',
  CLOSING = 'closing',
  ERROR = 'error'
}

/**
 * SMTP capabilities
 */
export interface ISmtpCapabilities {
  /** Supported extensions */
  extensions: Set<string>;
  
  /** Maximum message size */
  maxSize?: number;
  
  /** Supported authentication methods */
  authMethods: Set<string>;
  
  /** Support for pipelining */
  pipelining: boolean;
  
  /** Support for STARTTLS */
  starttls: boolean;
  
  /** Support for 8BITMIME */
  eightBitMime: boolean;
}

/**
 * Internal connection interface
 */
export interface ISmtpConnection {
  /** Socket connection */
  socket: net.Socket | tls.TLSSocket;
  
  /** Connection state */
  state: ConnectionState;
  
  /** Server capabilities */
  capabilities?: ISmtpCapabilities;
  
  /** Connection options */
  options: ISmtpClientOptions;
  
  /** Whether connection is secure */
  secure: boolean;
  
  /** Connection creation time */
  createdAt: Date;
  
  /** Last activity time */
  lastActivity: Date;
  
  /** Number of messages sent */
  messageCount: number;
}

/**
 * Error context for detailed error reporting
 */
export interface ISmtpErrorContext {
  /** Command that caused the error */
  command?: string;
  
  /** Server response */
  response?: ISmtpResponse;
  
  /** Connection state */
  connectionState?: ConnectionState;
  
  /** Additional context data */
  data?: Record<string, any>;
}