@nixxie-cms/email 1.0.1

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@nixxie-cms/email",
+  "version": "1.0.1",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-email.cjs.js",
+  "module": "dist/nixxie-cms-email.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-email.cjs.js",
+      "module": "./dist/nixxie-cms-email.esm.js",
+      "default": "./dist/nixxie-cms-email.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7",
+    "nodemailer": "^6.9.14"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^6.4.15",
+    "handlebars": "^4.7.8",
+    "pug": "^3.0.3",
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "optionalDependencies": {
+    "handlebars": "^4.7.8",
+    "pug": "^3.0.3"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/email"
+  }
+}

package/src/EmailService.ts

@@ -0,0 +1,263 @@
+import type {
+  NixxieEmailQueueOptions,
+  NixxieEmailRecipient,
+  NixxieEmailSendOptions,
+  NixxieEmailSentInfo,
+  NixxieEmailService,
+} from '@nixxie-cms/core'
+import type {
+  EmailConfig,
+  EmailQueueStats,
+  EmailTransporter,
+  QueueJob,
+  TransportMessage,
+} from './types'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { EmailQueue } from './queue/EmailQueue'
+import { TemplateManager } from './templates/TemplateManager'
+import { createTransport } from './transports'
+
+function normalizeRecipients(
+  recipients: NixxieEmailRecipient | NixxieEmailRecipient[]
+): string[] {
+  const arr = Array.isArray(recipients) ? recipients : [recipients]
+  return arr.map(r => (typeof r === 'string' ? r : r.name ? `"${r.name}" <${r.address}>` : r.address))
+}
+
+function extractAddress(recipient: NixxieEmailRecipient): string {
+  if (typeof recipient === 'string') {
+    const match = recipient.match(/<(.+)>/)
+    return match ? match[1] : recipient
+  }
+  return recipient.address
+}
+
+export class EmailService implements NixxieEmailService {
+  private transport: EmailTransporter
+  private templateManager: TemplateManager | undefined
+  private emailQueue: EmailQueue | undefined
+  private suppressionList = new Set<string>()
+  private config: EmailConfig
+
+  constructor(config: EmailConfig) {
+    this.config = config
+
+    // In development mode, log emails to the console instead of delivering them for real.
+    this.transport = this.isDevMode()
+      ? createTransport({ type: 'console' })
+      : createTransport(config.transport)
+
+    if (config.templates) {
+      this.templateManager = new TemplateManager(config.templates)
+    }
+
+    if (config.queue?.enabled !== false) {
+      this.emailQueue = new EmailQueue(config.queue ?? {}, async (job: QueueJob) => {
+        await this.sendImmediate(job.options)
+      })
+      this.emailQueue.start()
+    }
+
+    if (config.suppressionList?.length) {
+      for (const addr of config.suppressionList) {
+        this.suppressionList.add(addr.toLowerCase())
+      }
+    }
+  }
+
+  async send(options: NixxieEmailSendOptions): Promise<NixxieEmailSentInfo> {
+    return this.sendImmediate(options)
+  }
+
+  async bulk(
+    recipients: NixxieEmailRecipient[],
+    options: Omit<NixxieEmailSendOptions, 'to'>
+  ): Promise<NixxieEmailSentInfo[]> {
+    const results: NixxieEmailSentInfo[] = []
+
+    for (const recipient of recipients) {
+      try {
+        const info = await this.sendImmediate({ ...options, to: recipient })
+        results.push(info)
+      } catch (err) {
+        try {
+          await this.config.onFailed?.(
+            err instanceof Error ? err : new Error(String(err)),
+            { ...options, to: recipient }
+          )
+        } catch {
+          // a failing onFailed callback must not abort the rest of the bulk send
+        }
+      }
+    }
+
+    return results
+  }
+
+  /**
+   * Whether development mode is active. When a `development` config block is present, this defaults
+   * to `process.env.NODE_ENV !== 'production'` unless `development.enabled` is set explicitly.
+   * In dev mode emails are logged (and optionally written to `previewPath`) instead of being sent.
+   */
+  private isDevMode(): boolean {
+    const dev = this.config.development
+    if (!dev) return false
+    return dev.enabled ?? process.env.NODE_ENV !== 'production'
+  }
+
+  private async writePreview(
+    dir: string,
+    template: string | undefined,
+    html: string
+  ): Promise<void> {
+    try {
+      await mkdir(dir, { recursive: true })
+      const safeName = (template ?? 'email').replace(/[^a-zA-Z0-9._-]/g, '_')
+      await writeFile(join(dir, `${safeName}-${Date.now()}.html`), html, 'utf-8')
+    } catch {
+      // Preview writing is best-effort and must never break sending.
+    }
+  }
+
+  queue(options: NixxieEmailQueueOptions): string {
+    if (!this.emailQueue) {
+      throw new Error('Email queue is not enabled. Set queue.enabled = true in email config.')
+    }
+    const job = this.emailQueue.enqueue({ options, sendAt: options.sendAt, priority: options.priority ?? 'normal' })
+    return job.id
+  }
+
+  addToSuppressionList(address: string): void {
+    this.suppressionList.add(address.toLowerCase())
+  }
+
+  removeFromSuppressionList(address: string): void {
+    this.suppressionList.delete(address.toLowerCase())
+  }
+
+  isSuppressed(address: string): boolean {
+    return this.suppressionList.has(address.toLowerCase())
+  }
+
+  getSuppressionList(): string[] {
+    return Array.from(this.suppressionList)
+  }
+
+  getQueueStats(): EmailQueueStats {
+    if (!this.emailQueue) {
+      return { pending: 0, processing: 0, failed: 0, completed: 0 }
+    }
+    return this.emailQueue.getStats()
+  }
+
+  async flushQueue(): Promise<void> {
+    if (this.emailQueue) {
+      await this.emailQueue.flush()
+    }
+  }
+
+  async close(): Promise<void> {
+    this.emailQueue?.stop()
+    await this.transport.close()
+  }
+
+  private async sendImmediate(options: NixxieEmailSendOptions): Promise<NixxieEmailSentInfo> {
+    const toAddresses = normalizeRecipients(
+      Array.isArray(options.to) ? options.to : [options.to]
+    )
+
+    // Apply dev override
+    let effectiveTo = toAddresses
+    if (this.config.development?.enabled && this.config.development.toOverride) {
+      effectiveTo = normalizeRecipients(
+        Array.isArray(this.config.development.toOverride)
+          ? this.config.development.toOverride
+          : [this.config.development.toOverride]
+      )
+    }
+
+    // Suppression check
+    if (!options.skipSuppressionCheck) {
+      const suppressed = effectiveTo.filter(addr => {
+        const raw = extractAddress(addr)
+        return this.suppressionList.has(raw.toLowerCase())
+      })
+      if (suppressed.length) {
+        throw new Error(`Email suppressed for: ${suppressed.join(', ')}`)
+      }
+    }
+
+    let { html, text, subject } = options
+
+    // Render template
+    if (options.template && this.templateManager) {
+      const rendered = await this.templateManager.render(options.template, options.data ?? {})
+      html = html ?? rendered.html
+      text = text ?? rendered.text
+      subject = subject ?? rendered.subject
+    }
+
+    if (!subject) {
+      throw new Error('Email subject is required')
+    }
+
+    const from = options.from ?? this.config.from
+    if (!from) {
+      throw new Error('Email "from" address is required. Set it in config.email.from or pass it in the send options.')
+    }
+
+    const ccAddresses = options.cc
+      ? normalizeRecipients(Array.isArray(options.cc) ? options.cc : [options.cc])
+      : undefined
+    const bccAddresses = options.bcc
+      ? normalizeRecipients(Array.isArray(options.bcc) ? options.bcc : [options.bcc])
+      : undefined
+    const replyToAddresses = options.replyTo
+      ? normalizeRecipients(Array.isArray(options.replyTo) ? options.replyTo : [options.replyTo])
+      : this.config.replyTo
+        ? normalizeRecipients(this.config.replyTo)
+        : undefined
+
+    const message: TransportMessage = {
+      from:
+        typeof from === 'string'
+          ? from
+          : from.name
+            ? `"${from.name}" <${from.address}>`
+            : from.address,
+      to: effectiveTo,
+      cc: ccAddresses,
+      bcc: bccAddresses,
+      replyTo: replyToAddresses,
+      subject,
+      html,
+      text,
+      attachments: options.attachments,
+      headers: { ...this.config.headers, ...options.headers },
+    }
+
+    // In dev mode, optionally write the rendered HTML to disk for browser preview.
+    if (this.isDevMode() && this.config.development?.previewPath && html) {
+      await this.writePreview(this.config.development.previewPath, options.template, html)
+    }
+
+    const result = await this.transport.send(message)
+
+    const info: NixxieEmailSentInfo = {
+      messageId: result.messageId,
+      accepted: result.accepted,
+      rejected: result.rejected,
+      response: result.response,
+      timestamp: new Date(),
+    }
+
+    try {
+      await this.config.onSent?.(info, options)
+    } catch {
+      // a failing onSent callback must not fail an already-sent email
+    }
+
+    return info
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+import type { EmailConfig } from './types'
+import { EmailService } from './EmailService'
+
+export function createEmail(config: EmailConfig): EmailService {
+  return new EmailService(config)
+}
+
+export { EmailService }
+
+export type {
+  EmailAttachment,
+  EmailConfig,
+  EmailQueueConfig,
+  EmailTemplatesConfig,
+  EmailTrackingConfig,
+  EmailTransportConfig,
+  MailgunTransportConfig,
+  ResendTransportConfig,
+  SendEmailOptions,
+  SesTransportConfig,
+  SmtpTransportConfig,
+  ConsoleTransportConfig,
+  SendGridTransportConfig,
+  QueueJob,
+} from './types'
+
+export type {
+  NixxieEmailRecipient,
+  NixxieEmailAttachment,
+  NixxieEmailSendOptions,
+  NixxieEmailQueueOptions,
+  NixxieEmailSentInfo,
+  NixxieEmailQueueStats,
+  NixxieEmailService,
+} from '@nixxie-cms/core'

package/src/queue/EmailQueue.ts

@@ -0,0 +1,134 @@
+import type { EmailQueueConfig, QueueJob } from '../types'
+
+type JobHandler = (job: QueueJob) => Promise<void>
+
+// Higher number = processed first
+const PRIORITY_RANK: Record<QueueJob['priority'], number> = {
+  high: 2,
+  normal: 1,
+  low: 0,
+}
+
+export class EmailQueue {
+  private jobs: QueueJob[] = []
+  private processing = new Set<string>()
+  private config: Required<EmailQueueConfig>
+  private handler: JobHandler
+  private timer: NodeJS.Timeout | null = null
+  private running = false
+  private completedCount = 0
+
+  constructor(config: EmailQueueConfig, handler: JobHandler) {
+    this.config = {
+      enabled: config.enabled ?? true,
+      concurrency: config.concurrency ?? 5,
+      retries: config.retries ?? 3,
+      retryDelay: config.retryDelay ?? 5000,
+      maxAge: config.maxAge ?? 86400000,
+    }
+    this.handler = handler
+  }
+
+  enqueue(job: Omit<QueueJob, 'id' | 'status' | 'attempts' | 'createdAt'>): QueueJob {
+    const queued: QueueJob = {
+      ...job,
+      id: `job-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+      status: 'pending',
+      attempts: 0,
+      createdAt: new Date(),
+    }
+    this.jobs.push(queued)
+    this.scheduleFlush()
+    return queued
+  }
+
+  start() {
+    this.running = true
+    this.scheduleFlush()
+  }
+
+  stop() {
+    this.running = false
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+
+  getStats() {
+    const now = Date.now()
+    return {
+      pending: this.jobs.filter(j => j.status === 'pending' && (!j.sendAt || j.sendAt.getTime() <= now)).length,
+      processing: this.processing.size,
+      failed: this.jobs.filter(j => j.status === 'failed').length,
+      completed: this.completedCount,
+    }
+  }
+
+  async flush(): Promise<void> {
+    const now = Date.now()
+
+    // Expire old jobs. maxAge <= 0 means "never discard".
+    this.jobs = this.jobs.filter(j => {
+      if (j.status === 'completed') return false
+      if (this.config.maxAge > 0 && now - j.createdAt.getTime() > this.config.maxAge) return false
+      return true
+    })
+
+    const available = this.jobs
+      .filter(j => {
+        if (j.status !== 'pending') return false
+        if (this.processing.has(j.id)) return false
+        if (j.sendAt && j.sendAt.getTime() > now) return false
+        return true
+      })
+      // Highest priority first, then oldest first (FIFO within a priority)
+      .sort((a, b) => {
+        const byPriority = PRIORITY_RANK[b.priority] - PRIORITY_RANK[a.priority]
+        if (byPriority !== 0) return byPriority
+        return a.createdAt.getTime() - b.createdAt.getTime()
+      })
+
+    const slots = this.config.concurrency - this.processing.size
+    const toProcess = available.slice(0, slots)
+
+    await Promise.all(toProcess.map(job => this.processJob(job)))
+  }
+
+  private async processJob(job: QueueJob): Promise<void> {
+    this.processing.add(job.id)
+    job.status = 'processing'
+    job.attempts++
+
+    try {
+      await this.handler(job)
+      job.status = 'completed'
+      this.completedCount++
+    } catch (err) {
+      job.lastError = err instanceof Error ? err.message : String(err)
+
+      // `retries` is the number of retries after the initial attempt, so total attempts =
+      // 1 + retries. `attempts` is pre-incremented, hence `<=`.
+      if (job.attempts <= this.config.retries) {
+        job.status = 'pending'
+        // Exponential backoff
+        job.sendAt = new Date(Date.now() + this.config.retryDelay * Math.pow(2, job.attempts - 1))
+      } else {
+        job.status = 'failed'
+      }
+    } finally {
+      this.processing.delete(job.id)
+    }
+  }
+
+  private scheduleFlush() {
+    if (!this.running || this.timer) return
+    this.timer = setTimeout(async () => {
+      this.timer = null
+      await this.flush()
+      if (this.jobs.some(j => j.status === 'pending')) {
+        this.scheduleFlush()
+      }
+    }, 100)
+  }
+}

package/src/queue/index.ts

@@ -0,0 +1 @@
+export { EmailQueue } from './EmailQueue'

package/src/templates/HandlebarsEngine.ts

@@ -0,0 +1,152 @@
+import fs from 'fs'
+import path from 'path'
+import type Handlebars from 'handlebars'
+import type { EmailTemplatesConfig } from '../types'
+
+type HandlebarsInstance = typeof Handlebars
+
+let handlebars: HandlebarsInstance | undefined
+
+function getHandlebars(): HandlebarsInstance {
+  if (!handlebars) {
+    try {
+      handlebars = require('handlebars') as HandlebarsInstance
+    } catch {
+      throw new Error(
+        'Handlebars is not installed. Run: npm install handlebars'
+      )
+    }
+  }
+  return handlebars
+}
+
+export class HandlebarsEngine {
+  private hbs: HandlebarsInstance
+  private cache = new Map<string, HandlebarsTemplateDelegate>()
+  private config: EmailTemplatesConfig
+
+  constructor(config: EmailTemplatesConfig) {
+    this.hbs = getHandlebars().create()
+    this.config = config
+    this.registerHelpers()
+    this.registerPartials()
+  }
+
+  private registerHelpers() {
+    // Handlebars engine options are a flat shape: `{ noEscape?, helpers? }` (see EmailTemplatesConfig).
+    const helpers = this.config.engineOptions?.helpers as
+      | Record<string, unknown>
+      | undefined
+    if (!helpers) return
+    for (const [name, fn] of Object.entries(helpers)) {
+      this.hbs.registerHelper(name, fn as Handlebars.HelperDelegate)
+    }
+  }
+
+  private compileOptions() {
+    return this.config.engineOptions?.noEscape ? { noEscape: true } : undefined
+  }
+
+  private registerPartials() {
+    // `partials` is a boolean flag (default: enabled). Load from `<dir>/partials` when on.
+    if (this.config.partials === false || !this.config.dir) return
+    const partialsDir = path.join(this.config.dir, 'partials')
+
+    if (!fs.existsSync(partialsDir)) return
+
+    const files = fs.readdirSync(partialsDir)
+    for (const file of files) {
+      if (!/\.(hbs|handlebars)$/.test(file)) continue
+      const name = path.basename(file, path.extname(file))
+      const content = fs.readFileSync(path.join(partialsDir, file), 'utf-8')
+      this.hbs.registerPartial(name, content)
+    }
+  }
+
+  async render(templateName: string, data: Record<string, unknown>): Promise<string> {
+    const compiled = this.getCompiled(templateName)
+    const layout = this.config.layouts
+      ? this.resolveLayout(templateName)
+      : null
+
+    let body = compiled(data)
+
+    if (layout) {
+      const layoutTemplate = this.getCompiledLayout(layout)
+      body = layoutTemplate({ ...data, body })
+    }
+
+    return body
+  }
+
+  private getCompiled(templateName: string): HandlebarsTemplateDelegate {
+    const cacheKey = `template:${templateName}`
+    if (this.config.cache !== false && this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey)!
+    }
+
+    const filePath = this.resolveTemplatePath(templateName)
+    const source = fs.readFileSync(filePath, 'utf-8')
+    const compiled = this.hbs.compile(source, this.compileOptions())
+
+    if (this.config.cache !== false) {
+      this.cache.set(cacheKey, compiled)
+    }
+
+    return compiled
+  }
+
+  private getCompiledLayout(layoutPath: string): HandlebarsTemplateDelegate {
+    const cacheKey = `layout:${layoutPath}`
+    if (this.config.cache !== false && this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey)!
+    }
+
+    const source = fs.readFileSync(layoutPath, 'utf-8')
+    const compiled = this.hbs.compile(source, this.compileOptions())
+
+    if (this.config.cache !== false) {
+      this.cache.set(cacheKey, compiled)
+    }
+
+    return compiled
+  }
+
+  private resolveTemplatePath(templateName: string): string {
+    if (!this.config.dir) {
+      throw new Error('templates.dir must be set to use template rendering')
+    }
+    const candidates = [
+      path.join(this.config.dir, `${templateName}.hbs`),
+      path.join(this.config.dir, `${templateName}.handlebars`),
+      path.join(this.config.dir, templateName, 'html.hbs'),
+      path.join(this.config.dir, templateName, 'html.handlebars'),
+    ]
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) return candidate
+    }
+    throw new Error(`Handlebars template not found: ${templateName} (searched in ${this.config.dir})`)
+  }
+
+  private resolveLayout(templateName: string): string | null {
+    if (!this.config.layouts) return null
+
+    // Per-template layout override: templates/<name>/layout.hbs
+    if (this.config.dir) {
+      const perTemplate = path.join(this.config.dir, templateName, 'layout.hbs')
+      if (fs.existsSync(perTemplate)) return perTemplate
+    }
+
+    // Default layout: templates/layouts/default.hbs
+    const defaultLayout = path.join(this.config.dir, 'layouts', 'default.hbs')
+    if (fs.existsSync(defaultLayout)) return defaultLayout
+
+    return null
+  }
+
+  clearCache() {
+    this.cache.clear()
+  }
+}
+
+type HandlebarsTemplateDelegate = (context: unknown, options?: Handlebars.RuntimeOptions) => string