/**
 * EmailTransportInterface - Defines the configuration contract for email transport
 *
 * This interface specifies the structure required to configure an SMTP email transport.
 * It's typically used with Nodemailer or similar email-sending libraries to define
 * connection details for email servers.
 *
 * The interface follows standard SMTP configuration patterns and can be used with
 * various email providers (Gmail, SendGrid, AWS SES, custom SMTP servers, etc.)
 *
 * @example
 * // Basic SMTP configuration
 * const gmailConfig: EmailTransportInterface = {
 *   host: 'smtp.gmail.com',
 *   secure: true,
 *   auth: {
 *     user: 'your-email@gmail.com',
 *     pass: 'your-app-password'
 *   }
 * };
 *
 * // Local development configuration
 * const localConfig: EmailTransportInterface = {
 *   host: 'localhost',
 *   secure: false,
 *   auth: {
 *     user: undefined,
 *     pass: undefined
 *   }
 * };
 *
 * @see https://nodemailer.com/smtp/ - Nodemailer SMTP transport configuration
 */
export interface EmailTransportInterface {
  /**
   * SMTP server hostname or IP address
   *
   * Examples:
   * - 'smtp.gmail.com' for Gmail
   * - 'smtp.sendgrid.net' for SendGrid
   * - 'email-smtp.us-east-1.amazonaws.com' for AWS SES
   * - 'localhost' for local development mail servers
   *
   * @remarks Use undefined when configuration is optional or will be provided elsewhere
   */
  host: string | undefined;

  /**
   * Whether to use SSL/TLS for the connection
   *
   * - `true`: Use SSL/TLS immediately upon connection (port 465 typically)
   * - `false`: Start with plain text, upgrade to TLS via STARTTLS (port 587 typically)
   *
   * @default true for production, false for local development
   *
   * @note Some providers require specific settings:
   * - Gmail: secure: true
   * - Office 365: secure: false (uses STARTTLS)
   * - Self-hosted: depends on server configuration
   */
  secure: boolean;

  /**
   * Authentication credentials for the SMTP server
   *
   * Use undefined for servers that don't require authentication
   * (e.g., local development mail servers, open relays)
   */
  auth: {
    /**
     * Username or email address for authentication
     *
     * For most providers, this is the email address:
     * - 'user@example.com'
     * - 'apikey' (for SendGrid API key authentication)
     *
     * @remarks Can be undefined for servers without authentication
     */
    user: string | undefined;

    /**
     * Password or API key for authentication
     *
     * For security, always store passwords in environment variables
     * and never commit them to version control.
     *
     * Examples:
     * - Gmail: app-specific password (not your regular password)
     * - SendGrid: API key
     * - AWS SES: SMTP credentials (different from AWS console password)
     *
     * @remarks Can be undefined for servers without authentication
     */
    pass: string | undefined;
  };
}

/**
 * Common Usage Patterns and Best Practices:
 *
 * 1. **Environment-Based Configuration**:
 *
 *    ```typescript
 *    const emailConfig: EmailTransportInterface = {
 *       host: process.env.SMTP_HOST,
 *       secure: process.env.NODE_ENV === 'production',
 *       auth: {
 *         user: process.env.SMTP_USER,
 *         pass: process.env.SMTP_PASSWORD
 *       }
 *     };
 *    ```
 *
 * 2. **Provider-Specific Extensions** (consider using discriminated union):
 *
 *    ```typescript
 *     export type EmailTransportConfig =
 *       | EmailTransportInterface
 *       | SendGridConfig
 *       | AWS_SES_Config;
 *    ```
 *
 * 3. **Validation and Defaults**:
 *
 *    ```typescript
 *     function validateEmailConfig(config: EmailTransportInterface): boolean {
 *       if (process.env.NODE_ENV === 'production') {
 *         return !!(config.host && config.auth.user && config.auth.pass);
 *       }
 *       return true; // Allow incomplete config for development
 *     }
 *    ```
 *
 * 4. **Security Considerations**:
 *    - Always use environment variables for credentials
 *    - Consider using a secrets management service in production
 *    - Enable Two-Factor Authentication where possible
 *    - Use app-specific passwords (not regular passwords)
 *
 * 5. **Common Provider Configurations**:
 *
 *    - **Gmail**:
 *      host: 'smtp.gmail.com', secure: true, port: 465
 *      Requires app-specific password if 2FA enabled
 *
 *    - **SendGrid**:
 *      host: 'smtp.sendgrid.net', secure: true, port: 465
 *      auth.user: 'apikey', auth.pass: 'your-sendgrid-api-key'
 *
 *    - **AWS SES**:
 *      host: 'email-smtp.{region}.amazonaws.com', secure: true, port: 465
 *      Requires SMTP credentials from AWS IAM
 *
 *    - **Mailtrap (Testing)**:
 *      host: 'smtp.mailtrap.io', secure: false, port: 2525
 *      auth.user/pass from Mailtrap dashboard
 *
 * 6. **Testing Considerations**:
 *    - Use mail testing services (Mailtrap, Ethereal) in development
 *    - Mock email transport in unit tests
 *    - Consider implementing a no-op transport for development
 */
