@mantiq/mail 0.1.2 → 0.2.0

package/src/drivers/SmtpTransport.ts

@@ -0,0 +1,344 @@
+import type { MailTransport } from '../contracts/Transport.ts'
+import { Message, type Attachment } from '../Message.ts'
+import { MailError } from '../errors/MailError.ts'
+
+export interface SmtpConfig {
+  host: string
+  port: number
+  username?: string
+  password?: string
+  encryption?: 'tls' | 'starttls' | 'none'
+}
+
+export class SmtpTransport implements MailTransport {
+  private config: SmtpConfig
+
+  constructor(config: SmtpConfig) {
+    this.config = config
+  }
+
+  async send(message: Message): Promise<{ id: string }> {
+    const { host, port, username, password, encryption = 'none' } = this.config
+
+    let socket: ReturnType<typeof Bun.connect> extends Promise<infer T> ? T : never
+    let responseBuffer = ''
+    let responseResolve: ((value: string) => void) | null = null
+
+    const waitForResponse = (): Promise<string> => {
+      return new Promise((resolve) => {
+        if (responseBuffer.length > 0) {
+          // Check if we have a complete response
+          const complete = this.extractCompleteResponse(responseBuffer)
+          if (complete) {
+            responseBuffer = responseBuffer.slice(complete.length)
+            resolve(complete)
+            return
+          }
+        }
+        responseResolve = resolve
+      })
+    }
+
+    const handleData = (data: Buffer) => {
+      responseBuffer += data.toString()
+      if (responseResolve) {
+        const complete = this.extractCompleteResponse(responseBuffer)
+        if (complete) {
+          responseBuffer = responseBuffer.slice(complete.length)
+          const resolve = responseResolve
+          responseResolve = null
+          resolve(complete)
+        }
+      }
+    }
+
+    try {
+      const useTls = encryption === 'tls'
+
+      const socketOptions = {
+        hostname: host,
+        port,
+        socket: {
+          data(_socket: any, data: Buffer) {
+            handleData(data)
+          },
+          error(_socket: any, error: Error) {
+            throw new MailError(`SMTP socket error: ${error.message}`)
+          },
+          close() {
+            // Connection closed
+          },
+          open() {
+            // Connection opened
+          },
+        },
+      } as any
+
+      if (useTls) {
+        socketOptions.tls = true
+      }
+
+      socket = await Bun.connect(socketOptions)
+
+      // Read greeting
+      const greeting = await waitForResponse()
+      this.assertCode(greeting, 220, 'greeting')
+
+      // EHLO
+      socket.write(`EHLO localhost\r\n`)
+      const ehlo = await waitForResponse()
+      this.assertCode(ehlo, 250, 'EHLO')
+
+      // STARTTLS if needed
+      if (encryption === 'starttls') {
+        socket.write(`STARTTLS\r\n`)
+        const starttls = await waitForResponse()
+        this.assertCode(starttls, 220, 'STARTTLS')
+
+        // Upgrade to TLS — Bun's socket supports upgradeToTLS (if available)
+        // For environments where upgradeToTLS isn't available, we rely on the
+        // initial TLS connection (encryption: 'tls') instead.
+        // @ts-expect-error — upgradeToTLS may or may not exist on the socket
+        if (typeof socket.upgradeToTLS === 'function') {
+          // @ts-expect-error
+          socket = await socket.upgradeToTLS()
+        }
+
+        // Re-EHLO after STARTTLS
+        socket.write(`EHLO localhost\r\n`)
+        const ehlo2 = await waitForResponse()
+        this.assertCode(ehlo2, 250, 'EHLO after STARTTLS')
+      }
+
+      // AUTH if credentials provided
+      if (username && password) {
+        // Try AUTH PLAIN first
+        const credentials = Buffer.from(`\0${username}\0${password}`).toString('base64')
+        socket.write(`AUTH PLAIN ${credentials}\r\n`)
+        const authResp = await waitForResponse()
+
+        if (!authResp.startsWith('235')) {
+          // Fall back to AUTH LOGIN
+          socket.write(`AUTH LOGIN\r\n`)
+          const loginPrompt = await waitForResponse()
+          this.assertCode(loginPrompt, 334, 'AUTH LOGIN')
+
+          socket.write(`${Buffer.from(username).toString('base64')}\r\n`)
+          const userPrompt = await waitForResponse()
+          this.assertCode(userPrompt, 334, 'AUTH LOGIN username')
+
+          socket.write(`${Buffer.from(password).toString('base64')}\r\n`)
+          const passResp = await waitForResponse()
+          this.assertCode(passResp, 235, 'AUTH LOGIN password')
+        }
+      }
+
+      // MAIL FROM
+      socket.write(`MAIL FROM:<${message.from.address}>\r\n`)
+      const mailFrom = await waitForResponse()
+      this.assertCode(mailFrom, 250, 'MAIL FROM')
+
+      // RCPT TO — all recipients
+      const allRecipients = [...message.to, ...message.cc, ...message.bcc]
+      for (const recipient of allRecipients) {
+        socket.write(`RCPT TO:<${recipient.address}>\r\n`)
+        const rcpt = await waitForResponse()
+        this.assertCode(rcpt, 250, 'RCPT TO')
+      }
+
+      // DATA
+      socket.write(`DATA\r\n`)
+      const dataResp = await waitForResponse()
+      this.assertCode(dataResp, 354, 'DATA')
+
+      // Build RFC 2822 message
+      const messageId = `<${crypto.randomUUID()}@${host}>`
+      const rawMessage = this.buildRawMessage(message, messageId)
+
+      // Send the message body, ending with \r\n.\r\n
+      socket.write(rawMessage)
+      socket.write(`\r\n.\r\n`)
+      const sendResp = await waitForResponse()
+      this.assertCode(sendResp, 250, 'message send')
+
+      // Extract message ID from server response if available
+      const serverIdMatch = sendResp.match(/queued as ([^\s>]+)/i)
+      const id = serverIdMatch?.[1] ?? messageId.replace(/[<>]/g, '')
+
+      // QUIT
+      socket.write(`QUIT\r\n`)
+      // Don't wait for QUIT response — some servers close immediately
+
+      socket.end()
+
+      return { id }
+    } catch (error) {
+      if (error instanceof MailError) throw error
+      throw new MailError(`SMTP transport error: ${(error as Error).message}`, {
+        host,
+        port,
+      })
+    }
+  }
+
+  /**
+   * Extract a complete SMTP response from the buffer.
+   * Multi-line responses use "XXX-" continuation and end with "XXX ".
+   */
+  private extractCompleteResponse(buffer: string): string | null {
+    const lines = buffer.split('\r\n')
+    let result = ''
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i] as string
+      if (line === '' && i === lines.length - 1) break // trailing empty from split
+
+      result += line + '\r\n'
+
+      // A line like "250 OK" (code + space) signals the final line
+      if (/^\d{3} /.test(line)) {
+        return result
+      }
+      // A line like "250-..." means continuation, keep reading
+      if (/^\d{3}-/.test(line)) {
+        continue
+      }
+    }
+
+    return null
+  }
+
+  private assertCode(response: string, expected: number, step: string): void {
+    const code = parseInt(response.substring(0, 3), 10)
+    if (code !== expected) {
+      throw new MailError(
+        `SMTP ${step} failed: expected ${expected}, got ${code}`,
+        { response: response.trim() },
+      )
+    }
+  }
+
+  private buildRawMessage(message: Message, messageId: string): string {
+    const lines: string[] = []
+    const boundary = `----=_Part_${crypto.randomUUID().replace(/-/g, '')}`
+
+    // Headers
+    lines.push(`Message-ID: ${messageId}`)
+    lines.push(`Date: ${new Date().toUTCString()}`)
+    lines.push(`From: ${Message.formatAddress(message.from)}`)
+    lines.push(`To: ${Message.formatAddresses(message.to)}`)
+
+    if (message.cc.length > 0) {
+      lines.push(`Cc: ${Message.formatAddresses(message.cc)}`)
+    }
+
+    if (message.replyTo.length > 0) {
+      lines.push(`Reply-To: ${Message.formatAddresses(message.replyTo)}`)
+    }
+
+    lines.push(`Subject: ${message.subject}`)
+    lines.push(`MIME-Version: 1.0`)
+
+    // Custom headers
+    for (const [key, value] of Object.entries(message.headers)) {
+      lines.push(`${key}: ${value}`)
+    }
+
+    const hasAttachments = message.attachments.length > 0
+    const hasMultipleBodies = message.html !== null && message.text !== null
+
+    if (hasAttachments) {
+      lines.push(`Content-Type: multipart/mixed; boundary="${boundary}"`)
+      lines.push('')
+      lines.push(`--${boundary}`)
+
+      if (hasMultipleBodies) {
+        const altBoundary = `----=_Alt_${crypto.randomUUID().replace(/-/g, '')}`
+        lines.push(`Content-Type: multipart/alternative; boundary="${altBoundary}"`)
+        lines.push('')
+
+        if (message.text !== null) {
+          lines.push(`--${altBoundary}`)
+          lines.push(`Content-Type: text/plain; charset=utf-8`)
+          lines.push(`Content-Transfer-Encoding: 7bit`)
+          lines.push('')
+          lines.push(message.text)
+        }
+
+        if (message.html !== null) {
+          lines.push(`--${altBoundary}`)
+          lines.push(`Content-Type: text/html; charset=utf-8`)
+          lines.push(`Content-Transfer-Encoding: 7bit`)
+          lines.push('')
+          lines.push(message.html)
+        }
+
+        lines.push(`--${altBoundary}--`)
+      } else if (message.html !== null) {
+        lines.push(`Content-Type: text/html; charset=utf-8`)
+        lines.push(`Content-Transfer-Encoding: 7bit`)
+        lines.push('')
+        lines.push(message.html)
+      } else if (message.text !== null) {
+        lines.push(`Content-Type: text/plain; charset=utf-8`)
+        lines.push(`Content-Transfer-Encoding: 7bit`)
+        lines.push('')
+        lines.push(message.text)
+      }
+
+      // Attachments
+      for (const attachment of message.attachments) {
+        lines.push(`--${boundary}`)
+        const contentType = attachment.contentType || 'application/octet-stream'
+        lines.push(`Content-Type: ${contentType}; name="${attachment.filename}"`)
+        lines.push(`Content-Disposition: attachment; filename="${attachment.filename}"`)
+        lines.push(`Content-Transfer-Encoding: base64`)
+        lines.push('')
+        lines.push(this.encodeAttachment(attachment))
+      }
+
+      lines.push(`--${boundary}--`)
+    } else if (hasMultipleBodies) {
+      const altBoundary = `----=_Alt_${crypto.randomUUID().replace(/-/g, '')}`
+      lines.push(`Content-Type: multipart/alternative; boundary="${altBoundary}"`)
+      lines.push('')
+
+      if (message.text !== null) {
+        lines.push(`--${altBoundary}`)
+        lines.push(`Content-Type: text/plain; charset=utf-8`)
+        lines.push(`Content-Transfer-Encoding: 7bit`)
+        lines.push('')
+        lines.push(message.text)
+      }
+
+      if (message.html !== null) {
+        lines.push(`--${altBoundary}`)
+        lines.push(`Content-Type: text/html; charset=utf-8`)
+        lines.push(`Content-Transfer-Encoding: 7bit`)
+        lines.push('')
+        lines.push(message.html)
+      }
+
+      lines.push(`--${altBoundary}--`)
+    } else if (message.html !== null) {
+      lines.push(`Content-Type: text/html; charset=utf-8`)
+      lines.push(`Content-Transfer-Encoding: 7bit`)
+      lines.push('')
+      lines.push(message.html)
+    } else {
+      lines.push(`Content-Type: text/plain; charset=utf-8`)
+      lines.push(`Content-Transfer-Encoding: 7bit`)
+      lines.push('')
+      lines.push(message.text || '')
+    }
+
+    return lines.join('\r\n')
+  }
+
+  private encodeAttachment(attachment: Attachment): string {
+    if (typeof attachment.content === 'string') {
+      return Buffer.from(attachment.content).toString('base64')
+    }
+    return Buffer.from(attachment.content).toString('base64')
+  }
+}

package/src/errors/MailError.ts

@@ -0,0 +1,7 @@
+import { MantiqError } from '@mantiq/core'
+
+export class MailError extends MantiqError {
+  constructor(message: string, context?: Record<string, any>) {
+    super(message, context)
+  }
+}

package/src/helpers/mail.ts

@@ -0,0 +1,15 @@
+import { Application } from '@mantiq/core'
+import type { MailManager } from '../MailManager.ts'
+import type { PendingMail } from '../PendingMail.ts'
+
+export const MAIL_MANAGER = Symbol('MailManager')
+
+/** Get the mail manager instance */
+export function mail(): MailManager
+/** Start a pending mail to the given address */
+export function mail(to: string): PendingMail
+export function mail(to?: string): MailManager | PendingMail {
+  const manager = Application.getInstance().make<MailManager>(MAIL_MANAGER)
+  if (to === undefined) return manager
+  return manager.to(to)
+}

package/src/index.ts

@@ -1 +1,39 @@
-// @mantiq/mail — public API exports
+// ── Contracts ────────────────────────────────────────────────────────────────
+export type { MailTransport } from './contracts/Transport.ts'
+export type { MailConfig, MailerConfig, MailAddress } from './contracts/MailConfig.ts'
+export { DEFAULT_CONFIG } from './contracts/MailConfig.ts'
+
+// ── Core ─────────────────────────────────────────────────────────────────────
+export { Message, type Attachment } from './Message.ts'
+export { Mailable } from './Mailable.ts'
+export { MailManager } from './MailManager.ts'
+export { PendingMail } from './PendingMail.ts'
+
+// ── Drivers ──────────────────────────────────────────────────────────────────
+export { SmtpTransport } from './drivers/SmtpTransport.ts'
+export { ResendTransport } from './drivers/ResendTransport.ts'
+export { SendGridTransport } from './drivers/SendGridTransport.ts'
+export { MailgunTransport } from './drivers/MailgunTransport.ts'
+export { PostmarkTransport } from './drivers/PostmarkTransport.ts'
+export { SesTransport } from './drivers/SesTransport.ts'
+export { LogTransport } from './drivers/LogTransport.ts'
+export { ArrayTransport } from './drivers/ArrayTransport.ts'
+
+// ── Markdown ─────────────────────────────────────────────────────────────────
+export { renderMarkdown } from './markdown/MarkdownRenderer.ts'
+export { wrapInLayout, renderButton, renderPanel, renderTable } from './markdown/theme.ts'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+export { mail, MAIL_MANAGER } from './helpers/mail.ts'
+
+// ── Service Provider ─────────────────────────────────────────────────────────
+export { MailServiceProvider } from './MailServiceProvider.ts'
+
+// ── Testing ──────────────────────────────────────────────────────────────────
+export { MailFake } from './testing/MailFake.ts'
+
+// ── Errors ───────────────────────────────────────────────────────────────────
+export { MailError } from './errors/MailError.ts'
+
+// ── Commands ─────────────────────────────────────────────────────────────────
+export { MakeMailCommand } from './commands/MakeMailCommand.ts'

package/src/jobs/SendMailJob.ts

@@ -0,0 +1,25 @@
+import { Job } from '@mantiq/queue'
+import type { Mailable } from '../Mailable.ts'
+
+/**
+ * Queued mail job — sends a mailable via the mail manager.
+ * Dispatched by PendingMail.queue().
+ */
+export class SendMailJob extends Job {
+  override name = 'mail:send'
+  override tries = 3
+
+  constructor(
+    private mailable: Mailable,
+    private mailer?: string,
+  ) {
+    super()
+  }
+
+  override async handle(): Promise<void> {
+    const { mail } = await import('../helpers/mail.ts')
+    const manager = mail()
+    const message = this.mailable.toMessage(manager.getFrom())
+    await manager.driver(this.mailer).send(message)
+  }
+}

package/src/markdown/MarkdownRenderer.ts

@@ -0,0 +1,136 @@
+import { wrapInLayout, renderButton, renderPanel, type ThemeOptions } from './theme.ts'
+
+/**
+ * Converts markdown-like content to styled HTML email.
+ *
+ * Supports: headings, paragraphs, bold, italic, links, lists, code,
+ * blockquotes, horizontal rules, and custom components:
+ *   [button url="..."]text[/button]
+ *   [panel]content[/panel]
+ */
+export function renderMarkdown(content: string, options: ThemeOptions = {}): string {
+  const bodyHtml = markdownToHtml(content.trim())
+  return wrapInLayout(bodyHtml, options)
+}
+
+function markdownToHtml(md: string): string {
+  let html = ''
+  const lines = md.split('\n')
+  let i = 0
+  let inList: 'ul' | 'ol' | null = null
+
+  while (i < lines.length) {
+    const line = lines[i]!
+    const trimmed = line.trim()
+
+    // Empty line — close list if open
+    if (!trimmed) {
+      if (inList) { html += `</${inList}>` ; inList = null }
+      i++
+      continue
+    }
+
+    // Custom components
+    const buttonMatch = trimmed.match(/^\[button\s+url="([^"]+)"\](.*?)\[\/button\]$/)
+    if (buttonMatch) {
+      if (inList) { html += `</${inList}>`; inList = null }
+      html += renderButton(buttonMatch[1]!, buttonMatch[2]!)
+      i++
+      continue
+    }
+
+    // Panel block (multi-line)
+    if (trimmed === '[panel]') {
+      if (inList) { html += `</${inList}>`; inList = null }
+      const panelLines: string[] = []
+      i++
+      while (i < lines.length && lines[i]!.trim() !== '[/panel]') {
+        panelLines.push(lines[i]!)
+        i++
+      }
+      i++ // skip [/panel]
+      html += renderPanel(inlineFormatting(panelLines.join('<br>')))
+      continue
+    }
+
+    // Headings
+    const headingMatch = trimmed.match(/^(#{1,6})\s+(.+)$/)
+    if (headingMatch) {
+      if (inList) { html += `</${inList}>`; inList = null }
+      const level = headingMatch[1]!.length
+      const text = inlineFormatting(headingMatch[2]!)
+      const sizes: Record<number, string> = { 1: '24px', 2: '20px', 3: '17px', 4: '15px', 5: '14px', 6: '13px' }
+      const mt = level <= 2 ? '28px' : '20px'
+      html += `<h${level} class="email-text" style="margin:${mt} 0 8px;font-size:${sizes[level]};font-weight:700;line-height:1.3;color:#1a1a1a;">${text}</h${level}>`
+      i++
+      continue
+    }
+
+    // Horizontal rule
+    if (/^(-{3,}|\*{3,}|_{3,})$/.test(trimmed)) {
+      if (inList) { html += `</${inList}>`; inList = null }
+      html += `<hr class="email-hr" style="border:none;border-top:1px solid #e5e7eb;margin:24px 0;">`
+      i++
+      continue
+    }
+
+    // Blockquote
+    if (trimmed.startsWith('> ')) {
+      if (inList) { html += `</${inList}>`; inList = null }
+      const quoteLines: string[] = []
+      while (i < lines.length && lines[i]!.trim().startsWith('> ')) {
+        quoteLines.push(lines[i]!.trim().slice(2))
+        i++
+      }
+      html += `<blockquote class="email-blockquote" style="margin:16px 0;padding:12px 20px;border-left:3px solid #e5e7eb;color:#6b7280;font-style:italic;">${inlineFormatting(quoteLines.join('<br>'))}</blockquote>`
+      continue
+    }
+
+    // Unordered list
+    if (/^[-*+]\s+/.test(trimmed)) {
+      if (inList !== 'ul') {
+        if (inList) html += `</${inList}>`
+        html += `<ul style="margin:12px 0;padding-left:24px;color:#1a1a1a;">`
+        inList = 'ul'
+      }
+      html += `<li style="margin:4px 0;line-height:1.6;">${inlineFormatting(trimmed.replace(/^[-*+]\s+/, ''))}</li>`
+      i++
+      continue
+    }
+
+    // Ordered list
+    const olMatch = trimmed.match(/^(\d+)\.\s+(.+)$/)
+    if (olMatch) {
+      if (inList !== 'ol') {
+        if (inList) html += `</${inList}>`
+        html += `<ol style="margin:12px 0;padding-left:24px;color:#1a1a1a;">`
+        inList = 'ol'
+      }
+      html += `<li style="margin:4px 0;line-height:1.6;">${inlineFormatting(olMatch[2]!)}</li>`
+      i++
+      continue
+    }
+
+    // Paragraph (default)
+    if (inList) { html += `</${inList}>`; inList = null }
+    html += `<p class="email-text" style="margin:12px 0;line-height:1.65;color:#1a1a1a;">${inlineFormatting(trimmed)}</p>`
+    i++
+  }
+
+  if (inList) html += `</${inList}>`
+
+  return html
+}
+
+/** Process inline markdown: bold, italic, code, links */
+function inlineFormatting(text: string): string {
+  return text
+    // Bold
+    .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+    // Italic
+    .replace(/\*(.+?)\*/g, '<em>$1</em>')
+    // Inline code
+    .replace(/`([^`]+)`/g, '<code class="email-code" style="background:#f3f4f6;padding:2px 6px;border-radius:3px;font-size:13px;font-family:\'SF Mono\',ui-monospace,Menlo,monospace;color:#10b981;">$1</code>')
+    // Links
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2" class="email-link" style="color:#10b981;text-decoration:underline;">$1</a>')
+}