@nixxie-cms/email 1.0.1

package/src/types.ts

@@ -0,0 +1,279 @@
+import type {
+  NixxieEmailAttachment,
+  NixxieEmailQueueOptions,
+  NixxieEmailRecipient,
+  NixxieEmailSendOptions,
+  NixxieEmailSentInfo,
+  NixxieEmailQueueStats,
+} from '@nixxie-cms/core/types'
+
+// ── Re-export the shared types so consumers only need @nixxie-cms/email ──
+export type {
+  NixxieEmailAttachment as EmailAttachment,
+  NixxieEmailQueueOptions as QueueEmailOptions,
+  NixxieEmailRecipient as EmailRecipient,
+  NixxieEmailSendOptions as SendEmailOptions,
+  NixxieEmailSentInfo as SentEmailInfo,
+  NixxieEmailQueueStats as EmailQueueStats,
+}
+
+// ─────────────────────────────────────────────────────────────
+// Transport configs
+// ─────────────────────────────────────────────────────────────
+
+export type SmtpTransportConfig = {
+  type: 'smtp'
+  host: string
+  port?: number
+  secure?: boolean
+  auth?: {
+    user: string
+    pass: string
+  }
+  tls?: {
+    rejectUnauthorized?: boolean
+    ciphers?: string
+  }
+  connectionTimeout?: number
+  greetingTimeout?: number
+  socketTimeout?: number
+  pool?: boolean
+  maxConnections?: number
+  maxMessages?: number
+}
+
+export type SendGridTransportConfig = {
+  type: 'sendgrid'
+  apiKey: string
+}
+
+export type MailgunTransportConfig = {
+  type: 'mailgun'
+  apiKey: string
+  domain: string
+  /** 'us' (default) or 'eu' */
+  region?: 'us' | 'eu'
+}
+
+export type SesTransportConfig = {
+  type: 'ses'
+  region: string
+  credentials?: {
+    accessKeyId: string
+    secretAccessKey: string
+    sessionToken?: string
+  }
+}
+
+export type ResendTransportConfig = {
+  type: 'resend'
+  apiKey: string
+}
+
+/** Development transport — logs emails to the console instead of sending */
+export type ConsoleTransportConfig = {
+  type: 'console'
+}
+
+export type EmailTransportConfig =
+  | SmtpTransportConfig
+  | SendGridTransportConfig
+  | MailgunTransportConfig
+  | SesTransportConfig
+  | ResendTransportConfig
+  | ConsoleTransportConfig
+
+// ─────────────────────────────────────────────────────────────
+// Template config
+// ─────────────────────────────────────────────────────────────
+
+export type EmailTemplateEngine = 'handlebars' | 'pug' | 'auto'
+
+export type EmailTemplatesConfig = {
+  /** Absolute path to the templates directory */
+  dir: string
+  /**
+   * Default template engine. Use `'auto'` to detect the engine per-template from the file
+   * extension (.hbs/.handlebars vs .pug/.jade).
+   * @default 'handlebars'
+   */
+  engine?: EmailTemplateEngine
+  /**
+   * Enable layout support.
+   * Place a `layouts/base.hbs` (or `.pug`) file and use `{{{body}}}` inside it.
+   * @default true
+   */
+  layouts?: boolean
+  /**
+   * Auto-load Handlebars partials from `partials/` subdirectory.
+   * @default true
+   */
+  partials?: boolean
+  /**
+   * Options passed directly to the underlying template engine.
+   * For Handlebars: `{ noEscape?: boolean, helpers?: Record<string, Function> }`
+   * For Pug: `{ pretty?: boolean, filters?: object }`
+   */
+  engineOptions?: Record<string, unknown>
+  /**
+   * Reload templates from disk on every render (useful in development).
+   * @default false
+   */
+  cache?: boolean
+}
+
+// ─────────────────────────────────────────────────────────────
+// Queue config
+// ─────────────────────────────────────────────────────────────
+
+export type EmailQueueConfig = {
+  /** Enabled unless explicitly set to false. @default true */
+  enabled?: boolean
+  /** Number of emails processed in parallel @default 5 */
+  concurrency?: number
+  /** How many times to retry a failed send @default 3 */
+  retries?: number
+  /**
+   * Base delay in ms between retries — doubled on each subsequent attempt.
+   * @default 5000
+   */
+  retryDelay?: number
+  /** Discard jobs older than this (ms). 0 = never discard. @default 86400000 (24h) */
+  maxAge?: number
+}
+
+// ─────────────────────────────────────────────────────────────
+// Tracking config
+// ─────────────────────────────────────────────────────────────
+
+export type EmailTrackingConfig = {
+  /** Track email opens via a 1×1 pixel. @default false */
+  opens?: boolean
+  /** Rewrite links to track clicks. @default false */
+  clicks?: boolean
+  /**
+   * Base URL prepended to all tracking endpoints.
+   * Required when opens or clicks tracking is enabled.
+   */
+  baseUrl: string
+  /** Path prefix for tracking routes. @default '/email-tracking' */
+  path?: string
+}
+
+// ─────────────────────────────────────────────────────────────
+// Development config
+// ─────────────────────────────────────────────────────────────
+
+export type EmailDevelopmentConfig = {
+  /**
+   * When true, emails are not sent — they are logged and optionally previewed.
+   * @default process.env.NODE_ENV !== 'production'
+   */
+  enabled?: boolean
+  /**
+   * Write rendered HTML to this directory as .html files for browser preview.
+   * Filenames are `{template}-{timestamp}.html`.
+   */
+  previewPath?: string
+  /**
+   * Override the "to" address for all emails in development mode.
+   * Useful for catching all outgoing mail in one inbox.
+   */
+  toOverride?: string | string[]
+}
+
+// ─────────────────────────────────────────────────────────────
+// Callbacks
+// ─────────────────────────────────────────────────────────────
+
+export type EmailSentCallback = (info: NixxieEmailSentInfo, options: NixxieEmailSendOptions) => void | Promise<void>
+export type EmailFailedCallback = (error: Error, options: NixxieEmailSendOptions) => void | Promise<void>
+
+// ─────────────────────────────────────────────────────────────
+// Top-level EmailConfig (accepted by createEmail())
+// ─────────────────────────────────────────────────────────────
+
+export type EmailConfig = {
+  /** Transport configuration — defines how emails are physically sent */
+  transport: EmailTransportConfig
+
+  /**
+   * Default "from" address used when `SendEmailOptions.from` is not set.
+   * Can be a plain address string or an object with name + address.
+   */
+  from: NixxieEmailRecipient
+
+  /** Default reply-to address */
+  replyTo?: NixxieEmailRecipient
+
+  /** Template engine configuration */
+  templates?: EmailTemplatesConfig
+
+  /** Outbound queue configuration */
+  queue?: EmailQueueConfig
+
+  /** Email open/click tracking */
+  tracking?: EmailTrackingConfig
+
+  /** Development-mode settings (preview, override recipients, etc.) */
+  development?: EmailDevelopmentConfig
+
+  /** Addresses that should never receive emails */
+  suppressionList?: string[]
+
+  /** Default headers appended to every message */
+  headers?: Record<string, string>
+
+  /** Called after every successfully sent email */
+  onSent?: EmailSentCallback
+
+  /** Called when an email fails to send */
+  onFailed?: EmailFailedCallback
+}
+
+// ─────────────────────────────────────────────────────────────
+// Internal transport abstraction
+// ─────────────────────────────────────────────────────────────
+
+export type TransportMessage = {
+  from: string
+  to: string[]
+  cc?: string[]
+  bcc?: string[]
+  replyTo?: string[]
+  subject: string
+  html?: string
+  text?: string
+  attachments?: NixxieEmailAttachment[]
+  headers?: Record<string, string>
+}
+
+export type TransportResult = {
+  messageId: string
+  accepted: string[]
+  rejected: string[]
+  response?: string
+}
+
+export interface EmailTransporter {
+  send(message: TransportMessage): Promise<TransportResult>
+  verify(): Promise<boolean>
+  close(): Promise<void>
+}
+
+// ─────────────────────────────────────────────────────────────
+// Queue internals
+// ─────────────────────────────────────────────────────────────
+
+export type QueueJobStatus = 'pending' | 'processing' | 'completed' | 'failed'
+
+export type QueueJob = {
+  id: string
+  options: NixxieEmailQueueOptions
+  status: QueueJobStatus
+  attempts: number
+  createdAt: Date
+  sendAt?: Date
+  priority: 'high' | 'normal' | 'low'
+  lastError?: string
+}