@nixxie-cms/email 1.0.1

package/src/templates/PugEngine.ts

@@ -0,0 +1,101 @@
+import fs from 'fs'
+import path from 'path'
+import type pug from 'pug'
+import type { EmailTemplatesConfig } from '../types'
+
+type PugModule = typeof pug
+
+let pugModule: PugModule | undefined
+
+function getPug(): PugModule {
+  if (!pugModule) {
+    try {
+      pugModule = require('pug') as PugModule
+    } catch {
+      throw new Error('Pug is not installed. Run: npm install pug')
+    }
+  }
+  return pugModule
+}
+
+export class PugEngine {
+  private cache = new Map<string, pug.compileTemplate>()
+  private config: EmailTemplatesConfig
+
+  constructor(config: EmailTemplatesConfig) {
+    this.config = config
+  }
+
+  async render(templateName: string, data: Record<string, unknown>): Promise<string> {
+    const p = getPug()
+    const compiled = this.getCompiled(templateName, p)
+    const layout = this.config.layouts ? this.resolveLayout(templateName) : null
+
+    const renderData: Record<string, unknown> = { ...data }
+    if (layout) {
+      renderData['layout'] = layout
+    }
+
+    return compiled(renderData)
+  }
+
+  private getCompiled(templateName: string, p: PugModule): pug.compileTemplate {
+    const cacheKey = `template:${templateName}`
+    if (this.config.cache !== false && this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey)!
+    }
+
+    const filePath = this.resolveTemplatePath(templateName)
+    const engineOptions = this.config.engineOptions?.pug ?? {}
+
+    const compiled = p.compileFile(filePath, {
+      ...engineOptions,
+      filename: filePath,
+      cache: false,
+    })
+
+    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}.pug`),
+      path.join(this.config.dir, `${templateName}.jade`),
+      path.join(this.config.dir, templateName, 'html.pug'),
+      path.join(this.config.dir, templateName, 'index.pug'),
+    ]
+
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) return candidate
+    }
+
+    throw new Error(`Pug template not found: ${templateName} (searched in ${this.config.dir})`)
+  }
+
+  private resolveLayout(templateName: string): string | null {
+    if (!this.config.layouts) return null
+
+    if (this.config.dir) {
+      const perTemplate = path.join(this.config.dir, templateName, 'layout.pug')
+      if (fs.existsSync(perTemplate)) return perTemplate
+    }
+
+    // Default layout: templates/layouts/default.pug
+    const defaultLayout = path.join(this.config.dir, 'layouts', 'default.pug')
+    if (fs.existsSync(defaultLayout)) return defaultLayout
+
+    return null
+  }
+
+  clearCache() {
+    this.cache.clear()
+  }
+}

package/src/templates/TemplateManager.ts

@@ -0,0 +1,180 @@
+import fs from 'fs'
+import path from 'path'
+import type { EmailTemplatesConfig } from '../types'
+import { HandlebarsEngine } from './HandlebarsEngine'
+import { PugEngine } from './PugEngine'
+
+export type RenderedEmail = {
+  html: string
+  text: string | undefined
+  subject: string | undefined
+}
+
+export class TemplateManager {
+  private handlebars: HandlebarsEngine | undefined
+  private pug: PugEngine | undefined
+  private config: EmailTemplatesConfig
+
+  constructor(config: EmailTemplatesConfig) {
+    this.config = config
+    const engine = config.engine ?? 'handlebars'
+    if (engine === 'handlebars' || engine === 'auto') {
+      this.handlebars = new HandlebarsEngine(config)
+    }
+    if (engine === 'pug' || engine === 'auto') {
+      this.pug = new PugEngine(config)
+    }
+  }
+
+  async render(templateName: string, data: Record<string, unknown>): Promise<RenderedEmail> {
+    const engine = this.detectEngine(templateName)
+
+    switch (engine) {
+      case 'handlebars':
+        return this.renderWithHandlebars(templateName, data)
+      case 'pug':
+        return this.renderWithPug(templateName, data)
+      default:
+        throw new Error(`No template engine configured for template: ${templateName}`)
+    }
+  }
+
+  private detectEngine(templateName: string): 'handlebars' | 'pug' | null {
+    const configuredEngine = this.config.engine ?? 'handlebars'
+
+    if (configuredEngine === 'auto' || configuredEngine === 'handlebars') {
+      if (this.config.dir) {
+        const hbsCandidates = [
+          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'),
+        ]
+        if (hbsCandidates.some(p => fs.existsSync(p))) return 'handlebars'
+      }
+    }
+
+    if (configuredEngine === 'auto' || configuredEngine === 'pug') {
+      if (this.config.dir) {
+        const pugCandidates = [
+          path.join(this.config.dir, `${templateName}.pug`),
+          path.join(this.config.dir, `${templateName}.jade`),
+          path.join(this.config.dir, templateName, 'html.pug'),
+          path.join(this.config.dir, templateName, 'index.pug'),
+        ]
+        if (pugCandidates.some(p => fs.existsSync(p))) return 'pug'
+      }
+    }
+
+    if (configuredEngine !== 'auto') return configuredEngine
+
+    return null
+  }
+
+  private async renderWithHandlebars(
+    templateName: string,
+    data: Record<string, unknown>
+  ): Promise<RenderedEmail> {
+    if (!this.handlebars) {
+      this.handlebars = new HandlebarsEngine(this.config)
+    }
+
+    const html = await this.handlebars.render(templateName, data)
+    const text = await this.renderTextVersion(templateName, data, 'handlebars')
+    const subject = await this.renderSubject(templateName, data, 'handlebars')
+
+    return { html, text, subject }
+  }
+
+  private async renderWithPug(
+    templateName: string,
+    data: Record<string, unknown>
+  ): Promise<RenderedEmail> {
+    if (!this.pug) {
+      this.pug = new PugEngine(this.config)
+    }
+
+    const html = await this.pug.render(templateName, data)
+    const text = await this.renderTextVersion(templateName, data, 'pug')
+    const subject = await this.renderSubject(templateName, data, 'pug')
+
+    return { html, text, subject }
+  }
+
+  private async renderTextVersion(
+    templateName: string,
+    data: Record<string, unknown>,
+    engine: 'handlebars' | 'pug'
+  ): Promise<string | undefined> {
+    if (!this.config.dir) return undefined
+
+    const textPaths = engine === 'handlebars'
+      ? [
+          path.join(this.config.dir, templateName, 'text.hbs'),
+          path.join(this.config.dir, templateName, 'text.handlebars'),
+          path.join(this.config.dir, `${templateName}.text.hbs`),
+        ]
+      : [
+          path.join(this.config.dir, templateName, 'text.pug'),
+          path.join(this.config.dir, `${templateName}.text.pug`),
+        ]
+
+    const textFile = textPaths.find(p => fs.existsSync(p))
+    if (!textFile) return undefined
+
+    // Render a plain-text variant using the same engine but without layout
+    const textConfig = { ...this.config, layouts: undefined }
+    try {
+      if (engine === 'handlebars') {
+        const eng = new HandlebarsEngine(textConfig)
+        return await eng.render(path.relative(this.config.dir!, textFile).replace(/\\/g, '/').replace(/\.(hbs|handlebars)$/, ''), data)
+      } else {
+        const eng = new PugEngine(textConfig)
+        return await eng.render(path.relative(this.config.dir!, textFile).replace(/\\/g, '/').replace(/\.(pug|jade)$/, ''), data)
+      }
+    } catch {
+      // Fall back to reading the file as plain template
+      return fs.readFileSync(textFile, 'utf-8')
+    }
+  }
+
+  private async renderSubject(
+    templateName: string,
+    data: Record<string, unknown>,
+    engine: 'handlebars' | 'pug'
+  ): Promise<string | undefined> {
+    if (!this.config.dir) return undefined
+
+    const subjectPaths = engine === 'handlebars'
+      ? [
+          path.join(this.config.dir, templateName, 'subject.hbs'),
+          path.join(this.config.dir, templateName, 'subject.handlebars'),
+        ]
+      : [
+          path.join(this.config.dir, templateName, 'subject.pug'),
+        ]
+
+    const subjectFile = subjectPaths.find(p => fs.existsSync(p))
+    if (!subjectFile) return undefined
+
+    const subjectConfig = { ...this.config, layouts: undefined }
+    try {
+      if (engine === 'handlebars') {
+        const eng = new HandlebarsEngine(subjectConfig)
+        const relative = path.relative(this.config.dir!, subjectFile).replace(/\\/g, '/').replace(/\.(hbs|handlebars)$/, '')
+        return (await eng.render(relative, data)).trim()
+      } else {
+        const eng = new PugEngine(subjectConfig)
+        const relative = path.relative(this.config.dir!, subjectFile).replace(/\\/g, '/').replace(/\.(pug|jade)$/, '')
+        return (await eng.render(relative, data)).trim()
+      }
+    } catch {
+      return undefined
+    }
+  }
+
+  clearCache() {
+    this.handlebars?.clearCache()
+    this.pug?.clearCache()
+  }
+}

package/src/templates/index.ts

@@ -0,0 +1,4 @@
+export { HandlebarsEngine } from './HandlebarsEngine'
+export { PugEngine } from './PugEngine'
+export { TemplateManager } from './TemplateManager'
+export type { RenderedEmail } from './TemplateManager'

package/src/transports/ConsoleTransport.ts

@@ -0,0 +1,50 @@
+import type { EmailTransporter, TransportMessage, TransportResult } from '../types'
+
+let messageCounter = 0
+
+export class ConsoleTransport implements EmailTransporter {
+  async send(message: TransportMessage): Promise<TransportResult> {
+    const id = `console-${Date.now()}-${++messageCounter}`
+
+    const separator = '─'.repeat(60)
+    console.log(`\n${separator}`)
+    console.log('📧  [Nixxie Email — Development Mode]')
+    console.log(separator)
+    console.log(`  From:     ${message.from}`)
+    console.log(`  To:       ${message.to.join(', ')}`)
+    if (message.cc?.length) console.log(`  CC:       ${message.cc.join(', ')}`)
+    if (message.bcc?.length) console.log(`  BCC:      ${message.bcc.join(', ')}`)
+    if (message.replyTo?.length) console.log(`  Reply-To: ${message.replyTo.join(', ')}`)
+    console.log(`  Subject:  ${message.subject}`)
+    console.log(`  ID:       ${id}`)
+    if (message.attachments?.length) {
+      console.log(`  Attachments:`)
+      for (const a of message.attachments) {
+        console.log(`    • ${a.filename ?? a.path ?? 'unnamed'}`)
+      }
+    }
+    if (message.text) {
+      console.log(`\n  Text body:\n  ${message.text.slice(0, 300).replace(/\n/g, '\n  ')}`)
+    }
+    if (message.html) {
+      const truncated = message.html.replace(/<[^>]+>/g, '').trim().slice(0, 200)
+      console.log(`\n  HTML preview:\n  ${truncated}…`)
+    }
+    console.log(`${separator}\n`)
+
+    return {
+      messageId: id,
+      accepted: message.to,
+      rejected: [],
+      response: 'logged',
+    }
+  }
+
+  async verify(): Promise<boolean> {
+    return true
+  }
+
+  async close(): Promise<void> {
+    // nothing to close
+  }
+}

package/src/transports/MailgunTransport.ts

@@ -0,0 +1,58 @@
+import nodemailer from 'nodemailer'
+import type { EmailTransporter, MailgunTransportConfig, TransportMessage, TransportResult } from '../types'
+
+export class MailgunTransport implements EmailTransporter {
+  private transporter: nodemailer.Transporter
+
+  constructor(config: MailgunTransportConfig) {
+    const host =
+      config.region === 'eu'
+        ? 'smtp.eu.mailgun.org'
+        : 'smtp.mailgun.org'
+
+    this.transporter = nodemailer.createTransport({
+      host,
+      port: 587,
+      secure: false,
+      auth: {
+        user: `postmaster@${config.domain}`,
+        pass: config.apiKey,
+      },
+    })
+  }
+
+  async send(message: TransportMessage): Promise<TransportResult> {
+    const info = await this.transporter.sendMail({
+      from: message.from,
+      to: message.to.join(', '),
+      cc: message.cc?.join(', '),
+      bcc: message.bcc?.join(', '),
+      replyTo: message.replyTo?.join(', '),
+      subject: message.subject,
+      html: message.html,
+      text: message.text,
+      attachments: message.attachments,
+      headers: message.headers,
+    })
+
+    return {
+      messageId: info.messageId,
+      accepted: (info.accepted as string[]) ?? message.to,
+      rejected: (info.rejected as string[]) ?? [],
+      response: info.response,
+    }
+  }
+
+  async verify(): Promise<boolean> {
+    try {
+      await this.transporter.verify()
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async close(): Promise<void> {
+    this.transporter.close()
+  }
+}

package/src/transports/ResendTransport.ts

@@ -0,0 +1,83 @@
+import type { EmailTransporter, ResendTransportConfig, TransportMessage, TransportResult } from '../types'
+
+type ResendSendResponse = {
+  id: string
+}
+
+type ResendErrorResponse = {
+  name: string
+  message: string
+  statusCode: number
+}
+
+export class ResendTransport implements EmailTransporter {
+  private readonly apiKey: string
+ 
+  constructor(config: ResendTransportConfig) {
+    this.apiKey = config.apiKey
+  }
+
+  async send(message: TransportMessage): Promise<TransportResult> {
+    const body = {
+      from: message.from,
+      to: message.to,
+      cc: message.cc,
+      bcc: message.bcc,
+      reply_to: message.replyTo,
+      subject: message.subject,
+      html: message.html,
+      text: message.text,
+      headers: message.headers,
+      attachments: message.attachments?.map(a => ({
+        filename: a.filename,
+        // Resend expects attachment `content` as base64; encode raw string/Buffer content.
+        content:
+          a.content == null
+            ? undefined
+            : Buffer.isBuffer(a.content)
+              ? a.content.toString('base64')
+              : Buffer.from(a.content, 'utf-8').toString('base64'),
+        path: a.path,
+      })),
+    }
+
+    const response = await fetch(`${this.baseUrl}/emails`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+
+    const json = await response.json() as ResendSendResponse | ResendErrorResponse
+
+    if (!response.ok) {
+      const err = json as ResendErrorResponse
+      throw new Error(`Resend API error ${response.status}: ${err.message}`)
+    }
+
+    const data = json as ResendSendResponse
+    return {
+      messageId: data.id,
+      accepted: message.to,
+      rejected: [],
+      response: `${response.status} ${response.statusText}`,
+    }
+  }
+
+  async verify(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.baseUrl}/domains`, {
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+      })
+      return response.ok
+    } catch {
+      return false
+    }
+  }
+
+  async close(): Promise<void> {
+    // No persistent connections to close
+  }
+}

package/src/transports/SendGridTransport.ts

@@ -0,0 +1,54 @@
+import nodemailer from 'nodemailer'
+import type { EmailTransporter, SendGridTransportConfig, TransportMessage, TransportResult } from '../types'
+
+export class SendGridTransport implements EmailTransporter {
+  private transporter: nodemailer.Transporter
+
+  constructor(config: SendGridTransportConfig) {
+    // SendGrid supports nodemailer via their SMTP relay
+    this.transporter = nodemailer.createTransport({
+      host: 'smtp.sendgrid.net',
+      port: 587,
+      secure: false,
+      auth: {
+        user: 'apikey',
+        pass: config.apiKey,
+      },
+    })
+  }
+
+  async send(message: TransportMessage): Promise<TransportResult> {
+    const info = await this.transporter.sendMail({
+      from: message.from,
+      to: message.to.join(', '),
+      cc: message.cc?.join(', '),
+      bcc: message.bcc?.join(', '),
+      replyTo: message.replyTo?.join(', '),
+      subject: message.subject,
+      html: message.html,
+      text: message.text,
+      attachments: message.attachments,
+      headers: message.headers,
+    })
+
+    return {
+      messageId: info.messageId,
+      accepted: (info.accepted as string[]) ?? message.to,
+      rejected: (info.rejected as string[]) ?? [],
+      response: info.response,
+    }
+  }
+
+  async verify(): Promise<boolean> {
+    try {
+      await this.transporter.verify()
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async close(): Promise<void> {
+    this.transporter.close()
+  }
+}

package/src/transports/SesTransport.ts

@@ -0,0 +1,58 @@
+import nodemailer from 'nodemailer'
+import type { EmailTransporter, SesTransportConfig, TransportMessage, TransportResult } from '../types'
+
+export class SesTransport implements EmailTransporter {
+  private transporter: nodemailer.Transporter
+
+  constructor(config: SesTransportConfig) {
+    // Uses SES SMTP interface — credentials are SES SMTP credentials (different from IAM keys)
+    // See: https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html
+    this.transporter = nodemailer.createTransport({
+      host: `email-smtp.${config.region}.amazonaws.com`,
+      port: 587,
+      secure: false,
+      auth: config.credentials
+        ? {
+            user: config.credentials.accessKeyId,
+            pass: config.credentials.secretAccessKey,
+          }
+        : undefined,
+      tls: { ciphers: 'SSLv3' },
+    })
+  }
+
+  async send(message: TransportMessage): Promise<TransportResult> {
+    const info = await this.transporter.sendMail({
+      from: message.from,
+      to: message.to.join(', '),
+      cc: message.cc?.join(', '),
+      bcc: message.bcc?.join(', '),
+      replyTo: message.replyTo?.join(', '),
+      subject: message.subject,
+      html: message.html,
+      text: message.text,
+      attachments: message.attachments,
+      headers: message.headers,
+    })
+
+    return {
+      messageId: info.messageId,
+      accepted: (info.accepted as string[]) ?? message.to,
+      rejected: (info.rejected as string[]) ?? [],
+      response: info.response,
+    }
+  }
+
+  async verify(): Promise<boolean> {
+    try {
+      await this.transporter.verify()
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async close(): Promise<void> {
+    this.transporter.close()
+  }
+}

package/src/transports/SmtpTransport.ts

@@ -0,0 +1,66 @@
+import nodemailer from 'nodemailer'
+import type { EmailTransporter, SmtpTransportConfig, TransportMessage, TransportResult } from '../types'
+
+export class SmtpTransport implements EmailTransporter {
+  private transporter: nodemailer.Transporter
+
+  constructor(config: SmtpTransportConfig) {
+    this.transporter = nodemailer.createTransport({
+      host: config.host,
+      port: config.port ?? 587,
+      secure: config.secure ?? (config.port === 465),
+      auth: config.auth,
+      tls: config.tls,
+      connectionTimeout: config.connectionTimeout ?? 5_000,
+      greetingTimeout: config.greetingTimeout ?? 5_000,
+      socketTimeout: config.socketTimeout ?? 30_000,
+      pool: config.pool ?? false,
+      maxConnections: config.maxConnections ?? 5,
+      maxMessages: config.maxMessages ?? 100,
+    })
+  }
+
+  async send(message: TransportMessage): Promise<TransportResult> {
+    const info = await this.transporter.sendMail({
+      from: message.from,
+      to: message.to.join(', '),
+      cc: message.cc?.join(', '),
+      bcc: message.bcc?.join(', '),
+      replyTo: message.replyTo?.join(', '),
+      subject: message.subject,
+      html: message.html,
+      text: message.text,
+      attachments: message.attachments?.map(a => ({
+        filename: a.filename,
+        content: a.content,
+        path: a.path,
+        href: a.href,
+        contentType: a.contentType,
+        encoding: a.encoding,
+        contentDisposition: a.contentDisposition,
+        cid: a.cid,
+      })),
+      headers: message.headers,
+    })
+
+    return {
+      messageId: info.messageId,
+      accepted: (info.accepted as string[]) ?? [],
+      rejected: (info.rejected as string[]) ?? [],
+      response: info.response,
+    }
+  }
+
+  async verify(): Promise<boolean> {
+    try {
+      await this.transporter.verify()
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async close(): Promise<void> {
+    this.transporter.close()
+  }
+}

package/src/transports/index.ts

@@ -0,0 +1,30 @@
+import type { EmailTransportConfig, EmailTransporter } from '../types'
+import { ConsoleTransport } from './ConsoleTransport'
+import { MailgunTransport } from './MailgunTransport'
+import { ResendTransport } from './ResendTransport'
+import { SendGridTransport } from './SendGridTransport'
+import { SesTransport } from './SesTransport'
+import { SmtpTransport } from './SmtpTransport'
+
+export function createTransport(config: EmailTransportConfig): EmailTransporter {
+  switch (config.type) {
+    case 'smtp':
+      return new SmtpTransport(config)
+    case 'sendgrid':
+      return new SendGridTransport(config)
+    case 'mailgun':
+      return new MailgunTransport(config)
+    case 'ses':
+      return new SesTransport(config)
+    case 'resend':
+      return new ResendTransport(config)
+    case 'console':
+      return new ConsoleTransport()
+    default: {
+      const exhaustiveCheck: never = config
+      throw new Error(`Unknown email transport type: ${(exhaustiveCheck as any).type}`)
+    }
+  }
+}
+
+export { SmtpTransport, SendGridTransport, MailgunTransport, SesTransport, ResendTransport, ConsoleTransport }