@stravigor/core 0.1.0

package/src/mail/css_inliner.ts

@@ -0,0 +1,79 @@
+import juice from 'juice'
+
+export interface InlinerOptions {
+  /** Enable CSS inlining (default: true). */
+  enabled: boolean
+  /** Enable Tailwind CSS compilation before inlining (default: false). */
+  tailwind: boolean
+}
+
+/**
+ * Process rendered HTML for email delivery:
+ * 1. Optionally compile Tailwind classes to CSS
+ * 2. Inline all <style> blocks into style="" attributes via juice
+ */
+export async function inlineCss(html: string, options: InlinerOptions): Promise<string> {
+  if (!options.enabled) return html
+
+  let processed = html
+
+  if (options.tailwind) {
+    processed = await compileTailwind(processed)
+  }
+
+  return juice(processed, {
+    removeStyleTags: true,
+    preserveMediaQueries: true,
+    preserveFontFaces: true,
+    preserveKeyFrames: true,
+    applyWidthAttributes: true,
+    applyHeightAttributes: true,
+    applyAttributesTableElements: true,
+  })
+}
+
+/**
+ * Extract Tailwind utility classes from HTML and compile them to CSS,
+ * then inject a <style> block for juice to inline.
+ *
+ * Uses dynamic import — silently skips if tailwindcss is not installed.
+ */
+async function compileTailwind(html: string): Promise<string> {
+  try {
+    // @ts-ignore: Tailwind is optional
+    const { compile } = await import('tailwindcss')
+
+    const compiler = await compile('@tailwind utilities;')
+    const classes = extractClasses(html)
+
+    if (classes.length === 0) return html
+
+    const css = compiler.build(classes)
+    if (!css) return html
+
+    const insertPoint = html.indexOf('</head>')
+    if (insertPoint !== -1) {
+      return html.slice(0, insertPoint) + `<style>${css}</style>` + html.slice(insertPoint)
+    }
+    return `<style>${css}</style>` + html
+  } catch {
+    // tailwindcss not installed or API mismatch — skip silently
+    return html
+  }
+}
+
+/** Extract class names from HTML class="..." attributes. */
+function extractClasses(html: string): string[] {
+  const classRegex = /class\s*=\s*["']([^"']*)["']/gi
+  const classes = new Set<string>()
+
+  let match
+  while ((match = classRegex.exec(html)) !== null) {
+    for (const cls of match[1]!.split(/\s+/)) {
+      const trimmed = cls.trim()
+      if (trimmed) classes.add(trimmed)
+    }
+  }
+
+  return [...classes]
+}

package/src/mail/helpers.ts

@@ -0,0 +1,212 @@
+import MailManager from './mail_manager.ts'
+import ViewEngine from '../view/engine.ts'
+import { inlineCss } from './css_inliner.ts'
+import Queue from '../queue/queue.ts'
+import type { MailMessage, MailResult, MailAttachment } from './types.ts'
+
+/**
+ * Fluent email builder. Returned by `mail.to()`.
+ *
+ * @example
+ * await mail.to('user@example.com')
+ *   .subject('Welcome!')
+ *   .template('welcome', { name: 'Alice' })
+ *   .send()
+ *
+ * await mail.to(user.email)
+ *   .from('support@app.com')
+ *   .subject('Reset Password')
+ *   .template('reset', { token })
+ *   .queue()
+ */
+export class PendingMail {
+  private _from?: string
+  private _to: string | string[]
+  private _cc?: string | string[]
+  private _bcc?: string | string[]
+  private _replyTo?: string
+  private _subject = ''
+  private _html?: string
+  private _text?: string
+  private _attachments: MailAttachment[] = []
+  private _template?: string
+  private _templateData?: Record<string, unknown>
+
+  constructor(to: string | string[]) {
+    this._to = to
+  }
+
+  from(address: string): this {
+    this._from = address
+    return this
+  }
+
+  cc(address: string | string[]): this {
+    this._cc = address
+    return this
+  }
+
+  bcc(address: string | string[]): this {
+    this._bcc = address
+    return this
+  }
+
+  replyTo(address: string): this {
+    this._replyTo = address
+    return this
+  }
+
+  subject(value: string): this {
+    this._subject = value
+    return this
+  }
+
+  /** Set raw HTML content (bypasses template rendering). */
+  html(value: string): this {
+    this._html = value
+    return this
+  }
+
+  /** Set plain text content. */
+  text(value: string): this {
+    this._text = value
+    return this
+  }
+
+  /** Use a .strav template. Name is relative to the mail template prefix. */
+  template(name: string, data: Record<string, unknown> = {}): this {
+    this._template = name
+    this._templateData = data
+    return this
+  }
+
+  attach(attachment: MailAttachment): this {
+    this._attachments.push(attachment)
+    return this
+  }
+
+  /** Build the MailMessage, rendering template + inlining CSS if needed. */
+  async build(): Promise<MailMessage> {
+    const config = MailManager.config
+    let html = this._html
+    const text = this._text
+
+    if (this._template) {
+      const templateName = `${config.templatePrefix}.${this._template}`
+      html = await ViewEngine.instance.render(templateName, this._templateData ?? {})
+    }
+
+    if (html) {
+      html = await inlineCss(html, {
+        enabled: config.inlineCss,
+        tailwind: config.tailwind,
+      })
+    }
+
+    return {
+      from: this._from ?? config.from,
+      to: this._to,
+      cc: this._cc,
+      bcc: this._bcc,
+      replyTo: this._replyTo,
+      subject: this._subject,
+      html,
+      text,
+      attachments: this._attachments.length > 0 ? this._attachments : undefined,
+    }
+  }
+
+  /** Send the email immediately via the configured transport. */
+  async send(): Promise<MailResult> {
+    const message = await this.build()
+    return MailManager.transport.send(message)
+  }
+
+  /** Push the email onto the job queue for async sending. */
+  async queue(options?: { queue?: string; delay?: number }): Promise<number> {
+    const message = await this.build()
+    return Queue.push('strav:send-mail', message, options)
+  }
+}
+
+/**
+ * Mail helper object — the primary API for sending emails.
+ *
+ * @example
+ * import { mail } from '@stravigor/core/mail'
+ *
+ * // Fluent builder
+ * await mail.to('user@example.com').subject('Hello').template('welcome', { name }).send()
+ *
+ * // Convenience send
+ * await mail.send({ to: 'user@example.com', subject: 'Hello', template: 'welcome', data: { name } })
+ *
+ * // Raw HTML send
+ * await mail.raw({ to: 'user@example.com', subject: 'Hello', html: '<h1>Hi</h1>' })
+ */
+export const mail = {
+  /** Start building an email to the given recipient(s). Returns a fluent PendingMail. */
+  to(address: string | string[]): PendingMail {
+    return new PendingMail(address)
+  },
+
+  /** Send an email using a template. Convenience wrapper for the fluent API. */
+  async send(options: {
+    to: string | string[]
+    from?: string
+    cc?: string | string[]
+    bcc?: string | string[]
+    replyTo?: string
+    subject: string
+    template: string
+    data?: Record<string, unknown>
+    attachments?: MailAttachment[]
+  }): Promise<MailResult> {
+    const pending = new PendingMail(options.to)
+      .subject(options.subject)
+      .template(options.template, options.data)
+    if (options.from) pending.from(options.from)
+    if (options.cc) pending.cc(options.cc)
+    if (options.bcc) pending.bcc(options.bcc)
+    if (options.replyTo) pending.replyTo(options.replyTo)
+    if (options.attachments) {
+      for (const a of options.attachments) pending.attach(a)
+    }
+    return pending.send()
+  },
+
+  /** Send a raw email without template rendering. */
+  async raw(options: {
+    to: string | string[]
+    from?: string
+    cc?: string | string[]
+    bcc?: string | string[]
+    replyTo?: string
+    subject: string
+    html?: string
+    text?: string
+    attachments?: MailAttachment[]
+  }): Promise<MailResult> {
+    const pending = new PendingMail(options.to).subject(options.subject)
+    if (options.from) pending.from(options.from)
+    if (options.html) pending.html(options.html)
+    if (options.text) pending.text(options.text)
+    if (options.cc) pending.cc(options.cc)
+    if (options.bcc) pending.bcc(options.bcc)
+    if (options.replyTo) pending.replyTo(options.replyTo)
+    if (options.attachments) {
+      for (const a of options.attachments) pending.attach(a)
+    }
+    return pending.send()
+  },
+
+  /**
+   * Register the built-in queue handler for async mail sending.
+   * Call this in your app bootstrap after Queue is configured.
+   */
+  registerQueueHandler(): void {
+    Queue.handle<MailMessage>('strav:send-mail', async (message) => {
+      await MailManager.transport.send(message)
+    })
+  },
+}

package/src/mail/index.ts

@@ -0,0 +1,19 @@
+export { default, default as MailManager } from './mail_manager.ts'
+export { mail, PendingMail } from './helpers.ts'
+export { SmtpTransport } from './transports/smtp_transport.ts'
+export { ResendTransport } from './transports/resend_transport.ts'
+export { SendGridTransport } from './transports/sendgrid_transport.ts'
+export { LogTransport } from './transports/log_transport.ts'
+export { inlineCss } from './css_inliner.ts'
+export type {
+  MailTransport,
+  MailMessage,
+  MailResult,
+  MailAttachment,
+  MailConfig,
+  SmtpConfig,
+  ResendConfig,
+  SendGridConfig,
+  LogConfig,
+} from './types.ts'
+export type { InlinerOptions } from './css_inliner.ts'

package/src/mail/mail_manager.ts

@@ -0,0 +1,92 @@
+import { inject } from '../core/inject.ts'
+import { ConfigurationError } from '../exceptions/errors.ts'
+import Configuration from '../config/configuration.ts'
+import { SmtpTransport } from './transports/smtp_transport.ts'
+import { ResendTransport } from './transports/resend_transport.ts'
+import { SendGridTransport } from './transports/sendgrid_transport.ts'
+import { LogTransport } from './transports/log_transport.ts'
+import type { MailTransport, MailConfig } from './types.ts'
+
+/**
+ * Central mail configuration hub.
+ *
+ * Resolved once via the DI container — reads the mail config
+ * and initializes the appropriate transport driver.
+ *
+ * @example
+ * app.singleton(MailManager)
+ * app.resolve(MailManager)
+ *
+ * // Plug in a custom transport
+ * MailManager.useTransport(new MyCustomTransport())
+ */
+@inject
+export default class MailManager {
+  private static _transport: MailTransport
+  private static _config: MailConfig
+
+  constructor(config: Configuration) {
+    const driverName = config.get('mail.default', 'log') as string
+
+    MailManager._config = {
+      default: driverName,
+      from: config.get('mail.from', 'noreply@localhost') as string,
+      templatePrefix: config.get('mail.templatePrefix', 'emails') as string,
+      inlineCss: config.get('mail.inlineCss', true) as boolean,
+      tailwind: config.get('mail.tailwind', false) as boolean,
+      smtp: {
+        host: '127.0.0.1',
+        port: 587,
+        secure: false,
+        ...(config.get('mail.smtp', {}) as object),
+      },
+      resend: {
+        apiKey: '',
+        ...(config.get('mail.resend', {}) as object),
+      },
+      sendgrid: {
+        apiKey: '',
+        ...(config.get('mail.sendgrid', {}) as object),
+      },
+      log: {
+        output: 'console',
+        ...(config.get('mail.log', {}) as object),
+      },
+    }
+
+    MailManager._transport = MailManager.createTransport(driverName)
+  }
+
+  private static createTransport(driver: string): MailTransport {
+    switch (driver) {
+      case 'smtp':
+        return new SmtpTransport(MailManager._config.smtp)
+      case 'resend':
+        return new ResendTransport(MailManager._config.resend)
+      case 'sendgrid':
+        return new SendGridTransport(MailManager._config.sendgrid)
+      case 'log':
+        return new LogTransport(MailManager._config.log)
+      default:
+        throw new ConfigurationError(
+          `Unknown mail transport: ${driver}. Use MailManager.useTransport() for custom transports.`
+        )
+    }
+  }
+
+  static get transport(): MailTransport {
+    if (!MailManager._transport) {
+      throw new ConfigurationError('MailManager not configured. Resolve it through the container first.')
+    }
+    return MailManager._transport
+  }
+
+  static get config(): MailConfig {
+    return MailManager._config
+  }
+
+  /** Swap the transport at runtime (e.g., for testing or a custom provider). */
+  static useTransport(transport: MailTransport): void {
+    MailManager._transport = transport
+  }
+}

package/src/mail/transports/log_transport.ts

@@ -0,0 +1,69 @@
+import type { MailTransport, MailMessage, MailResult, LogConfig } from '../types.ts'
+
+/**
+ * Development/testing transport — logs email details to console or a file.
+ * No external dependencies required.
+ */
+export class LogTransport implements MailTransport {
+  private output: 'console' | string
+
+  constructor(config: LogConfig) {
+    this.output = config.output ?? 'console'
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const timestamp = new Date().toISOString()
+    const separator = '─'.repeat(60)
+    const toList = Array.isArray(message.to) ? message.to.join(', ') : message.to
+
+    const lines = [
+      separator,
+      `[Mail] ${timestamp}`,
+      `From:     ${message.from}`,
+      `To:       ${toList}`,
+    ]
+
+    if (message.cc) {
+      const cc = Array.isArray(message.cc) ? message.cc.join(', ') : message.cc
+      lines.push(`CC:       ${cc}`)
+    }
+    if (message.bcc) {
+      const bcc = Array.isArray(message.bcc) ? message.bcc.join(', ') : message.bcc
+      lines.push(`BCC:      ${bcc}`)
+    }
+    if (message.replyTo) lines.push(`Reply-To: ${message.replyTo}`)
+
+    lines.push(`Subject:  ${message.subject}`)
+
+    if (message.text) {
+      lines.push('', '--- Text ---', message.text)
+    }
+    if (message.html) {
+      lines.push('', '--- HTML ---', message.html)
+    }
+    if (message.attachments?.length) {
+      lines.push('', `--- Attachments (${message.attachments.length}) ---`)
+      for (const a of message.attachments) {
+        lines.push(`  ${a.filename} (${a.contentType ?? 'unknown'})`)
+      }
+    }
+
+    lines.push(separator, '')
+
+    const output = lines.join('\n')
+
+    if (this.output === 'console') {
+      console.log(output)
+    } else {
+      const file = Bun.file(this.output)
+      const existing = (await file.exists()) ? await file.text() : ''
+      await Bun.write(this.output, existing + output + '\n')
+    }
+
+    const messageId = `log-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    return {
+      messageId,
+      accepted: Array.isArray(message.to) ? message.to : [message.to],
+    }
+  }
+}

package/src/mail/transports/resend_transport.ts

@@ -0,0 +1,59 @@
+import { ExternalServiceError } from '../../exceptions/errors.ts'
+import type { MailTransport, MailMessage, MailResult, ResendConfig } from '../types.ts'
+
+/**
+ * Resend HTTP API transport.
+ * Uses fetch — no SDK dependency required.
+ *
+ * @see https://resend.com/docs/api-reference/emails/send-email
+ */
+export class ResendTransport implements MailTransport {
+  private apiKey: string
+  private baseUrl: string
+
+  constructor(config: ResendConfig) {
+    this.apiKey = config.apiKey
+    this.baseUrl = config.baseUrl ?? 'https://api.resend.com'
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const body: Record<string, unknown> = {
+      from: message.from,
+      to: Array.isArray(message.to) ? message.to : [message.to],
+      subject: message.subject,
+    }
+
+    if (message.cc) body.cc = Array.isArray(message.cc) ? message.cc : [message.cc]
+    if (message.bcc) body.bcc = Array.isArray(message.bcc) ? message.bcc : [message.bcc]
+    if (message.replyTo) body.reply_to = message.replyTo
+    if (message.html) body.html = message.html
+    if (message.text) body.text = message.text
+
+    if (message.attachments?.length) {
+      body.attachments = message.attachments.map((a) => ({
+        filename: a.filename,
+        content: typeof a.content === 'string'
+          ? a.content
+          : Buffer.from(a.content).toString('base64'),
+        content_type: a.contentType,
+      }))
+    }
+
+    const response = await fetch(`${this.baseUrl}/emails`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const error = await response.text()
+      throw new ExternalServiceError('Resend', response.status, error)
+    }
+
+    const data = (await response.json()) as { id: string }
+    return { messageId: data.id }
+  }
+}

package/src/mail/transports/sendgrid_transport.ts

@@ -0,0 +1,77 @@
+import { ExternalServiceError } from '../../exceptions/errors.ts'
+import type { MailTransport, MailMessage, MailResult, SendGridConfig } from '../types.ts'
+
+/**
+ * SendGrid v3 Mail Send API transport.
+ * Uses fetch — no SDK dependency required.
+ *
+ * @see https://docs.sendgrid.com/api-reference/mail-send/mail-send
+ */
+export class SendGridTransport implements MailTransport {
+  private apiKey: string
+  private baseUrl: string
+
+  constructor(config: SendGridConfig) {
+    this.apiKey = config.apiKey
+    this.baseUrl = config.baseUrl ?? 'https://api.sendgrid.com/v3'
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const toArray = Array.isArray(message.to) ? message.to : [message.to]
+
+    const personalizations: Record<string, unknown>[] = [{
+      to: toArray.map((email) => ({ email })),
+    }]
+
+    if (message.cc) {
+      const ccArray = Array.isArray(message.cc) ? message.cc : [message.cc]
+      personalizations[0]!.cc = ccArray.map((email) => ({ email }))
+    }
+    if (message.bcc) {
+      const bccArray = Array.isArray(message.bcc) ? message.bcc : [message.bcc]
+      personalizations[0]!.bcc = bccArray.map((email) => ({ email }))
+    }
+
+    const content: { type: string; value: string }[] = []
+    if (message.text) content.push({ type: 'text/plain', value: message.text })
+    if (message.html) content.push({ type: 'text/html', value: message.html })
+
+    const body: Record<string, unknown> = {
+      personalizations,
+      from: { email: message.from },
+      subject: message.subject,
+      content,
+    }
+
+    if (message.replyTo) body.reply_to = { email: message.replyTo }
+
+    if (message.attachments?.length) {
+      body.attachments = message.attachments.map((a) => ({
+        filename: a.filename,
+        content: typeof a.content === 'string'
+          ? Buffer.from(a.content).toString('base64')
+          : Buffer.from(a.content).toString('base64'),
+        type: a.contentType,
+        disposition: a.cid ? 'inline' : 'attachment',
+        content_id: a.cid,
+      }))
+    }
+
+    const response = await fetch(`${this.baseUrl}/mail/send`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+
+    if (!response.ok) {
+      const error = await response.text()
+      throw new ExternalServiceError('SendGrid', response.status, error)
+    }
+
+    const messageId = response.headers.get('X-Message-Id') ?? undefined
+    return { messageId, accepted: toArray }
+  }
+}

package/src/mail/transports/smtp_transport.ts

@@ -0,0 +1,48 @@
+import nodemailer from 'nodemailer'
+import type { MailTransport, MailMessage, MailResult, SmtpConfig } from '../types.ts'
+
+/**
+ * SMTP transport via nodemailer.
+ * Supports all standard SMTP features including TLS, auth, and attachments.
+ */
+export class SmtpTransport implements MailTransport {
+  private transporter: nodemailer.Transporter
+
+  constructor(config: SmtpConfig) {
+    this.transporter = nodemailer.createTransport({
+      host: config.host,
+      port: config.port,
+      secure: config.secure,
+      auth: config.auth?.user ? { user: config.auth.user, pass: config.auth.pass } : undefined,
+    })
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const info = await this.transporter.sendMail({
+      from: message.from,
+      to: Array.isArray(message.to) ? message.to.join(', ') : message.to,
+      cc: message.cc
+        ? Array.isArray(message.cc) ? message.cc.join(', ') : message.cc
+        : undefined,
+      bcc: message.bcc
+        ? Array.isArray(message.bcc) ? message.bcc.join(', ') : message.bcc
+        : undefined,
+      replyTo: message.replyTo,
+      subject: message.subject,
+      html: message.html,
+      text: message.text,
+      attachments: message.attachments?.map((a) => ({
+        filename: a.filename,
+        content: a.content,
+        contentType: a.contentType,
+        cid: a.cid,
+      })),
+    })
+
+    return {
+      messageId: info.messageId,
+      accepted: Array.isArray(info.accepted) ? info.accepted.map(String) : [],
+      rejected: Array.isArray(info.rejected) ? info.rejected.map(String) : [],
+    }
+  }
+}