Type Reference

import type {
  MailConfig,
  MailerConfig,
  SmtpConfig,
  SendGridConfig,
  SesConfig,
  MailgunConfig,
  ResendConfig,
  PostmarkConfig,
  MailtrapConfig,
  MailAddress,
  Attachment,
  MailOptions,
  MailProvider,
  MailResponse,
  FailoverConfig,
  FailoverEvent,
  FailoverDetail,
  QueueConfig,
  RedisConnectionConfig,
  BackoffConfig,
  QueuedMailJob,
  QueueJobResult,
  QueueDriver,
  TemplateConfig,
  TemplateEngine,
  TemplateEngineOptions,
  MarkdownConfig,
  MarkdownTheme,
  MarkdownRendererOptions,
  SentMessage,
} from '@impruthvi/nodemail';

interface MailAddress {
  address: string;     // Email address
  name?: string;       // Display name
}

interface Attachment {
  filename: string;         // Display filename
  content?: Buffer | string; // File content (buffer or string)
  path?: string;            // File path (alternative to content)
  contentType?: string;     // MIME type
  cid?: string;             // Content ID for inline attachments
}

interface MailOptions {
  to: string | string[] | MailAddress | MailAddress[];
  from?: string | MailAddress;
  subject: string;
  html?: string;
  text?: string;
  cc?: string | string[] | MailAddress | MailAddress[];
  bcc?: string | string[] | MailAddress | MailAddress[];
  replyTo?: string | MailAddress;
  attachments?: Attachment[];
  headers?: Record<string, string>;
  template?: string;
  data?: Record<string, unknown>;
}

interface MailProvider {
  send(options: MailOptions): Promise<MailResponse>;
}

interface MailResponse {
  success: boolean;
  messageId?: string;
  accepted?: string[];
  rejected?: string[];
  response?: string;
  error?: string;
  provider?: string;
  failoverUsed?: boolean;
  failoverAttempts?: FailoverDetail[];
}

interface MailConfig {
  default: string;
  from: { address: string; name: string };
  mailers: Record<string, MailerConfig>;
  templates?: TemplateConfig;
  queue?: QueueConfig;
  markdown?: MarkdownConfig;
  failover?: FailoverConfig;
}

interface MailerConfig {
  driver: 'smtp' | 'sendgrid' | 'ses' | 'mailgun' | 'resend' | 'postmark' | 'mailtrap';
  failover?: FailoverConfig;
  [key: string]: unknown;
}

interface SmtpConfig extends MailerConfig {
  driver: 'smtp';
  host: string;
  port: number;
  username?: string;
  password?: string;
  encryption?: 'tls' | 'ssl';
  secure?: boolean;
  auth?: { user: string; pass: string };
  options?: Record<string, unknown>;
}

interface SendGridConfig extends MailerConfig {
  driver: 'sendgrid';
  apiKey: string;
}

interface SesConfig extends MailerConfig {
  driver: 'ses';
  region: string;
  accessKeyId?: string;
  secretAccessKey?: string;
}

interface MailgunConfig extends MailerConfig {
  driver: 'mailgun';
  domain: string;
  apiKey: string;
  region?: 'us' | 'eu';
}

interface ResendConfig extends MailerConfig {
  driver: 'resend';
  apiKey: string;
}

interface PostmarkConfig extends MailerConfig {
  driver: 'postmark';
  serverToken: string;
}

interface MailtrapConfig extends MailerConfig {
  driver: 'mailtrap';
  token: string;
  inboxId: string;
}

interface TemplateConfig {
  engine?: 'handlebars' | 'ejs' | 'pug' | TemplateEngine;
  viewsPath?: string;
  extension?: string;
  cache?: boolean;
  options?: Record<string, unknown>;
}

interface TemplateEngine {
  render(template: string, data?: Record<string, unknown>): Promise<string>;
  renderFile(filePath: string, data?: Record<string, unknown>): Promise<string>;
  compile(template: string): (data?: Record<string, unknown>) => string;
}

interface TemplateEngineOptions {
  viewsPath?: string;
  extension?: string;
  cache?: boolean;
  options?: Record<string, unknown>;
}

interface FailoverConfig {
  chain: string[];
  maxRetriesPerProvider?: number;  // default: 1
  retryDelay?: number;             // default: 0
  failoverDelay?: number;          // default: 0
  onFailover?: (event: FailoverEvent) => void;
}

interface FailoverEvent {
  failedMailer: string;
  error: string;
  nextMailer: string;
  attemptIndex: number;
  timestamp: string;  // ISO 8601
}

interface FailoverDetail {
  mailer: string;
  success: boolean;
  error?: string;
  durationMs: number;
}

interface QueueConfig {
  driver: 'bull' | 'bullmq' | 'sync';
  connection?: RedisConnectionConfig;
  defaultQueue?: string;
  prefix?: string;
  retries?: number;
  backoff?: BackoffConfig;
}

interface RedisConnectionConfig {
  host?: string;
  port?: number;
  password?: string;
  db?: number;
  url?: string;
}

interface BackoffConfig {
  type: 'fixed' | 'exponential';
  delay: number;
}

interface QueuedMailJob {
  id: string;
  mailOptions: MailOptions;
  mailableClass?: string;
  mailableData?: Record<string, unknown>;
  attempts: number;
  maxAttempts: number;
  delay?: number;
  scheduledAt?: Date;
  createdAt: Date;
}

interface QueueJobResult {
  success: boolean;
  jobId: string;
  queue: string;
  scheduledAt?: Date;
  error?: string;
}

interface QueueDriver {
  add(job: QueuedMailJob, queueName?: string): Promise<QueueJobResult>;
  addDelayed(job: QueuedMailJob, delay: number, queueName?: string): Promise<QueueJobResult>;
  addScheduled(job: QueuedMailJob, date: Date, queueName?: string): Promise<QueueJobResult>;
  process(queueName: string, handler: (job: QueuedMailJob) => Promise<MailResponse>): void;
  close(): Promise<void>;
}

interface MarkdownConfig {
  theme?: {
    css?: string;
    headerHtml?: string;
    footerHtml?: string;
  };
  customCss?: string;
}

interface MarkdownTheme {
  css: string;
  headerHtml?: string;
  footerHtml?: string;
}

interface MarkdownRendererOptions {
  theme?: MarkdownTheme;
  customCss?: string;
  juiceOptions?: Record<string, unknown>;
}

interface SentMessage {
  options: MailOptions;
  mailable: Mailable | undefined;
  timestamp: Date;
}