dcrouter/ts/mail/routing/interfaces.ts

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

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