import { InboxAttachment, InboxConfig, InboxEmail, InboxMessage } from './inbox.types';

// Re-export types for downstream consumers that import from this module
export type { InboxAttachment, InboxConfig, InboxEmail, InboxMessage };

/**
 * Abstract inbox provider contract — implemented by ImapProvider and
 * ExchangeInboxProvider. Consumers (DkvService, DkvSchedulerService) depend
 * only on this interface, not on the concrete implementations.
 *
 * Security:
 * - T-07-03: Implementations MUST NOT log credential values
 * - InboxConfig carries decrypted credentials — never persist, never serialize
 */
export interface InboxProvider {
  /**
   * Connects to the configured inbox, searches for emails from the configured
   * sender filter, downloads PDF attachments, and returns all matching emails.
   *
   * @param config  Decrypted inbox connection parameters
   * @returns       Array of emails with their PDF attachments as Buffers
   */
  fetchPdfAttachments(config: InboxConfig): Promise<InboxEmail[]>;

  /**
   * Tests whether the inbox connection can be established.
   *
   * @param config  Decrypted inbox connection parameters
   * @returns       { success: true } on success, { success: false, message } on failure
   */
  testConnection(config: InboxConfig): Promise<{ success: boolean; message?: string }>;

  /**
   * Connects to the configured inbox, searches for unread emails (optionally
   * filtered by sender), and returns each message's subject + HTML/text body.
   *
   * Additive method (D-02, Phase 14 inbox extraction) — the seam the
   * EmailAlertAdapter (Plan 14-03) consumes. Does NOT affect
   * fetchPdfAttachments; DKV is not switched to this method.
   *
   * @param config  Decrypted inbox connection parameters
   * @returns       Array of messages with subject + body (empty array on error)
   */
  fetchMessages(config: InboxConfig): Promise<InboxMessage[]>;
}