@mantiq/mail 0.1.3 → 0.3.0-rc.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mantiq/mail",
-  "version": "0.1.3",
-  "description": "Mail transports, message builder",
+  "version": "0.3.0-rc.2",
+  "description": "Transactional email — SMTP, Resend, SendGrid, Mailgun, Postmark, SES, markdown templates",
   "type": "module",
   "license": "MIT",
   "author": "Abdullah Khan",
@@ -40,19 +40,23 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --packages=external",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"
   },
   "devDependencies": {
     "bun-types": "latest",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "@mantiq/core": "workspace:*"
   },
   "optionalDependencies": {
     "@mantiq/queue": "^0.1.0"
   },
   "peerDependencies": {
     "@mantiq/core": "^0.1.0"
+  },
+  "mantiq": {
+    "provider": "MailServiceProvider"
   }
 }

package/src/MailManager.ts

@@ -0,0 +1,115 @@
+import type { MailTransport } from './contracts/Transport.ts'
+import type { MailConfig, MailerConfig, MailAddress } from './contracts/MailConfig.ts'
+import { DEFAULT_CONFIG } from './contracts/MailConfig.ts'
+import { Message } from './Message.ts'
+import { PendingMail } from './PendingMail.ts'
+import { MailError } from './errors/MailError.ts'
+
+import { ArrayTransport } from './drivers/ArrayTransport.ts'
+import { LogTransport } from './drivers/LogTransport.ts'
+import { SmtpTransport } from './drivers/SmtpTransport.ts'
+import { ResendTransport } from './drivers/ResendTransport.ts'
+import { SendGridTransport } from './drivers/SendGridTransport.ts'
+import { MailgunTransport } from './drivers/MailgunTransport.ts'
+import { PostmarkTransport } from './drivers/PostmarkTransport.ts'
+import { SesTransport } from './drivers/SesTransport.ts'
+
+/**
+ * MailManager — driver manager for mail transports.
+ *
+ * @example
+ *   const manager = new MailManager(config)
+ *   await manager.to('user@example.com').send(new WelcomeEmail(user))
+ *   await manager.driver('resend').send(message)
+ */
+export class MailManager {
+  private config: MailConfig
+  private drivers = new Map<string, MailTransport>()
+  private customDrivers = new Map<string, () => MailTransport>()
+
+  constructor(config?: Partial<MailConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+  }
+
+  /** Get the default from address */
+  getFrom(): MailAddress {
+    return this.config.from
+  }
+
+  /** Get or create a transport driver by name */
+  driver(name?: string): MailTransport {
+    const driverName = name ?? this.config.default
+
+    if (this.drivers.has(driverName)) {
+      return this.drivers.get(driverName)!
+    }
+
+    const transport = this.createDriver(driverName)
+    this.drivers.set(driverName, transport)
+    return transport
+  }
+
+  /** Alias for driver() */
+  mailer(name?: string): MailTransport {
+    return this.driver(name)
+  }
+
+  /** Start a fluent pending mail */
+  to(address: string | MailAddress | (string | MailAddress)[]): PendingMail {
+    return new PendingMail(this).to(address)
+  }
+
+  /** Send a mailable using the default transport */
+  async send(mailable: import('./Mailable.ts').Mailable): Promise<{ id: string }> {
+    return new PendingMail(this).send(mailable)
+  }
+
+  /** Register a custom driver factory */
+  extend(name: string, factory: () => MailTransport): void {
+    this.customDrivers.set(name, factory)
+    this.drivers.delete(name) // clear cached instance
+  }
+
+  /** Get the default driver name */
+  getDefaultDriver(): string {
+    return this.config.default
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  private createDriver(name: string): MailTransport {
+    // Check custom drivers first
+    const customFactory = this.customDrivers.get(name)
+    if (customFactory) return customFactory()
+
+    const mailerConfig = this.config.mailers[name]
+    if (!mailerConfig) {
+      throw new MailError(`Mail driver "${name}" is not configured.`, { available: Object.keys(this.config.mailers) })
+    }
+
+    return this.resolveDriver(mailerConfig)
+  }
+
+  private resolveDriver(config: MailerConfig): MailTransport {
+    switch (config.driver) {
+      case 'smtp':
+        return new SmtpTransport(config)
+      case 'resend':
+        return new ResendTransport(config)
+      case 'sendgrid':
+        return new SendGridTransport(config)
+      case 'mailgun':
+        return new MailgunTransport(config)
+      case 'postmark':
+        return new PostmarkTransport(config)
+      case 'ses':
+        return new SesTransport(config)
+      case 'log':
+        return new LogTransport()
+      case 'array':
+        return new ArrayTransport()
+      default:
+        throw new MailError(`Unsupported mail driver: "${(config as any).driver}"`)
+    }
+  }
+}

package/src/MailServiceProvider.ts

@@ -0,0 +1,14 @@
+import { ServiceProvider, ConfigRepository } from '@mantiq/core'
+import { MailManager } from './MailManager.ts'
+import { MAIL_MANAGER } from './helpers/mail.ts'
+import type { MailConfig } from './contracts/MailConfig.ts'
+import { DEFAULT_CONFIG } from './contracts/MailConfig.ts'
+
+export class MailServiceProvider extends ServiceProvider {
+  override register(): void {
+    const config = this.app.make(ConfigRepository).get<MailConfig>('mail', DEFAULT_CONFIG)
+
+    this.app.singleton(MailManager, () => new MailManager(config))
+    this.app.alias(MailManager, MAIL_MANAGER)
+  }
+}

package/src/Mailable.ts

@@ -0,0 +1,148 @@
+import type { MailAddress } from './contracts/MailConfig.ts'
+import { Message, type Attachment } from './Message.ts'
+import { renderMarkdown } from './markdown/MarkdownRenderer.ts'
+
+/**
+ * Base class for all mailables. Users extend this and implement build().
+ *
+ * @example
+ *   class WelcomeEmail extends Mailable {
+ *     constructor(private user: { name: string }) { super() }
+ *
+ *     build() {
+ *       this.setSubject('Welcome!')
+ *       this.markdown(`# Hi ${this.user.name}!\n\nWelcome aboard.`)
+ *     }
+ *   }
+ */
+export abstract class Mailable {
+  private _to: MailAddress[] = []
+  private _cc: MailAddress[] = []
+  private _bcc: MailAddress[] = []
+  private _replyTo: MailAddress[] = []
+  private _subject = ''
+  private _html: string | null = null
+  private _text: string | null = null
+  private _markdown: string | null = null
+  private _attachments: Attachment[] = []
+  private _headers: Record<string, string> = {}
+  private _appName = 'MantiqJS'
+
+  abstract build(): void
+
+  // ── Recipients (can be set before send) ──────────────────────────────────
+
+  to(address: string | MailAddress | (string | MailAddress)[]): this {
+    const addrs = Array.isArray(address) ? address : [address]
+    this._to.push(...addrs.map(a => typeof a === 'string' ? { address: a } : a))
+    return this
+  }
+
+  cc(address: string | MailAddress | (string | MailAddress)[]): this {
+    const addrs = Array.isArray(address) ? address : [address]
+    this._cc.push(...addrs.map(a => typeof a === 'string' ? { address: a } : a))
+    return this
+  }
+
+  bcc(address: string | MailAddress | (string | MailAddress)[]): this {
+    const addrs = Array.isArray(address) ? address : [address]
+    this._bcc.push(...addrs.map(a => typeof a === 'string' ? { address: a } : a))
+    return this
+  }
+
+  replyTo(address: string | MailAddress): this {
+    this._replyTo.push(typeof address === 'string' ? { address } : address)
+    return this
+  }
+
+  // ── Content ───────────────────────────────────────────────────────────────
+
+  protected setSubject(subject: string): this {
+    this._subject = subject
+    return this
+  }
+
+  protected html(content: string): this {
+    this._html = content
+    this._markdown = null
+    return this
+  }
+
+  protected text(content: string): this {
+    this._text = content
+    return this
+  }
+
+  protected markdown(content: string): this {
+    this._markdown = content
+    this._html = null
+    return this
+  }
+
+  protected attach(filename: string, content: Uint8Array | string, contentType?: string): this {
+    this._attachments.push({ filename, content, contentType })
+    return this
+  }
+
+  protected header(key: string, value: string): this {
+    this._headers[key] = value
+    return this
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  /** Set the app name for email template header. Called by MailManager. */
+  setAppName(name: string): void {
+    this._appName = name
+  }
+
+  /** Convert to a Message ready for transport. Call build() first. */
+  toMessage(from: MailAddress): Message {
+    this.build()
+
+    const msg = new Message()
+    msg.setFrom(from)
+    msg.subject = this._subject
+
+    for (const addr of this._to) msg.addTo(addr)
+    for (const addr of this._cc) msg.addCc(addr)
+    for (const addr of this._bcc) msg.addBcc(addr)
+    for (const addr of this._replyTo) msg.addReplyTo(addr)
+
+    if (this._markdown) {
+      msg.html = renderMarkdown(this._markdown, { appName: this._appName })
+      // Generate plain text by stripping tags
+      msg.text = this._text ?? stripHtml(this._markdown)
+    } else if (this._html) {
+      msg.html = this._html
+      msg.text = this._text
+    } else if (this._text) {
+      msg.text = this._text
+    }
+
+    msg.attachments = [...this._attachments]
+    msg.headers = { ...this._headers }
+
+    return msg
+  }
+
+  /** Get recipients set on this mailable */
+  getTo(): MailAddress[] { return this._to }
+  getCc(): MailAddress[] { return this._cc }
+  getBcc(): MailAddress[] { return this._bcc }
+  getSubject(): string { return this._subject }
+}
+
+function stripHtml(md: string): string {
+  // Remove markdown syntax to produce plain text
+  return md
+    .replace(/\[button[^\]]*\](.*?)\[\/button\]/g, '$1')
+    .replace(/\[panel\]([\s\S]*?)\[\/panel\]/g, '$1')
+    .replace(/#{1,6}\s+/g, '')
+    .replace(/\*\*(.*?)\*\*/g, '$1')
+    .replace(/\*(.*?)\*/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/>\s*/gm, '')
+    .trim()
+}

package/src/Message.ts

@@ -0,0 +1,80 @@
+import type { MailAddress } from './contracts/MailConfig.ts'
+
+export interface Attachment {
+  filename: string
+  content: Uint8Array | string
+  contentType?: string | undefined
+}
+
+export class Message {
+  from: MailAddress = { address: '' }
+  to: MailAddress[] = []
+  cc: MailAddress[] = []
+  bcc: MailAddress[] = []
+  replyTo: MailAddress[] = []
+  subject = ''
+  html: string | null = null
+  text: string | null = null
+  attachments: Attachment[] = []
+  headers: Record<string, string> = {}
+
+  setFrom(address: string | MailAddress): this {
+    this.from = typeof address === 'string' ? { address } : address
+    return this
+  }
+
+  addTo(address: string | MailAddress): this {
+    this.to.push(typeof address === 'string' ? { address } : address)
+    return this
+  }
+
+  addCc(address: string | MailAddress): this {
+    this.cc.push(typeof address === 'string' ? { address } : address)
+    return this
+  }
+
+  addBcc(address: string | MailAddress): this {
+    this.bcc.push(typeof address === 'string' ? { address } : address)
+    return this
+  }
+
+  addReplyTo(address: string | MailAddress): this {
+    this.replyTo.push(typeof address === 'string' ? { address } : address)
+    return this
+  }
+
+  setSubject(subject: string): this {
+    this.subject = subject
+    return this
+  }
+
+  setHtml(html: string): this {
+    this.html = html
+    return this
+  }
+
+  setText(text: string): this {
+    this.text = text
+    return this
+  }
+
+  addAttachment(filename: string, content: Uint8Array | string, contentType?: string): this {
+    this.attachments.push({ filename, content, contentType })
+    return this
+  }
+
+  setHeader(key: string, value: string): this {
+    this.headers[key] = value
+    return this
+  }
+
+  /** Format address for SMTP/API: "Name <email>" or just "email" */
+  static formatAddress(addr: MailAddress): string {
+    return addr.name ? `${addr.name} <${addr.address}>` : addr.address
+  }
+
+  /** Format address list */
+  static formatAddresses(addrs: MailAddress[]): string {
+    return addrs.map(Message.formatAddress).join(', ')
+  }
+}

package/src/PendingMail.ts

@@ -0,0 +1,71 @@
+import type { MailAddress } from './contracts/MailConfig.ts'
+import type { MailManager } from './MailManager.ts'
+import type { Mailable } from './Mailable.ts'
+
+/**
+ * Fluent builder for sending mail.
+ *
+ * @example
+ *   await mail().to('user@example.com').send(new WelcomeEmail(user))
+ *   await mail().to(['a@b.com', 'c@d.com']).cc('admin@b.com').queue(new InvoiceEmail(order))
+ */
+export class PendingMail {
+  private _to: MailAddress[] = []
+  private _cc: MailAddress[] = []
+  private _bcc: MailAddress[] = []
+  private _mailer: string | undefined
+
+  constructor(private manager: MailManager) {}
+
+  to(address: string | MailAddress | (string | MailAddress)[]): this {
+    const addrs = Array.isArray(address) ? address : [address]
+    this._to.push(...addrs.map(a => typeof a === 'string' ? { address: a } : a))
+    return this
+  }
+
+  cc(address: string | MailAddress | (string | MailAddress)[]): this {
+    const addrs = Array.isArray(address) ? address : [address]
+    this._cc.push(...addrs.map(a => typeof a === 'string' ? { address: a } : a))
+    return this
+  }
+
+  bcc(address: string | MailAddress | (string | MailAddress)[]): this {
+    const addrs = Array.isArray(address) ? address : [address]
+    this._bcc.push(...addrs.map(a => typeof a === 'string' ? { address: a } : a))
+    return this
+  }
+
+  /** Use a specific mailer instead of default */
+  via(mailer: string): this {
+    this._mailer = mailer
+    return this
+  }
+
+  /** Send the mailable now */
+  async send(mailable: Mailable): Promise<{ id: string }> {
+    // Apply pending recipients to the mailable
+    if (this._to.length) mailable.to(this._to)
+    if (this._cc.length) mailable.cc(this._cc)
+    if (this._bcc.length) mailable.bcc(this._bcc)
+
+    const message = mailable.toMessage(this.manager.getFrom())
+    return this.manager.driver(this._mailer).send(message)
+  }
+
+  /** Queue the mailable for async sending (requires @mantiq/queue) */
+  async queue(mailable: Mailable): Promise<void> {
+    // Apply pending recipients
+    if (this._to.length) mailable.to(this._to)
+    if (this._cc.length) mailable.cc(this._cc)
+    if (this._bcc.length) mailable.bcc(this._bcc)
+
+    try {
+      const { dispatch } = await import('@mantiq/queue')
+      const { SendMailJob } = await import('./jobs/SendMailJob.ts')
+      await dispatch(new SendMailJob(mailable, this._mailer))
+    } catch {
+      // Queue not installed — send synchronously
+      await this.send(mailable)
+    }
+  }
+}

package/src/commands/MakeMailCommand.ts

@@ -0,0 +1,55 @@
+import { GeneratorCommand } from '@mantiq/cli'
+import type { ParsedArgs } from '@mantiq/cli'
+
+export class MakeMailCommand extends GeneratorCommand {
+  override name = 'make:mail'
+  override description = 'Create a new mailable class'
+  override usage = 'make:mail <name> [--markdown]'
+
+  override directory() { return 'app/Mail' }
+  override suffix() { return '' }
+
+  override stub(name: string, args: ParsedArgs): string {
+    const className = name
+    const useMarkdown = !!args.flags['markdown']
+
+    if (useMarkdown) {
+      return `import { Mailable } from '@mantiq/mail'
+
+export class ${className} extends Mailable {
+  constructor(private data: Record<string, any> = {}) { super() }
+
+  build() {
+    this.setSubject('${className}')
+    this.markdown(\`
+# Hello!
+
+This is the **${className}** mailable.
+
+[button url="/dashboard"]View Dashboard[/button]
+
+[panel]
+If you have any questions, reply to this email.
+[/panel]
+    \`)
+  }
+}
+`
+    }
+
+    return `import { Mailable } from '@mantiq/mail'
+
+export class ${className} extends Mailable {
+  constructor(private data: Record<string, any> = {}) { super() }
+
+  build() {
+    this.setSubject('${className}')
+    this.html(\`
+      <h1>Hello!</h1>
+      <p>This is the <strong>${className}</strong> mailable.</p>
+    \`)
+  }
+}
+`
+  }
+}

package/src/contracts/MailConfig.ts

@@ -0,0 +1,28 @@
+export interface MailAddress {
+  address: string
+  name?: string
+}
+
+export type MailerConfig =
+  | { driver: 'smtp'; host: string; port: number; username?: string; password?: string; encryption?: 'tls' | 'starttls' | 'none' }
+  | { driver: 'resend'; apiKey: string }
+  | { driver: 'sendgrid'; apiKey: string }
+  | { driver: 'mailgun'; apiKey: string; domain: string; region?: 'us' | 'eu' }
+  | { driver: 'postmark'; serverToken: string }
+  | { driver: 'ses'; region: string; accessKeyId: string; secretAccessKey: string }
+  | { driver: 'log' }
+  | { driver: 'array' }
+
+export interface MailConfig {
+  default: string
+  from: MailAddress
+  mailers: Record<string, MailerConfig>
+}
+
+export const DEFAULT_CONFIG: MailConfig = {
+  default: 'log',
+  from: { address: 'hello@example.com', name: 'MantiqJS' },
+  mailers: {
+    log: { driver: 'log' },
+  },
+}

package/src/contracts/Transport.ts

@@ -0,0 +1,5 @@
+import type { Message } from '../Message.ts'
+
+export interface MailTransport {
+  send(message: Message): Promise<{ id: string }>
+}

package/src/drivers/ArrayTransport.ts

@@ -0,0 +1,17 @@
+import type { MailTransport } from '../contracts/Transport.ts'
+import type { Message } from '../Message.ts'
+
+export class ArrayTransport implements MailTransport {
+  sent: Message[] = []
+
+  async send(message: Message): Promise<{ id: string }> {
+    const id = crypto.randomUUID()
+    this.sent.push(message)
+    return { id }
+  }
+
+  /** Clear all stored messages */
+  flush(): void {
+    this.sent = []
+  }
+}

package/src/drivers/LogTransport.ts

@@ -0,0 +1,22 @@
+import type { MailTransport } from '../contracts/Transport.ts'
+import { Message } from '../Message.ts'
+
+export class LogTransport implements MailTransport {
+  async send(message: Message): Promise<{ id: string }> {
+    const id = crypto.randomUUID()
+
+    const to = Message.formatAddresses(message.to)
+    const subject = message.subject
+    const preview = message.text
+      ? message.text.substring(0, 200)
+      : message.html
+        ? message.html.replace(/<[^>]*>/g, '').substring(0, 200)
+        : '(no body)'
+
+    console.log(
+      `[Mail] To: ${to} | Subject: ${subject} | Preview: ${preview}`,
+    )
+
+    return { id }
+  }
+}

package/src/drivers/MailgunTransport.ts

@@ -0,0 +1,94 @@
+import type { MailTransport } from '../contracts/Transport.ts'
+import { Message } from '../Message.ts'
+import { MailError } from '../errors/MailError.ts'
+
+export interface MailgunConfig {
+  apiKey: string
+  domain: string
+  region?: 'us' | 'eu'
+}
+
+export class MailgunTransport implements MailTransport {
+  private config: MailgunConfig
+
+  constructor(config: MailgunConfig) {
+    this.config = config
+  }
+
+  async send(message: Message): Promise<{ id: string }> {
+    const baseUrl = this.config.region === 'eu'
+      ? 'https://api.eu.mailgun.net'
+      : 'https://api.mailgun.net'
+
+    const url = `${baseUrl}/v3/${this.config.domain}/messages`
+
+    const formData = new FormData()
+
+    formData.append('from', Message.formatAddress(message.from))
+
+    for (const addr of message.to) {
+      formData.append('to', Message.formatAddress(addr))
+    }
+
+    for (const addr of message.cc) {
+      formData.append('cc', Message.formatAddress(addr))
+    }
+
+    for (const addr of message.bcc) {
+      formData.append('bcc', Message.formatAddress(addr))
+    }
+
+    formData.append('subject', message.subject)
+
+    if (message.html !== null) {
+      formData.append('html', message.html)
+    }
+
+    if (message.text !== null) {
+      formData.append('text', message.text)
+    }
+
+    if (message.replyTo.length > 0) {
+      formData.append('h:Reply-To', Message.formatAddresses(message.replyTo))
+    }
+
+    // Custom headers
+    for (const [key, value] of Object.entries(message.headers)) {
+      formData.append(`h:${key}`, value)
+    }
+
+    // Attachments
+    for (const attachment of message.attachments) {
+      const content = typeof attachment.content === 'string'
+        ? new Blob([attachment.content], { type: attachment.contentType || 'application/octet-stream' })
+        : new Blob([attachment.content], { type: attachment.contentType || 'application/octet-stream' })
+
+      formData.append('attachment', content, attachment.filename)
+    }
+
+    const authString = Buffer.from(`api:${this.config.apiKey}`).toString('base64')
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Basic ${authString}`,
+      },
+      body: formData,
+    })
+
+    if (!response.ok) {
+      const errorBody = await response.text()
+      throw new MailError(`Mailgun API error: ${response.status} ${response.statusText}`, {
+        status: response.status,
+        body: errorBody,
+      })
+    }
+
+    const result = await response.json() as { id: string; message: string }
+
+    // Mailgun returns id wrapped in angle brackets like "<id@domain>"
+    const id = result.id ? result.id.replace(/[<>]/g, '') : crypto.randomUUID()
+
+    return { id }
+  }
+}