/**
 * SendProvider: the contract Mailforge uses to actually deliver email.
 *
 * The Worker (`src/worker/index.ts`) never imports M365 or SMTP libs directly.
 * It asks `adapters.send` for the active provider and calls `send()`.
 *
 * To support a new provider (Resend, Postmark, SES, etc.), implement this
 * interface and register it in `adapters.config.ts`.
 */

import type { UserContext } from '@/core/types';
import type { SendMailInput, SendResult } from '@/adapters/types';

export interface SendProvider {
  /** Logging/debug identifier, e.g. "smtp", "m365", "resend". */
  readonly name: string;

  /**
   * Whether the provider has credentials and is ready to deliver mail.
   * Mailforge UI uses this to decide whether to show "Configure send provider"
   * banners.
   */
  isConfigured(): boolean;

  /**
   * Send a single mail. SendProvider implementations should NOT retry — the
   * Worker handles retries (3 attempts with backoff) based on errorKind.
   *
   * UserContext is optional because some send flows (test-mail from UI) carry
   * it, while Worker-driven sends use a system context.
   */
  send(input: SendMailInput, ctx?: UserContext): Promise<SendResult>;

  /**
   * Health-check the sender mailbox. Used by the Settings UI's "Test
   * connection" button. Returns ok=true if the provider can authenticate AND
   * the sender address is permitted.
   */
  ping(senderEmail: string): Promise<{ ok: boolean; error?: string }>;

  /**
   * Optional: report send-rate quotas to the Worker for throttling.
   * If absent, Worker uses conservative defaults (no provider hint).
   */
  getQuotas?(): { dailyLimit: number; perMinute: number };
}
