interface ReadIMAPEmailsAdvancedOptions {
  // Connection
  email: string;                    // Email address (required)
  password: string;                 // Password / app password (required)
  host?: string;                    // IMAP host (default: "imap.gmail.com")
  port?: number;                    // IMAP port (default: 993)
  folder?: string;                  // Folder to read (default: "INBOX")
  connectTimeoutMs?: number;        // Connect timeout (default: 30000)
  readTimeoutMs?: number;           // Read timeout (default: 60000)

  // Pagination & sorting
  skip?: number;                    // Matching emails to skip (default: 0)
  limit?: number;                   // Max emails to return, 1-200 (default: 10)
  sortOrder?: "asc" | "desc";       // By arrival time; "desc" = newest first (default)

  // Filters (combined with AND)
  since?: number;                   // Only emails with date >= this (Unix ms)
  before?: number;                  // Only emails with date < this (Unix ms)
  from?: string;                    // Sender address contains
  to?: string;                      // A TO recipient contains
  subject?: string;                 // Subject contains
  bodyContains?: string;            // Body contains (server-side search)
  unreadOnly?: boolean;             // Only unread emails (default: false)

  // Content control
  includeBody?: boolean;            // Include bodies (default: true; false is faster)
  preferHtml?: boolean;             // Prefer HTML over plain text (default: true)
  maxBodyLength?: number;           // Truncate body chars, 0 = unlimited (default: 0)
  includeAttachmentNames?: boolean; // Extract attachment names (default: true)

  // Server-side effects & extras
  markAsRead?: boolean;             // Mark returned emails as read (default: false)
  includeFolderList?: boolean;      // Return folder list in metadata (default: false)

  // Proxy
  proxyHost?: string;
  proxyPort?: number;
  proxyUser?: string;
  proxyPassword?: string;
}

type ReadIMAPEmailsAdvancedResult =
  | { success: false; error: string }
  | { success: true; metadata: EmailReadMetadata; emails: AdvancedEmail[] };

interface EmailReadMetadata {
  totalEmails: number;      // Total emails in the folder
  unreadEmails: number;     // Unread emails in the folder (-1 if unknown)
  matchedEmails: number;    // Emails matching the filters
  returnedEmails: number;   // Emails in this page
  skip: number;             // Skip applied
  limit: number;            // Limit applied
  sortOrder: "asc" | "desc";// Sort order applied
  hasMore: boolean;         // More matching emails beyond this page
  filtered: boolean;        // Whether any filters were applied
  folder: string;           // Folder that was read
  host: string;             // IMAP host used
  port: number;             // IMAP port used
  account: string;          // Account that was read
  durationMs: number;       // How long the read took
  folders?: string[];       // Folder list (when includeFolderList: true)
}

interface AdvancedEmail extends Email {
  uid: string | null;       // Stable IMAP UID within the folder
  messageNumber: number;    // IMAP message sequence number
  folder: string;           // Folder the email was read from
  replyTo: string[];        // Reply-To addresses
  receivedDate: number | null; // Received timestamp (Unix ms)
  bodyTruncated: boolean;   // true if body was cut by maxBodyLength
  isAnswered: boolean;      // IMAP Answered flag
  isFlagged: boolean;       // IMAP Flagged (starred) flag
  sizeBytes: number;        // Message size in bytes (-1 if unknown)
}

interface Email {
  id: string;              // Unique email ID
  subject: string;         // Email subject
  from: string;            // Sender email address
  fromName: string;        // Sender display name
  to: string[];            // Recipients
  cc: string[];            // CC recipients
  bcc: string[];           // BCC recipients
  date: number;            // Timestamp (Unix ms)
  body: string;            // Email body content
  isHtml: boolean;         // true if body is HTML
  isRead: boolean;         // Read status
  hasAttachments: boolean; // Has attachments
  attachmentNames: string[]; // Attachment file names
}