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

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

/**
 * 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;
  
  /**
   * 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;
}

/**
 * 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;
  
  /**
   * Maximum size of messages in bytes
   */
  maxSize?: number;
  
  /**
   * Authentication options
   */
  auth?: {
    /**
     * Whether authentication is required
     */
    required: boolean;
    
    /**
     * Allowed authentication methods
     */
    methods: ('PLAIN' | 'LOGIN' | 'OAUTH2')[];
  };
}

/**
 * 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;
}