@strav/mail 1.0.0-alpha.25

package/src/transports/alibaba_transport.ts

@@ -0,0 +1,273 @@
+/**
+ * `AlibabaDmTransport` — sends mail via Alibaba Cloud DirectMail (DM).
+ *
+ *   POST {endpoint}/?{rpc-v1 form-encoded params}
+ *   Content-Type: application/x-www-form-urlencoded
+ *
+ * Why this is here: DirectMail is the dominant transactional-email
+ * provider for apps deployed inside Alibaba Cloud and for senders
+ * targeting Chinese / South-East Asian inboxes — domestic deliverability
+ * to QQ, 163, NetEase, etc. routinely outperforms Western providers.
+ *
+ * Wire shape — DirectMail exposes a classic Alibaba-Cloud RPC API:
+ *
+ *   - Authentication: HMAC-SHA1 signature ("Signature V1") over a
+ *     URL-encoded sorted-key canonical query string. Key is
+ *     `{accessKeySecret}&`. We compute it per request — no SDK
+ *     dependency.
+ *   - Payload: form-urlencoded, NOT JSON. JSON is what the API
+ *     *responds* with (`Format=JSON`), not what we send.
+ *   - Action: `SingleSendMail` for transactional sends. The other
+ *     action (`BatchSendMail`) requires a pre-uploaded template and
+ *     is out of scope for an outbound `Transport`.
+ *
+ * Limitations forced by the API surface:
+ *
+ *   - **No attachments.** `SingleSendMail` has no attachment field;
+ *     attachments require SMTP relay or `BatchSendMail` with a
+ *     template-uploaded file. We throw `MailTransportError` rather
+ *     than silently drop bytes the caller expected to send.
+ *   - **No cc / bcc.** `SingleSendMail` accepts a comma-separated
+ *     `ToAddress` (up to 100) but exposes no cc / bcc parameters.
+ *     Merging cc / bcc into `to` would silently expose recipient
+ *     addresses, so we throw instead.
+ *   - **Custom headers are dropped.** `SingleSendMail` does not
+ *     expose arbitrary header injection. DirectMail's `TagName`
+ *     field covers the common "tag this send" use-case — set
+ *     `tagName` on the transport options if you need it.
+ *
+ * Regions — DirectMail is region-scoped. The transport defaults to
+ * the global endpoint (`https://dm.aliyuncs.com`); SEA-region
+ * customers override `endpoint` to e.g.
+ * `https://dm.ap-southeast-1.aliyuncs.com` (Singapore) or
+ * `https://dm.ap-southeast-5.aliyuncs.com` (Jakarta).
+ *
+ * @see https://www.alibabacloud.com/help/en/direct-mail/developer-reference/api-dm-2015-11-23-singlesendmail
+ */
+
+import { createHmac, randomUUID } from 'node:crypto'
+import type { Message } from '../message.ts'
+import type { Transport } from '../transport.ts'
+import { MailTransportError } from '../transport_error.ts'
+import { isRetryableStatus, mapRecipients, toStructured } from './internal/normalize.ts'
+
+const DEFAULT_ENDPOINT = 'https://dm.aliyuncs.com'
+const API_VERSION = '2015-11-23'
+
+export interface AlibabaDmTransportOptions {
+  /** Alibaba Cloud AccessKey ID. Pull from env in `config/mail.ts`; never hard-code. */
+  accessKeyId: string
+  /** Alibaba Cloud AccessKey Secret. */
+  accessKeySecret: string
+  /**
+   * Verified DirectMail sender address (the "AccountName" — must be
+   * pre-registered in the DirectMail console). DM enforces that
+   * outbound senders match a configured account; using `message.from`
+   * as `AccountName` would fail for every send that uses a per-user
+   * `from`. Configure the verified account here, set the display name
+   * via `message.from.name`.
+   */
+  accountName: string
+  /**
+   * Base URL of the DirectMail API. Defaults to `https://dm.aliyuncs.com`
+   * (global). Region overrides — common in SEA deployments:
+   *
+   *   - `https://dm.ap-southeast-1.aliyuncs.com` — Singapore
+   *   - `https://dm.ap-southeast-2.aliyuncs.com` — Sydney
+   *   - `https://dm.ap-southeast-3.aliyuncs.com` — Kuala Lumpur
+   *   - `https://dm.ap-southeast-5.aliyuncs.com` — Jakarta
+   */
+  endpoint?: string
+  /**
+   * Optional `TagName` attached to every send — surfaces in DirectMail
+   * console analytics. Equivalent to a fixed `X-Tag` header on
+   * Western providers.
+   */
+  tagName?: string
+  /**
+   * Enable click-tracking — DirectMail rewrites links in the HTML
+   * body. Off by default; turn on per-deployment if you actually
+   * consume the analytics.
+   */
+  clickTrace?: boolean
+  /** Custom `fetch` for tests. */
+  fetch?: typeof fetch
+  /** Override clock for deterministic signatures in tests. */
+  now?: () => Date
+  /** Override SignatureNonce generation for deterministic signatures in tests. */
+  nonce?: () => string
+}
+
+export class AlibabaDmTransport implements Transport {
+  private readonly accessKeyId: string
+  private readonly accessKeySecret: string
+  private readonly accountName: string
+  private readonly endpoint: string
+  private readonly tagName: string | undefined
+  private readonly clickTrace: '0' | '1'
+  private readonly fetchFn: typeof fetch
+  private readonly nowFn: () => Date
+  private readonly nonceFn: () => string
+
+  constructor(opts: AlibabaDmTransportOptions) {
+    this.accessKeyId = opts.accessKeyId
+    this.accessKeySecret = opts.accessKeySecret
+    this.accountName = opts.accountName
+    this.endpoint = (opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, '')
+    this.tagName = opts.tagName
+    this.clickTrace = opts.clickTrace ? '1' : '0'
+    this.fetchFn = opts.fetch ?? fetch
+    this.nowFn = opts.now ?? (() => new Date())
+    this.nonceFn = opts.nonce ?? (() => randomUUID())
+  }
+
+  async send(message: Message): Promise<void> {
+    if (message.from === undefined) {
+      throw new MailTransportError('Alibaba DM requires `from` — none on the message or default.', {
+        context: { provider: 'alibaba', retryable: false },
+      })
+    }
+    if (message.cc !== undefined || message.bcc !== undefined) {
+      throw new MailTransportError(
+        'Alibaba DM SingleSendMail does not support cc/bcc — send a separate message per recipient set.',
+        { context: { provider: 'alibaba', retryable: false } },
+      )
+    }
+    if (message.attachments !== undefined && message.attachments.length > 0) {
+      throw new MailTransportError(
+        'Alibaba DM SingleSendMail does not support attachments. Use SMTP relay or BatchSendMail with a template-uploaded file.',
+        { context: { provider: 'alibaba', retryable: false } },
+      )
+    }
+
+    const fromAddress = toStructured(message.from)
+    const toAddresses = mapRecipients(message.to, toStructured)
+    if (toAddresses.length === 0) {
+      throw new MailTransportError('Alibaba DM requires at least one `to` recipient.', {
+        context: { provider: 'alibaba', retryable: false },
+      })
+    }
+
+    const params: Record<string, string> = {
+      // Common RPC parameters.
+      Action: 'SingleSendMail',
+      Version: API_VERSION,
+      Format: 'JSON',
+      AccessKeyId: this.accessKeyId,
+      SignatureMethod: 'HMAC-SHA1',
+      SignatureVersion: '1.0',
+      SignatureNonce: this.nonceFn(),
+      Timestamp: toAlibabaTimestamp(this.nowFn()),
+      // Action-specific parameters.
+      AccountName: this.accountName,
+      // AddressType=1 → send from a configured sender account (the normal
+      // path). 0 is reserved for "random sender" which we don't expose.
+      AddressType: '1',
+      ReplyToAddress: message.replyTo === undefined ? 'false' : 'true',
+      ToAddress: toAddresses.map((a) => a.email).join(','),
+      Subject: message.subject,
+      ClickTrace: this.clickTrace,
+    }
+
+    if (fromAddress.name !== undefined) params['FromAlias'] = fromAddress.name
+    if (message.html !== undefined) params['HtmlBody'] = message.html
+    if (message.text !== undefined) params['TextBody'] = message.text
+    if (this.tagName !== undefined) params['TagName'] = this.tagName
+
+    if (message.replyTo !== undefined) {
+      // DM SingleSendMail accepts a single ReplyAddress. If the caller
+      // passed multiple, we use the first — matches what DM would do if
+      // we crammed extras into a header it doesn't read.
+      const [first] = mapRecipients(message.replyTo, toStructured)
+      if (first !== undefined) {
+        params['ReplyAddress'] = first.email
+        if (first.name !== undefined) params['ReplyAddressAlias'] = first.name
+      }
+    }
+
+    params['Signature'] = signRpcV1(params, 'POST', this.accessKeySecret)
+
+    let response: Response
+    try {
+      response = await this.fetchFn(this.endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: encodeForm(params),
+      })
+    } catch (cause) {
+      throw new MailTransportError(
+        `Alibaba DM send failed at the network layer: ${(cause as Error).message ?? String(cause)}`,
+        { context: { provider: 'alibaba', 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(
+      `Alibaba DM rejected the send (HTTP ${response.status} ${response.statusText}).`,
+      {
+        context: {
+          provider: 'alibaba',
+          status: response.status,
+          retryable: isRetryableStatus(response.status),
+          providerError,
+        },
+      },
+    )
+  }
+}
+
+/**
+ * Alibaba Cloud RPC v1 signature.
+ *
+ *   StringToSign = HTTPMethod + "&" + pct(/) + "&" + pct(canonicalQueryString)
+ *   Signature    = base64(HMAC-SHA1(StringToSign, accessKeySecret + "&"))
+ *
+ * The trailing `&` on the HMAC key is mandated by the spec — it is
+ * NOT a bug. Same with the literal `&` separators in `StringToSign`.
+ */
+function signRpcV1(
+  params: Record<string, string>,
+  method: string,
+  accessKeySecret: string,
+): string {
+  const sortedKeys = Object.keys(params).sort()
+  const canonical = sortedKeys
+    .map((k) => `${percentEncode(k)}=${percentEncode(params[k] as string)}`)
+    .join('&')
+  const stringToSign = `${method}&${percentEncode('/')}&${percentEncode(canonical)}`
+  return createHmac('sha1', `${accessKeySecret}&`).update(stringToSign).digest('base64')
+}
+
+/**
+ * Alibaba's percent-encoding rules — RFC 3986 strict, with the
+ * additional fix-ups that bring `encodeURIComponent` into line:
+ * encode `!`, `'`, `(`, `)`, `*`, but leave `~` alone (which
+ * `encodeURIComponent` already does in modern engines).
+ */
+function percentEncode(value: string): string {
+  return encodeURIComponent(value)
+    .replace(/!/g, '%21')
+    .replace(/'/g, '%27')
+    .replace(/\(/g, '%28')
+    .replace(/\)/g, '%29')
+    .replace(/\*/g, '%2A')
+}
+
+function encodeForm(params: Record<string, string>): string {
+  return Object.entries(params)
+    .map(([k, v]) => `${percentEncode(k)}=${percentEncode(v)}`)
+    .join('&')
+}
+
+/** ISO 8601 in UTC with seconds precision — `2025-01-15T08:30:00Z`. */
+function toAlibabaTimestamp(d: Date): string {
+  return `${d.toISOString().slice(0, 19)}Z`
+}

package/src/transports/array_transport.ts

@@ -0,0 +1,36 @@
+/**
+ * `ArrayTransport` — in-memory mail sink for tests.
+ *
+ * Records every `send()` in insertion order. Apps wire it as the
+ * default transport during tests, then assert on `transport.messages`
+ * to verify what would have left the process. No I/O, no encoding —
+ * the recorded `Message` is the same object passed to `send()` (a
+ * shallow copy, so downstream mutation by the caller doesn't disturb
+ * recorded history).
+ */
+
+import type { Message } from '../message.ts'
+import type { Transport } from '../transport.ts'
+
+export class ArrayTransport implements Transport {
+  private readonly _messages: Message[] = []
+
+  async send(message: Message): Promise<void> {
+    this._messages.push({ ...message })
+  }
+
+  /** Frozen view of every message recorded since the last `clear()`. */
+  get messages(): readonly Message[] {
+    return this._messages
+  }
+
+  /** Number of messages recorded. Equivalent to `messages.length`. */
+  get count(): number {
+    return this._messages.length
+  }
+
+  /** Drop all recorded messages. Use between tests. */
+  clear(): void {
+    this._messages.length = 0
+  }
+}

package/src/transports/internal/normalize.ts

@@ -0,0 +1,92 @@
+/**
+ * Internal helpers shared by HTTP-based transports (Resend, SendGrid,
+ * future Postmark / Mailgun).
+ *
+ * These are NOT exported from the package barrel — they're an
+ * implementation detail of the transports. Tests reach in via the
+ * relative path; user code constructs a `Message` and lets the
+ * transport format it.
+ */
+
+import type { MailAddress, MailRecipient, MessageAttachment } from '../../message.ts'
+
+// ─── Recipient normalisation ─────────────────────────────────────────────────
+
+/**
+ * Coerce a `MailRecipient` into `{ email, name? }` form.
+ * Used by transports whose API takes structured-recipient JSON
+ * (SendGrid: `[{ "email": "...", "name": "..." }]`).
+ */
+export function toStructured(r: MailRecipient): MailAddress {
+  return typeof r === 'string' ? { email: r } : r
+}
+
+/**
+ * Coerce a `MailRecipient` into RFC 5322 "Name <email>" form.
+ * Used by transports that accept that as a single string (Resend:
+ * `"to": "Alice <a@x>"`).
+ */
+export function toRfc5322(r: MailRecipient): string {
+  if (typeof r === 'string') return r
+  if (r.name === undefined) return r.email
+  return `"${escapeQuotes(r.name)}" <${r.email}>`
+}
+
+function escapeQuotes(s: string): string {
+  return s.replace(/"/g, '\\"')
+}
+
+/** Apply `mapper` to either a single recipient or a list. */
+export function mapRecipients<T>(
+  value: MailRecipient | MailRecipient[],
+  mapper: (r: MailRecipient) => T,
+): T[] {
+  return Array.isArray(value) ? value.map(mapper) : [mapper(value)]
+}
+
+// ─── Attachment encoding ─────────────────────────────────────────────────────
+
+/**
+ * Encode a `MessageAttachment`'s `content` to base64 — the wire format
+ * every HTTP mail provider accepts. `Uint8Array` → btoa; `string` is
+ * pass-through if `encoding: 'base64'`, otherwise UTF-8 → btoa.
+ */
+export function attachmentToBase64(a: MessageAttachment): string {
+  if (typeof a.content === 'string') {
+    if (a.encoding === 'base64') return a.content
+    // UTF-8 string → bytes → base64.
+    return uint8ToBase64(new TextEncoder().encode(a.content))
+  }
+  return uint8ToBase64(a.content)
+}
+
+function uint8ToBase64(bytes: Uint8Array): string {
+  // Bun supports btoa + the binary-string trick used in browsers; this
+  // path stays portable to plain Node without pulling Buffer in.
+  let binary = ''
+  const chunk = 0x8000
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk))
+  }
+  return btoa(binary)
+}
+
+// ─── Retry classification ────────────────────────────────────────────────────
+
+/**
+ * Best-effort guess at whether a transport failure is worth retrying.
+ * Used in the `context.retryable` field of `MailTransportError` so
+ * the Worker's `failed()` hook can log the hint (the Worker itself
+ * doesn't read it — retry policy lives in `Job.maxAttempts` /
+ * `Job.backoff`).
+ *
+ * Rule of thumb (matches HTTP semantics):
+ *   - 5xx / network → retryable
+ *   - 408 / 429 → retryable (timeout + rate-limit)
+ *   - other 4xx → permanent
+ */
+export function isRetryableStatus(status: number): boolean {
+  if (status >= 500) return true
+  if (status === 408 || status === 429) return true
+  return false
+}

package/src/transports/log_transport.ts

@@ -0,0 +1,74 @@
+/**
+ * `LogTransport` — writes outgoing mail to a `Logger` channel instead
+ * of a real transport.
+ *
+ * Local-dev default. Apps point `config.mail.default` at the `'log'`
+ * transport so that `bun dev` prints what would have been sent without
+ * touching SMTP / Resend / SendGrid. Production never uses this — the
+ * Mail body sits in logs verbatim.
+ *
+ * Output shape
+ *   The transport emits one structured record per `send()`:
+ *
+ *     logger.info('mail.sent', { mail: { to, from, subject, ... } })
+ *
+ *   The Logger contract is `(msg, fields?)`, so the event identifier
+ *   `'mail.sent'` is the first arg and the structured payload is the
+ *   second. Bodies are not logged by default — putting full HTML into
+ *   a log channel is wasteful in dev and unsafe in shared environments.
+ *   Set `includeBody: true` to opt in (intended only for local debugging).
+ */
+
+import type { Logger } from '@strav/kernel'
+import type { Message } from '../message.ts'
+import type { Transport } from '../transport.ts'
+
+export interface LogTransportOptions {
+  /** Logger to write records to. Typically a named channel like `'mail'`. */
+  logger: Logger
+  /** Log level for outgoing records. Default `'info'`. */
+  level?: 'debug' | 'info'
+  /**
+   * Include `html` / `text` bodies in the log record. Default `false`
+   * — bodies in logs are noisy and can leak PII. Flip on only for
+   * local debugging.
+   */
+  includeBody?: boolean
+}
+
+export class LogTransport implements Transport {
+  private readonly logger: Logger
+  private readonly level: 'debug' | 'info'
+  private readonly includeBody: boolean
+
+  constructor(opts: LogTransportOptions) {
+    this.logger = opts.logger
+    this.level = opts.level ?? 'info'
+    this.includeBody = opts.includeBody ?? false
+  }
+
+  async send(message: Message): Promise<void> {
+    const record: Record<string, unknown> = {
+      to: message.to,
+      from: message.from,
+      subject: message.subject,
+      hasHtml: message.html !== undefined,
+      hasText: message.text !== undefined,
+    }
+    if (message.cc !== undefined) record.cc = message.cc
+    if (message.bcc !== undefined) record.bcc = message.bcc
+    if (message.replyTo !== undefined) record.replyTo = message.replyTo
+    if (message.headers !== undefined) record.headers = message.headers
+    if (message.attachments !== undefined) {
+      record.attachments = message.attachments.map((a) => ({
+        filename: a.filename,
+        contentType: a.contentType,
+      }))
+    }
+    if (this.includeBody) {
+      if (message.html !== undefined) record.html = message.html
+      if (message.text !== undefined) record.text = message.text
+    }
+    this.logger[this.level]('mail.sent', { mail: record })
+  }
+}

package/src/transports/mailgun_transport.ts

@@ -0,0 +1,160 @@
+/**
+ * `MailgunTransport` — sends mail via the Mailgun HTTP API.
+ *
+ *   POST {endpoint}/v3/{domain}/messages
+ *   Authorization: Basic base64('api:{apiKey}')
+ *   Content-Type: multipart/form-data    (set automatically by fetch)
+ *
+ * Mailgun differs from Resend / SendGrid in two ways:
+ *
+ *   1. Auth is HTTP Basic with a fixed `"api"` username — the API key
+ *      is the password. We construct the credential internally; the
+ *      config only collects the key.
+ *   2. The request body is `FormData`, not JSON. Recipients are
+ *      comma-separated strings on `to` / `cc` / `bcc`; custom headers
+ *      ride as `h:X-Header-Name` form fields; attachments are `Blob`
+ *      parts on the `attachment` field.
+ *
+ * Region routing — EU customers override `endpoint` to
+ * `https://api.eu.mailgun.net`. The default is the US endpoint.
+ *
+ * @see https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Messages/
+ */
+
+import type { Message, MessageAttachment } from '../message.ts'
+import type { Transport } from '../transport.ts'
+import { MailTransportError } from '../transport_error.ts'
+import { isRetryableStatus, mapRecipients, toRfc5322 } from './internal/normalize.ts'
+
+export interface MailgunTransportOptions {
+  /** Mailgun API key. Pull from env in `config/mail.ts`; never hard-code. */
+  apiKey: string
+  /**
+   * Sending domain registered with Mailgun (e.g. `mg.acme.com`). Used
+   * as the path component of the API URL. Distinct from the recipient
+   * domain — this is YOUR Mailgun-verified domain.
+   */
+  domain: string
+  /**
+   * Base URL of the Mailgun API. Defaults to `https://api.mailgun.net`.
+   * Set to `https://api.eu.mailgun.net` for EU-region accounts.
+   */
+  endpoint?: string
+  /** Custom `fetch` for tests. */
+  fetch?: typeof fetch
+}
+
+export class MailgunTransport implements Transport {
+  private readonly apiKey: string
+  private readonly domain: string
+  private readonly endpoint: string
+  private readonly fetchFn: typeof fetch
+
+  constructor(opts: MailgunTransportOptions) {
+    this.apiKey = opts.apiKey
+    this.domain = opts.domain
+    this.endpoint = (opts.endpoint ?? 'https://api.mailgun.net').replace(/\/$/, '')
+    this.fetchFn = opts.fetch ?? fetch
+  }
+
+  async send(message: Message): Promise<void> {
+    if (message.from === undefined) {
+      throw new MailTransportError('Mailgun requires `from` — none on the message or default.', {
+        context: { provider: 'mailgun', retryable: false },
+      })
+    }
+
+    const form = new FormData()
+    form.append('from', toRfc5322(message.from))
+    form.append('to', mapRecipients(message.to, toRfc5322).join(', '))
+    form.append('subject', message.subject)
+
+    if (message.cc !== undefined) {
+      form.append('cc', mapRecipients(message.cc, toRfc5322).join(', '))
+    }
+    if (message.bcc !== undefined) {
+      form.append('bcc', mapRecipients(message.bcc, toRfc5322).join(', '))
+    }
+    if (message.replyTo !== undefined) {
+      // Mailgun expects a single Reply-To header value. Multiple
+      // reply-tos collapse to a comma-separated list inside the
+      // single header — RFC 5322 allows that.
+      form.append('h:Reply-To', mapRecipients(message.replyTo, toRfc5322).join(', '))
+    }
+    if (message.html !== undefined) form.append('html', message.html)
+    if (message.text !== undefined) form.append('text', message.text)
+
+    if (message.headers !== undefined) {
+      for (const [name, value] of Object.entries(message.headers)) {
+        // `h:` prefix turns the form field into an outbound header.
+        form.append(`h:${name}`, value)
+      }
+    }
+
+    if (message.attachments !== undefined) {
+      for (const a of message.attachments) {
+        form.append('attachment', attachmentToBlob(a), a.filename)
+      }
+    }
+
+    const credentials = btoa(`api:${this.apiKey}`)
+    let response: Response
+    try {
+      response = await this.fetchFn(`${this.endpoint}/v3/${this.domain}/messages`, {
+        method: 'POST',
+        headers: { authorization: `Basic ${credentials}` },
+        body: form,
+      })
+    } catch (cause) {
+      throw new MailTransportError(
+        `Mailgun send failed at the network layer: ${(cause as Error).message ?? String(cause)}`,
+        { context: { provider: 'mailgun', 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(
+      `Mailgun rejected the send (HTTP ${response.status} ${response.statusText}).`,
+      {
+        context: {
+          provider: 'mailgun',
+          status: response.status,
+          retryable: isRetryableStatus(response.status),
+          providerError,
+        },
+      },
+    )
+  }
+}
+
+/**
+ * Mailgun accepts attachments as `Blob` parts on the multipart form —
+ * the same byte stream the user supplied, wrapped with the declared
+ * MIME type. Unlike Resend / SendGrid we don't base64-encode here;
+ * `fetch` handles the multipart boundary and binary framing.
+ *
+ * For `encoding: 'base64'` string inputs we DO need to decode first —
+ * Mailgun expects raw bytes on the wire, not base64 text.
+ */
+function attachmentToBlob(a: MessageAttachment): Blob {
+  const type = a.contentType ?? 'application/octet-stream'
+  if (typeof a.content === 'string') {
+    if (a.encoding === 'base64') {
+      // Decode base64 → bytes so the wire payload is the actual file.
+      const binary = atob(a.content)
+      const bytes = new Uint8Array(binary.length)
+      for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i)
+      return new Blob([bytes], { type })
+    }
+    return new Blob([a.content], { type })
+  }
+  return new Blob([a.content], { type })
+}