@strav/mail 1.0.0-alpha.25

package/src/transports/resend_transport.ts

@@ -0,0 +1,149 @@
+/**
+ * `ResendTransport` — sends mail via the Resend HTTP API.
+ *
+ *   POST {endpoint}/emails
+ *   Authorization: Bearer {apiKey}
+ *   Content-Type: application/json
+ *
+ *   { from, to, subject, html?, text?, cc?, bcc?, reply_to?,
+ *     headers?, attachments?: [{ filename, content (base64) }] }
+ *
+ * Resend accepts recipients as either `"Name <email>"` strings or bare
+ * emails — this transport normalises to the RFC 5322 form so display
+ * names always render.
+ *
+ * Failure model: any non-2xx response throws `MailTransportError`.
+ * The `context` payload carries `provider`, `status`, `retryable`
+ * (heuristic), and the parsed provider error body when present — the
+ * Worker's `failed()` hook can log it as-is.
+ *
+ * Networking: a transient `fetch` rejection (DNS, TCP reset, TLS
+ * timeout) wraps as `MailTransportError` with `context.retryable: true`
+ * — the underlying `Error.cause` carries the original.
+ *
+ * @see https://resend.com/docs/api-reference/emails/send-email
+ */
+
+import type { Message } from '../message.ts'
+import type { Transport } from '../transport.ts'
+import { MailTransportError } from '../transport_error.ts'
+import {
+  attachmentToBase64,
+  isRetryableStatus,
+  mapRecipients,
+  toRfc5322,
+} from './internal/normalize.ts'
+
+export interface ResendTransportOptions {
+  /** Resend API key (`re_…`). Read from env / config, never hard-coded. */
+  apiKey: string
+  /**
+   * Base URL of the Resend API. Defaults to `https://api.resend.com`.
+   * Override for self-hosted / regional / mocked endpoints.
+   */
+  endpoint?: string
+  /**
+   * Custom `fetch` for tests. Defaults to the global `fetch`. The
+   * transport doesn't validate its return shape beyond `.ok` + `.json()`
+   * — pass a plain stub.
+   */
+  fetch?: typeof fetch
+}
+
+interface ResendRequestBody {
+  from: string
+  to: string[]
+  subject: string
+  html?: string
+  text?: string
+  cc?: string[]
+  bcc?: string[]
+  reply_to?: string | string[]
+  headers?: Record<string, string>
+  attachments?: Array<{ filename: string; content: string; content_type?: string }>
+}
+
+export class ResendTransport implements Transport {
+  private readonly apiKey: string
+  private readonly endpoint: string
+  private readonly fetchFn: typeof fetch
+
+  constructor(opts: ResendTransportOptions) {
+    this.apiKey = opts.apiKey
+    this.endpoint = (opts.endpoint ?? 'https://api.resend.com').replace(/\/$/, '')
+    this.fetchFn = opts.fetch ?? fetch
+  }
+
+  async send(message: Message): Promise<void> {
+    if (message.from === undefined) {
+      throw new MailTransportError('Resend requires `from` — none on the message or default.', {
+        context: { provider: 'resend', retryable: false },
+      })
+    }
+
+    const body: ResendRequestBody = {
+      from: toRfc5322(message.from),
+      to: mapRecipients(message.to, toRfc5322),
+      subject: message.subject,
+    }
+    if (message.html !== undefined) body.html = message.html
+    if (message.text !== undefined) body.text = message.text
+    if (message.cc !== undefined) body.cc = mapRecipients(message.cc, toRfc5322)
+    if (message.bcc !== undefined) body.bcc = mapRecipients(message.bcc, toRfc5322)
+    if (message.replyTo !== undefined) {
+      const list = mapRecipients(message.replyTo, toRfc5322)
+      const [first] = list
+      body.reply_to = list.length === 1 && first !== undefined ? first : list
+    }
+    if (message.headers !== undefined) body.headers = message.headers
+    if (message.attachments !== undefined && message.attachments.length > 0) {
+      body.attachments = message.attachments.map((a) => {
+        const out: { filename: string; content: string; content_type?: string } = {
+          filename: a.filename,
+          content: attachmentToBase64(a),
+        }
+        if (a.contentType !== undefined) out.content_type = a.contentType
+        return out
+      })
+    }
+
+    let response: Response
+    try {
+      response = await this.fetchFn(`${this.endpoint}/emails`, {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${this.apiKey}`,
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      })
+    } catch (cause) {
+      // Network-level failure — no HTTP response. Treat as retryable.
+      throw new MailTransportError(
+        `Resend send failed at the network layer: ${(cause as Error).message ?? String(cause)}`,
+        { context: { provider: 'resend', retryable: true }, cause },
+      )
+    }
+
+    if (response.ok) return
+
+    let providerError: unknown
+    try {
+      providerError = await response.json()
+    } catch {
+      providerError = await response.text().catch(() => undefined)
+    }
+
+    throw new MailTransportError(
+      `Resend rejected the send (HTTP ${response.status} ${response.statusText}).`,
+      {
+        context: {
+          provider: 'resend',
+          status: response.status,
+          retryable: isRetryableStatus(response.status),
+          providerError,
+        },
+      },
+    )
+  }
+}

package/src/transports/sendgrid_transport.ts

@@ -0,0 +1,179 @@
+/**
+ * `SendGridTransport` — sends mail via the SendGrid v3 API.
+ *
+ *   POST {endpoint}/v3/mail/send
+ *   Authorization: Bearer {apiKey}
+ *   Content-Type: application/json
+ *
+ *   {
+ *     personalizations: [{ to, cc?, bcc?, subject?, headers? }],
+ *     from, reply_to?,
+ *     subject,
+ *     content: [{ type: 'text/plain', value }, { type: 'text/html', value }],
+ *     attachments?: [{ content (base64), filename, type, disposition }],
+ *     headers?,
+ *   }
+ *
+ * SendGrid wants structured recipients (`{ "email": "...", "name": "..." }`)
+ * and a multi-part `content` array. The transport normalises both.
+ *
+ * SendGrid returns `202 Accepted` on success (no body). Any other
+ * status throws `MailTransportError` with `provider: 'sendgrid'` and
+ * the parsed error body when present.
+ *
+ * @see https://docs.sendgrid.com/api-reference/mail-send/mail-send
+ */
+
+import type { MailAddress, Message } from '../message.ts'
+import type { Transport } from '../transport.ts'
+import { MailTransportError } from '../transport_error.ts'
+import {
+  attachmentToBase64,
+  isRetryableStatus,
+  mapRecipients,
+  toStructured,
+} from './internal/normalize.ts'
+
+export interface SendGridTransportOptions {
+  /** SendGrid API key (`SG.…`). Read from env / config, never hard-coded. */
+  apiKey: string
+  /**
+   * Base URL of the SendGrid API. Defaults to `https://api.sendgrid.com`.
+   * Override for regional / mocked endpoints.
+   */
+  endpoint?: string
+  /** Custom `fetch` for tests. */
+  fetch?: typeof fetch
+}
+
+interface SendGridContent {
+  type: 'text/plain' | 'text/html'
+  value: string
+}
+
+interface SendGridPersonalization {
+  to: MailAddress[]
+  cc?: MailAddress[]
+  bcc?: MailAddress[]
+}
+
+interface SendGridAttachment {
+  content: string
+  filename: string
+  type?: string
+  disposition: 'attachment'
+}
+
+interface SendGridRequestBody {
+  personalizations: SendGridPersonalization[]
+  from: MailAddress
+  reply_to?: MailAddress
+  subject: string
+  content: SendGridContent[]
+  attachments?: SendGridAttachment[]
+  headers?: Record<string, string>
+}
+
+export class SendGridTransport implements Transport {
+  private readonly apiKey: string
+  private readonly endpoint: string
+  private readonly fetchFn: typeof fetch
+
+  constructor(opts: SendGridTransportOptions) {
+    this.apiKey = opts.apiKey
+    this.endpoint = (opts.endpoint ?? 'https://api.sendgrid.com').replace(/\/$/, '')
+    this.fetchFn = opts.fetch ?? fetch
+  }
+
+  async send(message: Message): Promise<void> {
+    if (message.from === undefined) {
+      throw new MailTransportError('SendGrid requires `from` — none on the message or default.', {
+        context: { provider: 'sendgrid', retryable: false },
+      })
+    }
+
+    // SendGrid requires at least one content entry. The order matters —
+    // text/plain before text/html, per the v3 docs.
+    const content: SendGridContent[] = []
+    if (message.text !== undefined) content.push({ type: 'text/plain', value: message.text })
+    if (message.html !== undefined) content.push({ type: 'text/html', value: message.html })
+    if (content.length === 0) {
+      throw new MailTransportError(
+        'SendGrid: Message must include at least one of `html` or `text`.',
+        { context: { provider: 'sendgrid', retryable: false } },
+      )
+    }
+
+    const personalization: SendGridPersonalization = {
+      to: mapRecipients(message.to, toStructured),
+    }
+    if (message.cc !== undefined) personalization.cc = mapRecipients(message.cc, toStructured)
+    if (message.bcc !== undefined) personalization.bcc = mapRecipients(message.bcc, toStructured)
+
+    const body: SendGridRequestBody = {
+      personalizations: [personalization],
+      from: toStructured(message.from),
+      subject: message.subject,
+      content,
+    }
+    if (message.replyTo !== undefined) {
+      // SendGrid v3 single reply_to. If the caller passes a list, take
+      // the first — the rest are best-effort dropped (multi reply-to
+      // goes through `reply_to_list`, a newer field; not modelled here
+      // until a real user needs it).
+      const list = mapRecipients(message.replyTo, toStructured)
+      if (list[0] !== undefined) body.reply_to = list[0]
+    }
+    if (message.headers !== undefined) body.headers = message.headers
+    if (message.attachments !== undefined && message.attachments.length > 0) {
+      body.attachments = message.attachments.map((a) => {
+        const out: SendGridAttachment = {
+          content: attachmentToBase64(a),
+          filename: a.filename,
+          disposition: 'attachment',
+        }
+        if (a.contentType !== undefined) out.type = a.contentType
+        return out
+      })
+    }
+
+    let response: Response
+    try {
+      response = await this.fetchFn(`${this.endpoint}/v3/mail/send`, {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${this.apiKey}`,
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      })
+    } catch (cause) {
+      throw new MailTransportError(
+        `SendGrid send failed at the network layer: ${(cause as Error).message ?? String(cause)}`,
+        { context: { provider: 'sendgrid', retryable: true }, cause },
+      )
+    }
+
+    // SendGrid returns 202 Accepted on success. Anything else is a failure.
+    if (response.ok) return
+
+    let providerError: unknown
+    try {
+      providerError = await response.json()
+    } catch {
+      providerError = await response.text().catch(() => undefined)
+    }
+
+    throw new MailTransportError(
+      `SendGrid rejected the send (HTTP ${response.status} ${response.statusText}).`,
+      {
+        context: {
+          provider: 'sendgrid',
+          status: response.status,
+          retryable: isRetryableStatus(response.status),
+          providerError,
+        },
+      },
+    )
+  }
+}