@strav/mail 1.0.0-alpha.36 → 1.0.0-alpha.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/mail",
-  "version": "1.0.0-alpha.36",
+  "version": "1.0.0-alpha.38",
   "description": "Strav signal layer — mail (core + array/log transports + Mailable + queue-dispatch); notifications + SSE + broadcast follow in later slices",
   "type": "module",
   "main": "./src/index.ts",
@@ -19,8 +19,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/kernel": "1.0.0-alpha.36",
-    "@strav/queue": "1.0.0-alpha.36"
+    "@strav/kernel": "1.0.0-alpha.38",
+    "@strav/queue": "1.0.0-alpha.38"
   },
   "peerDependencies": {
     "@types/bun": ">=1.3.14"

package/src/index.ts

@@ -4,8 +4,10 @@
 //   - 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).
+//   - Transports: `ArrayTransport` (in-memory recorder for tests),
+//     `LogTransport` (writes to a `Logger` channel — local-dev),
+//     `ResendTransport`, `SendGridTransport`, `MailgunTransport`,
+//     `PostmarkTransport`, `AlibabaDmTransport`.
 //   - `MailManager` — multi-transport orchestration with `via(name?)`,
 //     default-`from` substitution, lazy/cached transport construction,
 //     and a Mailable-aware `send(MailableClass, payload)` overload.
@@ -49,6 +51,10 @@ export {
 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 {
+  PostmarkTransport,
+  type PostmarkTransportOptions,
+} from './transports/postmark_transport.ts'
 export { ResendTransport, type ResendTransportOptions } from './transports/resend_transport.ts'
 export {
   SendGridTransport,

package/src/mail_manager.ts

@@ -37,6 +37,7 @@ 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 { PostmarkTransport } from './transports/postmark_transport.ts'
 import { ResendTransport } from './transports/resend_transport.ts'
 import { SendGridTransport } from './transports/sendgrid_transport.ts'
 
@@ -88,6 +89,20 @@ interface MailgunTransportConfig {
   endpoint?: string
 }
 
+interface PostmarkTransportConfig {
+  driver: 'postmark'
+  /** Postmark Server Token (per-server). NOT the Account token. */
+  serverToken: string
+  /** Override the base URL — defaults to `https://api.postmarkapp.com`. */
+  endpoint?: string
+  /**
+   * Optional `MessageStream` ID. When omitted, Postmark routes through
+   * the server's default transactional stream. Set this for broadcast
+   * or custom-stream slugs.
+   */
+  messageStream?: string
+}
+
 interface AlibabaDmTransportConfig {
   driver: 'alibaba'
   /** Alibaba Cloud AccessKey ID. */
@@ -120,6 +135,7 @@ export type MailTransportConfig =
   | ResendTransportConfig
   | SendGridTransportConfig
   | MailgunTransportConfig
+  | PostmarkTransportConfig
   | AlibabaDmTransportConfig
 
 export interface MailConfig {
@@ -267,6 +283,12 @@ export class MailManager {
           domain: cfg.domain,
           endpoint: cfg.endpoint,
         })
+      case 'postmark':
+        return new PostmarkTransport({
+          serverToken: cfg.serverToken,
+          endpoint: cfg.endpoint,
+          messageStream: cfg.messageStream,
+        })
       case 'alibaba':
         return new AlibabaDmTransport({
           accessKeyId: cfg.accessKeyId,
@@ -285,7 +307,15 @@ export class MailManager {
         `Mail: default transport "${config.default}" is not defined in transports.`,
       )
     }
-    const knownDrivers = new Set(['array', 'log', 'resend', 'sendgrid', 'mailgun', 'alibaba'])
+    const knownDrivers = new Set([
+      'array',
+      'log',
+      'resend',
+      'sendgrid',
+      'mailgun',
+      'postmark',
+      'alibaba',
+    ])
     for (const [name, cfg] of Object.entries(config.transports)) {
       if (!knownDrivers.has(cfg.driver)) {
         throw new ConfigError(
@@ -305,6 +335,11 @@ export class MailManager {
           `Mail: transport "${name}" (mailgun) requires a non-empty \`domain\`.`,
         )
       }
+      if (cfg.driver === 'postmark' && !cfg.serverToken) {
+        throw new ConfigError(
+          `Mail: transport "${name}" (postmark) requires a non-empty \`serverToken\`.`,
+        )
+      }
       if (cfg.driver === 'alibaba') {
         if (!cfg.accessKeyId || !cfg.accessKeySecret) {
           throw new ConfigError(

package/src/message.ts

@@ -40,6 +40,14 @@ export type MailRecipient = string | MailAddress
  * `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.
+ *
+ * Inline images: set `disposition: 'inline'` and assign a `cid` (Content-ID)
+ * to reference the part from HTML — e.g. `cid: 'logo'` pairs with
+ * `<img src="cid:logo">`. Transports map this to their provider's
+ * inline-part field (Resend `content_id` + `inline_content`, SendGrid
+ * `disposition: "inline"` + `content_id`, Mailgun `inline` part,
+ * Postmark `ContentID` with `cid:` prefix). When omitted, the attachment
+ * is sent as a regular attachment.
  */
 export interface MessageAttachment {
   filename: string
@@ -48,6 +56,14 @@ export interface MessageAttachment {
   contentType?: string
   /** How `content` is encoded when it's a string. Defaults to `'utf-8'`. */
   encoding?: 'utf-8' | 'base64'
+  /**
+   * Content-ID for inline references. Bare token without angle brackets
+   * (e.g. `'logo'`, not `'<logo>'`) — transports add provider-specific
+   * decoration. Required when `disposition: 'inline'`; ignored otherwise.
+   */
+  cid?: string
+  /** Defaults to `'attachment'`. Use `'inline'` for images referenced via `cid:` in HTML. */
+  disposition?: 'attachment' | 'inline'
 }
 
 export interface Message {

package/src/transports/mailgun_transport.ts

@@ -93,7 +93,16 @@ export class MailgunTransport implements Transport {
 
     if (message.attachments !== undefined) {
       for (const a of message.attachments) {
-        form.append('attachment', attachmentToBlob(a), a.filename)
+        // Mailgun routes inline parts to the `inline` form field instead
+        // of `attachment`. The filename becomes the Content-ID — HTML
+        // bodies reference it as `<img src="cid:{filename}">` UNLESS an
+        // explicit `cid` is supplied, in which case we send the cid as
+        // the field filename so it survives as the Content-ID header.
+        if (a.disposition === 'inline') {
+          form.append('inline', attachmentToBlob(a), a.cid ?? a.filename)
+        } else {
+          form.append('attachment', attachmentToBlob(a), a.filename)
+        }
       }
     }
 

package/src/transports/postmark_transport.ts

@@ -0,0 +1,188 @@
+/**
+ * `PostmarkTransport` — sends mail via the Postmark HTTP API.
+ *
+ *   POST {endpoint}/email
+ *   X-Postmark-Server-Token: {serverToken}
+ *   Accept: application/json
+ *   Content-Type: application/json
+ *
+ *   {
+ *     From, To, Cc?, Bcc?, ReplyTo?,
+ *     Subject, HtmlBody?, TextBody?,
+ *     Headers?: [{ Name, Value }],
+ *     Attachments?: [{ Name, Content (base64), ContentType, ContentID? }],
+ *     MessageStream?,
+ *   }
+ *
+ * Postmark uses PascalCase field names, a list-of-`{Name,Value}` headers
+ * shape (not a flat map), and recipients as comma-separated RFC 5322
+ * strings. Inline images set `ContentID` with a `cid:` prefix — HTML
+ * bodies reference them via `<img src="cid:{cid}">`.
+ *
+ * Streams: Postmark splits transactional vs broadcast into named
+ * "message streams". When unset, Postmark routes through the server's
+ * default transactional stream. Set `messageStream` on the transport
+ * for broadcasts.
+ *
+ * Failure model: any non-2xx response throws `MailTransportError` with
+ * `provider: 'postmark'` and the parsed error body. Postmark returns
+ * a numeric `ErrorCode` field in the body — preserved verbatim under
+ * `context.providerError` for callers that switch on it.
+ *
+ * @see https://postmarkapp.com/developer/api/email-api
+ */
+
+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 PostmarkTransportOptions {
+  /**
+   * Postmark Server Token (per-server). Pull from env in `config/mail.ts`;
+   * never hard-code. NOT the Account token — Account tokens are for the
+   * admin API, not for sending.
+   */
+  serverToken: string
+  /**
+   * Base URL of the Postmark API. Defaults to `https://api.postmarkapp.com`.
+   * Override for mocked endpoints in tests.
+   */
+  endpoint?: string
+  /**
+   * Optional `MessageStream` ID. When omitted, Postmark routes through
+   * the server's default transactional stream. Set this for broadcast
+   * streams (e.g. `'broadcast'` or a custom stream slug).
+   */
+  messageStream?: string
+  /** Custom `fetch` for tests. */
+  fetch?: typeof fetch
+}
+
+interface PostmarkAttachment {
+  Name: string
+  Content: string
+  ContentType: string
+  ContentID?: string
+}
+
+interface PostmarkHeader {
+  Name: string
+  Value: string
+}
+
+interface PostmarkRequestBody {
+  From: string
+  To: string
+  Cc?: string
+  Bcc?: string
+  ReplyTo?: string
+  Subject: string
+  HtmlBody?: string
+  TextBody?: string
+  Headers?: PostmarkHeader[]
+  Attachments?: PostmarkAttachment[]
+  MessageStream?: string
+}
+
+export class PostmarkTransport implements Transport {
+  private readonly serverToken: string
+  private readonly endpoint: string
+  private readonly messageStream: string | undefined
+  private readonly fetchFn: typeof fetch
+
+  constructor(opts: PostmarkTransportOptions) {
+    this.serverToken = opts.serverToken
+    this.endpoint = (opts.endpoint ?? 'https://api.postmarkapp.com').replace(/\/$/, '')
+    this.messageStream = opts.messageStream
+    this.fetchFn = opts.fetch ?? fetch
+  }
+
+  async send(message: Message): Promise<void> {
+    if (message.from === undefined) {
+      throw new MailTransportError('Postmark requires `from` — none on the message or default.', {
+        context: { provider: 'postmark', retryable: false },
+      })
+    }
+
+    const body: PostmarkRequestBody = {
+      From: toRfc5322(message.from),
+      To: mapRecipients(message.to, toRfc5322).join(', '),
+      Subject: message.subject,
+    }
+    if (message.cc !== undefined) body.Cc = mapRecipients(message.cc, toRfc5322).join(', ')
+    if (message.bcc !== undefined) body.Bcc = mapRecipients(message.bcc, toRfc5322).join(', ')
+    if (message.replyTo !== undefined) {
+      // Postmark accepts multiple Reply-To via a comma-separated string in
+      // the single `ReplyTo` field — matches RFC 5322's address-list rules.
+      body.ReplyTo = mapRecipients(message.replyTo, toRfc5322).join(', ')
+    }
+    if (message.html !== undefined) body.HtmlBody = message.html
+    if (message.text !== undefined) body.TextBody = message.text
+    if (message.headers !== undefined) {
+      body.Headers = Object.entries(message.headers).map(([Name, Value]) => ({ Name, Value }))
+    }
+    if (message.attachments !== undefined && message.attachments.length > 0) {
+      body.Attachments = message.attachments.map((a) => {
+        const out: PostmarkAttachment = {
+          Name: a.filename,
+          Content: attachmentToBase64(a),
+          // Postmark requires ContentType — fall back to the generic
+          // octet-stream when the caller didn't supply one.
+          ContentType: a.contentType ?? 'application/octet-stream',
+        }
+        // Inline parts: Postmark expects `ContentID` with a `cid:` prefix.
+        // Sending it as a bare token without the prefix is a common
+        // integration mistake — Postmark won't reject it but the inline
+        // reference from the HTML body won't resolve.
+        if (a.disposition === 'inline' && a.cid !== undefined) out.ContentID = `cid:${a.cid}`
+        return out
+      })
+    }
+    if (this.messageStream !== undefined) body.MessageStream = this.messageStream
+
+    let response: Response
+    try {
+      response = await this.fetchFn(`${this.endpoint}/email`, {
+        method: 'POST',
+        headers: {
+          accept: 'application/json',
+          'content-type': 'application/json',
+          'x-postmark-server-token': this.serverToken,
+        },
+        body: JSON.stringify(body),
+      })
+    } catch (cause) {
+      throw new MailTransportError(
+        `Postmark send failed at the network layer: ${(cause as Error).message ?? String(cause)}`,
+        { context: { provider: 'postmark', 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(
+      `Postmark rejected the send (HTTP ${response.status} ${response.statusText}).`,
+      {
+        context: {
+          provider: 'postmark',
+          status: response.status,
+          retryable: isRetryableStatus(response.status),
+          providerError,
+        },
+      },
+    )
+  }
+}

package/src/transports/resend_transport.ts

@@ -60,7 +60,12 @@ interface ResendRequestBody {
   bcc?: string[]
   reply_to?: string | string[]
   headers?: Record<string, string>
-  attachments?: Array<{ filename: string; content: string; content_type?: string }>
+  attachments?: Array<{
+    filename: string
+    content: string
+    content_type?: string
+    content_id?: string
+  }>
 }
 
 export class ResendTransport implements Transport {
@@ -98,11 +103,22 @@ export class ResendTransport implements Transport {
     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 } = {
+        const out: {
+          filename: string
+          content: string
+          content_type?: string
+          content_id?: string
+        } = {
           filename: a.filename,
           content: attachmentToBase64(a),
         }
         if (a.contentType !== undefined) out.content_type = a.contentType
+        // Resend signals an inline part by populating `content_id` — the
+        // HTML body references it via `<img src="cid:{cid}">`. We only
+        // emit `content_id` when `disposition: 'inline'` is set, so that
+        // a stray `cid` field on a regular attachment doesn't accidentally
+        // flip the part to inline.
+        if (a.disposition === 'inline' && a.cid !== undefined) out.content_id = a.cid
         return out
       })
     }

package/src/transports/sendgrid_transport.ts

@@ -61,7 +61,8 @@ interface SendGridAttachment {
   content: string
   filename: string
   type?: string
-  disposition: 'attachment'
+  disposition: 'attachment' | 'inline'
+  content_id?: string
 }
 
 interface SendGridRequestBody {
@@ -130,9 +131,10 @@ export class SendGridTransport implements Transport {
         const out: SendGridAttachment = {
           content: attachmentToBase64(a),
           filename: a.filename,
-          disposition: 'attachment',
+          disposition: a.disposition ?? 'attachment',
         }
         if (a.contentType !== undefined) out.type = a.contentType
+        if (a.disposition === 'inline' && a.cid !== undefined) out.content_id = a.cid
         return out
       })
     }