/**
 * SMTP client types.
 *
 * Provides a typed interface for sending emails via SMTP.
 */

import type { BaseIntegrationClient } from "../../types.js";
import type { TraceMetadata } from "../registry.js";

/**
 * Options for sending an email via SMTP.
 */
export interface SmtpSendOptions {
  /** Sender email address */
  from: string;

  /** Recipient email address(es), comma-separated for multiple */
  to: string;

  /** Email subject line */
  subject: string;

  /** Email body content (HTML or plain text) */
  body: string;

  /** CC recipients, comma-separated for multiple */
  cc?: string;

  /** BCC recipients, comma-separated for multiple */
  bcc?: string;

  /** Reply-to email address */
  replyTo?: string;

  /**
   * Email attachments as a JSON array of objects with fields:
   * `content` (base64-encoded), `name` (filename), `type` (MIME type).
   */
  attachments?: string;
}

/**
 * SMTP client for sending emails.
 *
 * @example
 * ```typescript
 * const mailer = ctx.integrations.mailer;
 *
 * await mailer.send({
 *   from: 'noreply@example.com',
 *   to: 'user@example.com',
 *   subject: 'Hello',
 *   body: '<h1>Welcome!</h1>',
 * });
 * ```
 */
export interface SmtpClient extends BaseIntegrationClient {
  /**
   * Send an email via SMTP.
   *
   * @param options - Email send options
   * @returns The raw result from the SMTP plugin
   */
  send(options: SmtpSendOptions, metadata?: TraceMetadata): Promise<unknown>;
}