mailer/ts/mail/routing/interfaces.ts

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

/**
 * Route configuration for email routing
 */
export interface IEmailRoute {
  /** Route identifier */
  name: string;
  /** Order of evaluation (higher priority evaluated first, default: 0) */
  priority?: number;
  /** Conditions to match */
  match: IEmailMatch;
  /** Action to take when matched */
  action: IEmailAction;
}

/**
 * Match criteria for email routing
 */
export interface IEmailMatch {
  /** Email patterns to match recipients: "*@example.com", "admin@*" */
  recipients?: string | string[];
  /** Email patterns to match senders */
  senders?: string | string[];
  /** IP addresses or CIDR ranges to match */
  clientIp?: string | string[];
  /** Require authentication status */
  authenticated?: boolean;
  
  // Optional advanced matching
  /** Headers to match */
  headers?: Record<string, string | RegExp>;
  /** Message size range */
  sizeRange?: { min?: number; max?: number };
  /** Subject line patterns */
  subject?: string | RegExp;
  /** Has attachments */
  hasAttachments?: boolean;
}

/**
 * Action to take when route matches
 */
export interface IEmailAction {
  /** Type of action to perform */
  type: 'forward' | 'deliver' | 'reject' | 'process';
  
  /** Forward action configuration */
  forward?: {
    /** Target host to forward to */
    host: string;
    /** Target port (default: 25) */
    port?: number;
    /** Authentication credentials */
    auth?: {
      user: string;
      pass: string;
    };
    /** Preserve original headers */
    preserveHeaders?: boolean;
    /** Additional headers to add */
    addHeaders?: Record<string, string>;
  };
  
  /** Reject action configuration */
  reject?: {
    /** SMTP response code */
    code: number;
    /** SMTP response message */
    message: string;
  };
  
  /** Process action configuration */
  process?: {
    /** Enable content scanning */
    scan?: boolean;
    /** Enable DKIM signing */
    dkim?: boolean;
    /** Delivery queue priority */
    queue?: 'normal' | 'priority' | 'bulk';
  };
  
  /** Options for various action types */
  options?: {
    /** MTA specific options */
    mtaOptions?: {
      domain?: string;
      allowLocalDelivery?: boolean;
      localDeliveryPath?: string;
      dkimSign?: boolean;
      dkimOptions?: {
        domainName: string;
        keySelector: string;
        privateKey?: string;
      };
      smtpBanner?: string;
      maxConnections?: number;
      connTimeout?: number;
      spoolDir?: string;
    };
    /** Content scanning configuration */
    contentScanning?: boolean;
    scanners?: Array<{
      type: 'spam' | 'virus' | 'attachment';
      threshold?: number;
      action: 'tag' | 'reject';
      blockedExtensions?: string[];
    }>;
    /** Email transformations */
    transformations?: Array<{
      type: string;
      header?: string;
      value?: string;
      domains?: string[];
      append?: boolean;
      [key: string]: any;
    }>;
  };
  
  /** Delivery options (applies to forward/process/deliver) */
  delivery?: {
    /** Rate limit (messages per minute) */
    rateLimit?: number;
    /** Number of retry attempts */
    retries?: number;
  };
}

/**
 * Context for route evaluation
 */
export interface IEmailContext {
  /** The email being routed */
  email: Email;
  /** The SMTP session */
  session: IExtendedSmtpSession;
}

/**
 * Email domain configuration
 */
export interface IEmailDomainConfig {
  /** Domain name */
  domain: string;
  
  /** DNS handling mode */
  dnsMode: 'forward' | 'internal-dns' | 'external-dns';
  
  /** DNS configuration based on mode */
  dns?: {
    /** For 'forward' mode */
    forward?: {
      /** Skip DNS validation (default: false) */
      skipDnsValidation?: boolean;
      /** Target server's expected domain */
      targetDomain?: string;
    };
    
    /** For 'internal-dns' mode */
    internal?: {
      /** TTL for DNS records in seconds (default: 3600) */
      ttl?: number;
      /** MX record priority (default: 10) */
      mxPriority?: number;
    };
    
    /** For 'external-dns' mode */
    external?: {
      /** Custom DNS servers (default: system DNS) */
      servers?: string[];
      /** Which records to validate (default: ['MX', 'SPF', 'DKIM', 'DMARC']) */
      requiredRecords?: ('MX' | 'SPF' | 'DKIM' | 'DMARC')[];
    };
  };
  
  /** Per-domain DKIM settings (DKIM always enabled) */
  dkim?: {
    /** DKIM selector (default: 'default') */
    selector?: string;
    /** Key size in bits (default: 2048) */
    keySize?: number;
    /** Automatically rotate keys (default: false) */
    rotateKeys?: boolean;
    /** Days between key rotations (default: 90) */
    rotationInterval?: number;
  };
  
  /** Per-domain rate limits */
  rateLimits?: {
    outbound?: {
      messagesPerMinute?: number;
      messagesPerHour?: number;
      messagesPerDay?: number;
    };
    inbound?: {
      messagesPerMinute?: number;
      connectionsPerIp?: number;
      recipientsPerMessage?: number;
    };
  };
}