@strav/mail 1.0.0-alpha.25

package/src/index.ts

@@ -0,0 +1,56 @@
+// Public API of @strav/mail — mail layer.
+//
+// Shipping:
+//   - The `Message` shape + `MailRecipient` / `MailAddress` /
+//     `MessageAttachment`.
+//   - The `Transport` driver contract.
+//   - Two transports: `ArrayTransport` (in-memory recorder for tests)
+//     + `LogTransport` (writes to a `Logger` channel — local-dev).
+//   - `MailManager` — multi-transport orchestration with `via(name?)`,
+//     default-`from` substitution, lazy/cached transport construction,
+//     and a Mailable-aware `send(MailableClass, payload)` overload.
+//   - `MailProvider` — wires `MailManager` into the container from
+//     `config('mail')`.
+//   - `Mailable<TPayload>` — typed `Job` subclass; `build(payload)` is
+//     the override point, `handle()` is auto-implemented to send via
+//     the default transport. Dispatch via `queue.dispatch(MailableClass,
+//     payload)` like any other Job.
+//
+// Inbound webhooks:
+//   - `PostmarkInboundParser` + `MailgunInboundParser` normalize provider
+//     webhooks to `ParsedInboundMail`. Mailgun verifies HMAC-SHA256;
+//     Postmark relies on HTTP-level auth (Basic/IP allow-list).
+//   - `isAutoGeneratedMessage` — mail-loop guard for application code.
+//
+// Notifications, broadcast, and SSE live in `@strav/notification`.
+
+export { isAutoGeneratedMessage } from './inbound/loop_guard.ts'
+export { MailgunInboundParser } from './inbound/mailgun_parser.ts'
+export { PostmarkInboundParser } from './inbound/postmark_parser.ts'
+export type {
+  InboundWebhookInput,
+  InboundWebhookParser,
+  MailgunInboundConfig,
+  ParsedInboundAddress,
+  ParsedInboundAttachment,
+  ParsedInboundMail,
+} from './inbound/types.ts'
+export { MailInboundError } from './inbound_error.ts'
+export { type MailConfig, MailManager, type MailTransportConfig } from './mail_manager.ts'
+export { MailProvider } from './mail_provider.ts'
+export { Mailable, type MailableClass, type MailablePayloadOf } from './mailable.ts'
+export type { MailAddress, MailRecipient, Message, MessageAttachment } from './message.ts'
+export type { Transport } from './transport.ts'
+export { MailTransportError } from './transport_error.ts'
+export {
+  AlibabaDmTransport,
+  type AlibabaDmTransportOptions,
+} from './transports/alibaba_transport.ts'
+export { ArrayTransport } from './transports/array_transport.ts'
+export { LogTransport, type LogTransportOptions } from './transports/log_transport.ts'
+export { MailgunTransport, type MailgunTransportOptions } from './transports/mailgun_transport.ts'
+export { ResendTransport, type ResendTransportOptions } from './transports/resend_transport.ts'
+export {
+  SendGridTransport,
+  type SendGridTransportOptions,
+} from './transports/sendgrid_transport.ts'

package/src/mail_manager.ts

@@ -0,0 +1,322 @@
+/**
+ * `MailManager` — builds and caches one `Transport` per configured
+ * mail transport.
+ *
+ * Built once at boot from `config('mail')`. Validates the config eagerly
+ * (default-transport exists, every entry has a known `driver`) so
+ * misconfiguration surfaces during provider boot, not on the first
+ * `mail.send()` call inside a request. Each transport's underlying
+ * resource is constructed lazily on first `via(name)`, then cached for
+ * the lifetime of the manager.
+ *
+ * The `from` substitution
+ *   `config.mail.from` is an optional default sender. If a `Message`
+ *   omits `from`, the manager fills it in before handing the message
+ *   to the transport. If neither is set, the transport throws. The
+ *   manager does NOT override a `from` the caller already set —
+ *   per-message overrides win.
+ *
+ * Shutdown
+ *   `shutdown()` runs every cached transport's optional `close()`
+ *   best-effort, swallowing errors so a misbehaving transport can't
+ *   block app shutdown.
+ *
+ * Multi-transport apps
+ *   `via(name?)` returns a named transport (or the default if `name`
+ *   is omitted). Callers that want to route a particular message
+ *   through a non-default transport do:
+ *
+ *     await mail.via('priority').send({ to, subject, ... })
+ */
+
+import { ConfigError, type Container, type Logger, type LogManager } from '@strav/kernel'
+import type { MailableClass, MailablePayloadOf } from './mailable.ts'
+import type { MailRecipient, Message } from './message.ts'
+import type { Transport } from './transport.ts'
+import { AlibabaDmTransport } from './transports/alibaba_transport.ts'
+import { ArrayTransport } from './transports/array_transport.ts'
+import { LogTransport } from './transports/log_transport.ts'
+import { MailgunTransport } from './transports/mailgun_transport.ts'
+import { ResendTransport } from './transports/resend_transport.ts'
+import { SendGridTransport } from './transports/sendgrid_transport.ts'
+
+/** Per-driver transport config shapes. */
+interface ArrayTransportConfig {
+  driver: 'array'
+}
+
+interface LogTransportConfig {
+  driver: 'log'
+  /**
+   * Logger channel to write to. Falls back to the default channel when
+   * omitted. Apps typically dedicate a channel (`'mail'`) so dev output
+   * is filterable.
+   */
+  channel?: string
+  /** Default `'info'`. */
+  level?: 'debug' | 'info'
+  /** See `LogTransportOptions.includeBody`. Default `false`. */
+  includeBody?: boolean
+}
+
+interface ResendTransportConfig {
+  driver: 'resend'
+  /** Resend API key. Pull from env in `config/mail.ts`; never hard-code. */
+  apiKey: string
+  /** Override the base URL — defaults to `https://api.resend.com`. */
+  endpoint?: string
+}
+
+interface SendGridTransportConfig {
+  driver: 'sendgrid'
+  /** SendGrid API key. */
+  apiKey: string
+  /** Override the base URL — defaults to `https://api.sendgrid.com`. */
+  endpoint?: string
+}
+
+interface MailgunTransportConfig {
+  driver: 'mailgun'
+  /** Mailgun API key. */
+  apiKey: string
+  /** Your Mailgun-verified sending domain (e.g. `mg.acme.com`). */
+  domain: string
+  /**
+   * Override the base URL — defaults to `https://api.mailgun.net`.
+   * Set to `https://api.eu.mailgun.net` for EU-region accounts.
+   */
+  endpoint?: string
+}
+
+interface AlibabaDmTransportConfig {
+  driver: 'alibaba'
+  /** Alibaba Cloud AccessKey ID. */
+  accessKeyId: string
+  /** Alibaba Cloud AccessKey Secret. */
+  accessKeySecret: string
+  /** Verified DirectMail sender account (set in the DM console). */
+  accountName: string
+  /**
+   * Override the base URL — defaults to `https://dm.aliyuncs.com` (global).
+   * SEA: `https://dm.ap-southeast-1.aliyuncs.com` (Singapore),
+   * `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. */
+  tagName?: string
+  /** Enable DM click-tracking. Default false. */
+  clickTrace?: boolean
+}
+
+/**
+ * Discriminated union — every shipping driver gets an entry. Adding a
+ * new driver here + a new `case` in `buildTransport` is the contract;
+ * apps configure by string name.
+ */
+export type MailTransportConfig =
+  | ArrayTransportConfig
+  | LogTransportConfig
+  | ResendTransportConfig
+  | SendGridTransportConfig
+  | MailgunTransportConfig
+  | AlibabaDmTransportConfig
+
+export interface MailConfig {
+  /**
+   * Name of the transport used by `send()` when the caller doesn't
+   * specify one. Must be a key of `transports`.
+   */
+  default: string
+  /**
+   * Default `from` filled in when a `Message` omits one. Optional —
+   * apps that always pass `from` per-message can leave this off.
+   */
+  from?: MailRecipient
+  /** Transport instances keyed by name. */
+  transports: Record<string, MailTransportConfig>
+}
+
+export class MailManager {
+  private readonly cache = new Map<string, Transport>()
+
+  constructor(
+    private readonly config: MailConfig,
+    private readonly logManager: LogManager,
+    /**
+     * Optional `Container` used by the `send(MailableClass, payload)`
+     * overload to construct mailables via `@inject()` reflection. Apps
+     * that only ever call `send(message)` can omit it; the Mailable
+     * overload throws a clear error if called without one wired.
+     *
+     * The `MailProvider` passes the resolving container automatically,
+     * so apps using the provider don't pass anything by hand.
+     */
+    private readonly container?: Container,
+  ) {
+    this.validate(config)
+  }
+
+  /**
+   * Send `message` via the default transport. Applies `config.mail.from`
+   * if the message lacks one.
+   */
+  async send(message: Message): Promise<void>
+  /**
+   * Sync-send overload — constructs the `Mailable` subclass via the
+   * container (so `@inject()` deps resolve), calls `build(payload)`,
+   * then sends through the default transport. No queue hop; the
+   * caller's process does the work.
+   *
+   * For async / retry / dead-letter semantics, dispatch through the
+   * queue instead — `await queue.dispatch(WelcomeEmail, payload)`.
+   * Mailables ARE Jobs, so the queue's `Worker` handles them with no
+   * additional wiring beyond a `JobRegistry.register(WelcomeEmail)`.
+   */
+  async send<T extends MailableClass>(
+    MailableClass: T,
+    payload: MailablePayloadOf<T>,
+  ): Promise<void>
+  async send(arg1: Message | MailableClass, payload?: unknown): Promise<void> {
+    if (typeof arg1 === 'function') {
+      const message = await this.buildMailable(arg1, payload)
+      await this.via().send(this.applyDefaultFrom(message))
+      return
+    }
+    await this.via().send(this.applyDefaultFrom(arg1))
+  }
+
+  /**
+   * Resolve a transport by name. Pass nothing to get the default.
+   * Returned transport is cached — subsequent calls return the same
+   * instance.
+   */
+  via(name?: string): Transport {
+    const key = name ?? this.config.default
+    const cached = this.cache.get(key)
+    if (cached) return cached
+    const built = this.buildTransport(key)
+    this.cache.set(key, built)
+    return built
+  }
+
+  /**
+   * Close every cached transport. Best-effort — individual transport
+   * `close()` errors are swallowed so a misbehaving driver can't block
+   * shutdown.
+   */
+  async shutdown(): Promise<void> {
+    const open = [...this.cache.values()]
+    this.cache.clear()
+    await Promise.all(
+      open.map(async (t) => {
+        if (t.close === undefined) return
+        try {
+          await t.close()
+        } catch {
+          // Best-effort: never throw during shutdown.
+        }
+      }),
+    )
+  }
+
+  // ─── Internals ─────────────────────────────────────────────────────────────
+
+  private async buildMailable(MailableClass: MailableClass, payload: unknown): Promise<Message> {
+    if (this.container === undefined) {
+      throw new ConfigError(
+        'MailManager: send(MailableClass, payload) requires a Container — wire MailProvider instead of constructing MailManager directly.',
+      )
+    }
+    const mailable = this.container.make(MailableClass)
+    return mailable.build(payload as never)
+  }
+
+  private applyDefaultFrom(message: Message): Message {
+    if (message.from !== undefined) return message
+    if (this.config.from === undefined) return message
+    return { ...message, from: this.config.from }
+  }
+
+  private buildTransport(name: string): Transport {
+    const cfg = this.config.transports[name]
+    if (cfg === undefined) {
+      throw new ConfigError(`Mail: transport "${name}" is not defined in config.`)
+    }
+    switch (cfg.driver) {
+      case 'array':
+        return new ArrayTransport()
+      case 'log': {
+        const logger: Logger =
+          cfg.channel !== undefined
+            ? this.logManager.channel(cfg.channel)
+            : this.logManager.default()
+        return new LogTransport({
+          logger,
+          level: cfg.level,
+          includeBody: cfg.includeBody,
+        })
+      }
+      case 'resend':
+        return new ResendTransport({ apiKey: cfg.apiKey, endpoint: cfg.endpoint })
+      case 'sendgrid':
+        return new SendGridTransport({ apiKey: cfg.apiKey, endpoint: cfg.endpoint })
+      case 'mailgun':
+        return new MailgunTransport({
+          apiKey: cfg.apiKey,
+          domain: cfg.domain,
+          endpoint: cfg.endpoint,
+        })
+      case 'alibaba':
+        return new AlibabaDmTransport({
+          accessKeyId: cfg.accessKeyId,
+          accessKeySecret: cfg.accessKeySecret,
+          accountName: cfg.accountName,
+          endpoint: cfg.endpoint,
+          tagName: cfg.tagName,
+          clickTrace: cfg.clickTrace,
+        })
+    }
+  }
+
+  private validate(config: MailConfig): void {
+    if (config.transports[config.default] === undefined) {
+      throw new ConfigError(
+        `Mail: default transport "${config.default}" is not defined in transports.`,
+      )
+    }
+    const knownDrivers = new Set(['array', 'log', 'resend', 'sendgrid', 'mailgun', 'alibaba'])
+    for (const [name, cfg] of Object.entries(config.transports)) {
+      if (!knownDrivers.has(cfg.driver)) {
+        throw new ConfigError(
+          `Mail: transport "${name}" has unknown driver "${(cfg as { driver: string }).driver}".`,
+        )
+      }
+      if (
+        (cfg.driver === 'resend' || cfg.driver === 'sendgrid' || cfg.driver === 'mailgun') &&
+        !cfg.apiKey
+      ) {
+        throw new ConfigError(
+          `Mail: transport "${name}" (${cfg.driver}) requires a non-empty \`apiKey\`.`,
+        )
+      }
+      if (cfg.driver === 'mailgun' && !cfg.domain) {
+        throw new ConfigError(
+          `Mail: transport "${name}" (mailgun) requires a non-empty \`domain\`.`,
+        )
+      }
+      if (cfg.driver === 'alibaba') {
+        if (!cfg.accessKeyId || !cfg.accessKeySecret) {
+          throw new ConfigError(
+            `Mail: transport "${name}" (alibaba) requires \`accessKeyId\` and \`accessKeySecret\`.`,
+          )
+        }
+        if (!cfg.accountName) {
+          throw new ConfigError(
+            `Mail: transport "${name}" (alibaba) requires \`accountName\` — the verified DirectMail sender.`,
+          )
+        }
+      }
+    }
+  }
+}

package/src/mail_provider.ts

@@ -0,0 +1,58 @@
+/**
+ * `MailProvider` reads `config('mail')`, constructs a `MailManager`,
+ * and binds:
+ *   - `MailManager` (singleton) — the public mail surface.
+ *   - `'mail'` (string key, singleton) — alias resolving to the same
+ *     `MailManager`, so apps can `@inject('mail')` without importing
+ *     the class.
+ *
+ * Depends on `'config'` and `'logger'`, so `ConfigProvider` and
+ * `LoggerProvider` must be registered first. The provider's
+ * `shutdown()` runs `MailManager.shutdown()` to close every cached
+ * transport.
+ *
+ * @see docs/signal/api.md
+ */
+
+import {
+  type Application,
+  ConfigError,
+  ConfigRepository,
+  LogManager,
+  ServiceProvider,
+} from '@strav/kernel'
+import { type MailConfig, MailManager } from './mail_manager.ts'
+
+export class MailProvider extends ServiceProvider {
+  override readonly name = 'mail'
+  override readonly dependencies = ['config', 'logger']
+
+  override register(app: Application): void {
+    app.singleton(MailManager, (c) => {
+      const raw = c.resolve(ConfigRepository).get('mail')
+      if (raw === undefined || raw === null) {
+        throw new ConfigError(
+          'MailProvider: `config.mail` is missing. Add a `config/mail.ts` file (see docs/signal/README.md).',
+        )
+      }
+      return new MailManager(raw as MailConfig, c.resolve(LogManager), c)
+    })
+    app.singleton('mail', (c) => c.resolve(MailManager))
+  }
+
+  override async boot(app: Application): Promise<void> {
+    // Construct the manager now so config errors surface at boot —
+    // not on the first send call inside a request.
+    app.resolve(MailManager)
+  }
+
+  override async shutdown(app: Application): Promise<void> {
+    try {
+      if (!app.has(MailManager)) return
+      await app.resolve(MailManager).shutdown()
+    } catch {
+      // No manager was constructed (config missing / boot failed earlier) —
+      // nothing to clean up.
+    }
+  }
+}

package/src/mailable.ts

@@ -0,0 +1,107 @@
+/**
+ * `Mailable<TPayload>` — a typed `Job` that builds and sends a mail
+ * message.
+ *
+ * Apps subclass `Mailable`, set `static override jobName`, and implement
+ * `build(payload)` to produce a `Message`. The framework provides
+ * `handle()` — it calls `build(ctx.payload)` and forwards the result to
+ * `MailManager.send(message)`.
+ *
+ * Because `Mailable extends Job`, mailables participate in the full job
+ * lifecycle: retries, backoff, abort-aware shutdown, `failed()` hook,
+ * dead-letter via `strav_failed_jobs`. There is no separate
+ * `MailableRegistry` — mailables register with the same `JobRegistry`
+ * the rest of the app uses, and dispatch the same way:
+ *
+ *     await queue.dispatch(WelcomeEmail, { userId: '01J...' })
+ *
+ * For sync sends inside a request (no queue hop), apps call either
+ * `MailManager.send(WelcomeEmail, payload)` (the overload constructs
+ * the Mailable via the container, builds, sends) or — if the message
+ * is already built — `MailManager.send(message)` directly.
+ *
+ * Dependency injection
+ *   The base class declares `@inject()` and a constructor taking
+ *   `MailManager`. Subclasses without additional deps inherit both
+ *   shape and metadata — `container.make(WelcomeEmail)` resolves
+ *   `MailManager` via the inherited `@inject()` reflection.
+ *
+ *   Subclasses with extra deps redeclare:
+ *
+ *     @inject()
+ *     class WelcomeEmail extends Mailable<{ userId: string }> {
+ *       static override readonly jobName = 'mail.welcome'
+ *       constructor(
+ *         mail: MailManager,
+ *         private readonly users: UserRepository,
+ *       ) { super(mail) }
+ *       async build({ userId }) {
+ *         const user = await this.users.findOrFail(userId)
+ *         return { to: user.email, subject: 'Welcome', text: `Hi ${user.name}` }
+ *       }
+ *     }
+ *
+ * Payload shape
+ *   `TPayload` must round-trip through JSON — same constraint as any
+ *   `Job` payload. The Worker `JSON.stringify`s on dispatch and
+ *   `JSON.parse`s on pick-up; non-serialisable values silently corrupt.
+ */
+
+import { inject } from '@strav/kernel'
+import { Job, type JobContext } from '@strav/queue'
+// Value import required — `@inject()` reads constructor paramtypes via
+// `emitDecoratorMetadata`, which erases `import type` references to
+// `Object`. Container then can't resolve them. This is one-way:
+// `mail_manager.ts` imports types from this file only, so there's no
+// runtime cycle. Biome's useImportType lint suggests the wrong fix.
+// biome-ignore lint/style/useImportType: value import is load-bearing for @inject() metadata emission
+import { MailManager } from './mail_manager.ts'
+import type { Message } from './message.ts'
+
+@inject()
+export abstract class Mailable<TPayload = unknown> extends Job<TPayload> {
+  constructor(protected readonly mail: MailManager) {
+    super()
+  }
+
+  /**
+   * Construct the `Message` to send. Called once per attempt. Receives
+   * the dispatched payload (JSON-deserialized when running under a
+   * persistent queue driver).
+   *
+   * May read async resources — the `Job` lifecycle awaits it. Throwing
+   * triggers the standard retry path; consider whether the thrown
+   * condition is transient (give up after `maxAttempts`) or permanent
+   * (override `maxAttempts = 1` so it dead-letters immediately).
+   */
+  abstract build(payload: TPayload): Message | Promise<Message>
+
+  /**
+   * Default handler — builds the message, sends it through the default
+   * transport. Subclasses can override (e.g. to route through a named
+   * transport via `this.mail.via('priority').send(message)`), but the
+   * default covers the common case.
+   */
+  override async handle(context: JobContext<TPayload>): Promise<void> {
+    const message = await this.build(context.payload)
+    await this.mail.send(message)
+  }
+}
+
+/**
+ * Constructor-shape for any `Mailable` subclass — used by
+ * `MailManager.send(MailableClass, payload)` typing. Mirrors
+ * `JobClass` from `@strav/queue` but constrained to `Mailable`.
+ */
+export interface MailableClass<TPayload = unknown> {
+  // biome-ignore lint/suspicious/noExplicitAny: matches kernel `Constructor<T>` variance — subclasses have arbitrary constructor params
+  new (...args: any[]): Mailable<TPayload>
+  readonly jobName: string
+}
+
+/**
+ * Extract the payload type from a `MailableClass` reference. Useful for
+ * typed wrappers that take a `MailableClass` and need to type their
+ * `payload` parameter against it.
+ */
+export type MailablePayloadOf<T> = T extends MailableClass<infer P> ? P : never

package/src/message.ts

@@ -0,0 +1,72 @@
+/**
+ * `Message` — the wire-shape every Strav `Transport` accepts.
+ *
+ * Plain data, deliberately. The same `Message` literal a test handler
+ * constructs by hand is the same shape a future `Mailable.build()` will
+ * return — no driver-specific fields, no transport-specific options.
+ * Transports translate this into their own provider format (SMTP
+ * envelope, Resend JSON, SendGrid v3, etc.) on `send()`.
+ *
+ * Recipients
+ *   `to` / `cc` / `bcc` / `replyTo` accept either a bare email string
+ *   (`'alice@example.com'`) or a `{ email, name? }` object. A list of
+ *   either is fine — `to: ['a@x', { email: 'b@x', name: 'Bob' }]` is
+ *   legal. Use the structured form when the display name matters.
+ *
+ * Body
+ *   At least one of `html` / `text` must be present. Transports that
+ *   support multipart will send both when both are set; transports that
+ *   only support one degrade as documented in the driver's notes.
+ *
+ * Headers + attachments
+ *   `headers` is a flat string-to-string map; transports apply provider
+ *   constraints (e.g. SMTP rejects newlines). `attachments` carries an
+ *   optional list — see `MessageAttachment`. Per-driver size limits
+ *   apply; transports throw on oversize content.
+ */
+
+export interface MailAddress {
+  /** RFC 5322 addr-spec. Validated by the transport, not here. */
+  email: string
+  /** Optional display name. Joined as `"Name" <email>` by transports that support it. */
+  name?: string
+}
+
+/** Either a bare email or a `{ email, name? }` pair. */
+export type MailRecipient = string | MailAddress
+
+/**
+ * File attached to a message. `content` is the raw bytes; pass a
+ * `Uint8Array` for binary data or a UTF-8 `string` for text. When
+ * passing a string that's actually a base64-encoded payload, set
+ * `encoding: 'base64'` so transports decode it before transmission.
+ */
+export interface MessageAttachment {
+  filename: string
+  content: string | Uint8Array
+  /** Defaults to `application/octet-stream` if omitted; transports may sniff from filename. */
+  contentType?: string
+  /** How `content` is encoded when it's a string. Defaults to `'utf-8'`. */
+  encoding?: 'utf-8' | 'base64'
+}
+
+export interface Message {
+  to: MailRecipient | MailRecipient[]
+  /**
+   * Optional. When omitted, `MailManager.send` substitutes `config.mail.from`
+   * before handing the message to the transport. If neither is set, the
+   * transport throws — there is no implicit "MAIL FROM:" guess.
+   */
+  from?: MailRecipient
+  cc?: MailRecipient | MailRecipient[]
+  bcc?: MailRecipient | MailRecipient[]
+  replyTo?: MailRecipient | MailRecipient[]
+  subject: string
+  /** HTML body. At least one of `html` / `text` is required. */
+  html?: string
+  /** Plain-text body. At least one of `html` / `text` is required. */
+  text?: string
+  /** Flat header map; values must be ASCII single-line strings. */
+  headers?: Record<string, string>
+  attachments?: MessageAttachment[]
+}

package/src/transport.ts

@@ -0,0 +1,34 @@
+/**
+ * `Transport` — the per-driver contract every mail backend implements.
+ *
+ * `MailManager` holds a name → `Transport` map (Resend, SMTP, log,
+ * array, …) and delegates `send()` to the one named in `config.mail.default`
+ * (or whichever the caller passed to `via()`). Drivers translate the
+ * `Message` shape into their provider format and report transport
+ * errors by throwing.
+ *
+ * Lifecycle
+ *   `close()` is optional. Implementations that hold long-lived
+ *   resources (a pooled SMTP connection, a kept-alive HTTPS agent) use
+ *   it to flush and release; the `MailManager.shutdown()` path awaits
+ *   every cached transport's `close()` best-effort.
+ *
+ * Authoring a new driver
+ *   1. Class implementing `Transport`.
+ *   2. Constructor takes its config shape — never the global `MailConfig`.
+ *   3. `send()` rejects with an `Error` subclass that carries enough
+ *      context for the queue Worker's `failed()` hook to log usefully
+ *      (provider, status, attempted recipients).
+ *   4. Register the driver in `MailManager.buildTransport` (alpha-N
+ *      bumps; once 1.0 ships, a `MailTransportRegistry` lets apps
+ *      register additional drivers without forking).
+ */
+
+import type { Message } from './message.ts'
+
+export interface Transport {
+  /** Transmit `message`. Throws on transport-level failure. */
+  send(message: Message): Promise<void>
+  /** Optional cleanup. Called once on manager shutdown. Must not throw. */
+  close?(): void | Promise<void>
+}

package/src/transport_error.ts

@@ -0,0 +1,31 @@
+/**
+ * `MailTransportError` — typed error raised by mail `Transport`
+ * implementations when a `send()` fails at the transport level
+ * (network / HTTP non-2xx / provider rejection).
+ *
+ * The Worker's `failed(ctx)` hook receives the thrown error as
+ * `ctx.error`, so carrying provider + status + retry-hint in the
+ * `context` payload makes log records and dead-letter rows actionable
+ * without parsing exception strings.
+ *
+ *   throw new MailTransportError('Resend rejected the request', {
+ *     context: {
+ *       provider: 'resend',
+ *       status: 422,
+ *       retryable: false,
+ *       providerError: { name: 'validation_error', message: '...' },
+ *     },
+ *   })
+ *
+ * `status` on the error itself is fixed at 502 — this is a Strav
+ * server-side surface ("an upstream mail provider failed"). The
+ * provider's HTTP status lives under `context.status`.
+ */
+
+import { StravError, type StravErrorOptions } from '@strav/kernel'
+
+export class MailTransportError extends StravError {
+  constructor(message: string, options: StravErrorOptions = {}) {
+    super(message, { code: 'mail-transport-error', status: 502 }, options)
+  }
+}