@coderize/email 0.0.0-stage → 0.1.1

package/mailer.js

@@ -0,0 +1,154 @@
+import { SendEmailCommand, SESv2Client } from '@aws-sdk/client-sesv2'
+
+import { normalizeMessage } from './message.js'
+import { renderRaw } from './mime.js'
+import { isTransientAwsError, SendError } from './sendError.js'
+
+const LOG_ONLY = 'EMAIL NOT SENT (log only: set EMAIL_PROVIDER=ses to send)'
+const PREVIEW_CHARS = 800
+
+/**
+ * The SendEmail input for a normalised message: Simple content, or Raw when there are attachments.
+ * @param {import('./message.js').NormalMessage} m
+ */
+export function sesInput(m) {
+  const input = {
+    FromEmailAddress: m.from,
+    Destination: {
+      ToAddresses: m.to,
+      ...(m.cc.length ? { CcAddresses: m.cc } : {}),
+      // The envelope is the only place Bcc goes, on both paths.
+      ...(m.bcc.length ? { BccAddresses: m.bcc } : {})
+    },
+    ...(m.configurationSet ? { ConfigurationSetName: m.configurationSet } : {})
+  }
+
+  if (m.attachments.length) {
+    // Reply-To and the custom headers are inside the raw message.
+    return { ...input, Content: { Raw: { Data: renderRaw(m) } } }
+  }
+
+  return {
+    ...input,
+    ...(m.replyTo.length ? { ReplyToAddresses: m.replyTo } : {}),
+    Content: {
+      Simple: {
+        Subject: { Data: m.subject, Charset: 'UTF-8' },
+        Body: {
+          ...(m.text ? { Text: { Data: m.text, Charset: 'UTF-8' } } : {}),
+          ...(m.html ? { Html: { Data: m.html, Charset: 'UTF-8' } } : {})
+        },
+        ...(m.headers.length ? { Headers: m.headers.map(([Name, Value]) => ({ Name, Value })) } : {})
+      }
+    }
+  }
+}
+
+/**
+ * What an AWS error says, minus anything that names a recipient: SES's MessageRejected quotes addresses,
+ * while AccessDenied quotes the ARN that is missing from the IAM policy, which is the part worth keeping.
+ * @param {unknown} error
+ */
+function errorFacts(error) {
+  const e = /** @type {any} */ (error)
+  return {
+    error: e?.name,
+    statusCode: e?.$metadata?.httpStatusCode,
+    requestId: e?.$metadata?.requestId,
+    detail: String(e?.message ?? '')
+      .replace(/[^\s<>()[\]"',;:]+@[^\s<>()[\]"',;:]+/g, '[address]')
+      .slice(0, 300)
+  }
+}
+
+/** @param {import('./message.js').NormalMessage} m */
+const recipientCount = (m) => m.to.length + m.cc.length + m.bcc.length
+
+/**
+ * A mailer for one app. SES only when `EMAIL_PROVIDER` is `ses`; anything else logs the message instead
+ * of sending it, at error level in production (where it means mail is not going out) and at info level
+ * with a body preview elsewhere.
+ *
+ * @param {object} [options]
+ * @param {string} [options.from] the app's default From, e.g. `process.env.EMAIL_FROM ?? 'App <no-reply@app.com>'`
+ * @param {string} [options.configurationSet] SES configuration set to name on every send; none by default
+ * @param {{ send: (command: SendEmailCommand) => Promise<{ MessageId?: string }> }} [options.client] an SESv2Client, injected in tests
+ * @param {string} [options.region] defaults to `AWS_REGION`, then us-east-1
+ * @param {{ info: Function, error: Function }} [options.logger] pino (`app.log`) or console, the default
+ * @param {Record<string, string | undefined>} [options.env] defaults to `process.env`; read once, here
+ */
+export function createMailer({ from, configurationSet, client, region, logger = console, env = process.env } = {}) {
+  const enabled = env.EMAIL_PROVIDER === 'ses'
+  const production = env.NODE_ENV === 'production'
+  let ses = client
+  const sesClient = () => (ses ??= new SESv2Client({ region: region || env.AWS_REGION || 'us-east-1' }))
+  const defaults = { from, configurationSet }
+
+  /**
+   * @param {import('./message.js').NormalMessage} m
+   */
+  function logOnly(m) {
+    if (production) {
+      logger.error({ recipients: recipientCount(m), subject: m.subject }, LOG_ONLY)
+    } else {
+      logger.info(
+        {
+          to: m.to,
+          ...(m.cc.length ? { cc: m.cc } : {}),
+          ...(m.bcc.length ? { bcc: m.bcc } : {}),
+          subject: m.subject,
+          ...(m.attachments.length ? { attachments: m.attachments.map((a) => a.filename) } : {}),
+          body: (m.text ?? m.html ?? '').slice(0, PREVIEW_CHARS)
+        },
+        LOG_ONLY
+      )
+    }
+    return { status: /** @type {const} */ ('logged'), id: null }
+  }
+
+  /**
+   * Sends one message. Resolves `{ status: 'sent', id }` (id is SES's MessageId), `{ status: 'logged',
+   * id: null }` when EMAIL_PROVIDER is not ses, or `{ status: 'skipped', id: null }` when `to` is empty.
+   * Throws a SendError when the message did not go out, after logging it.
+   * @param {object} message
+   */
+  async function send(message) {
+    let m
+    try {
+      m = normalizeMessage(message, defaults)
+    } catch (err) {
+      logger.error({ kind: 'permanent', reason: /** @type {Error} */ (err).message }, 'email not sent')
+      throw err
+    }
+    if (!m) return { status: /** @type {const} */ ('skipped'), id: null }
+    if (!enabled) return logOnly(m)
+
+    try {
+      const result = await sesClient().send(new SendEmailCommand(sesInput(m)))
+      // Production logs carry no addresses (some apps show their logs in an admin viewer); dev keeps them.
+      const who = production ? { recipients: recipientCount(m) } : { to: m.to }
+      logger.info({ messageId: result.MessageId, ...who, subject: m.subject }, 'email sent')
+      return { status: /** @type {const} */ ('sent'), id: result.MessageId ?? null }
+    } catch (cause) {
+      const kind = isTransientAwsError(cause) ? 'transient' : 'permanent'
+      logger.error({ kind, ...errorFacts(cause), recipients: recipientCount(m), subject: m.subject }, 'email not sent')
+      throw new SendError('Email not sent', kind, { cause })
+    }
+  }
+
+  /**
+   * `send()` that never throws: `{ ok: true, status, id, error: null }`, or `{ ok: false, status:
+   * 'failed', id: null, error }` with the SendError. The failure is already logged.
+   * @param {object} message
+   */
+  async function trySend(message) {
+    try {
+      return { ok: true, ...(await send(message)), error: null }
+    } catch (err) {
+      const error = err instanceof SendError ? err : new SendError('Email not sent', 'permanent', { cause: err })
+      return { ok: false, status: /** @type {const} */ ('failed'), id: null, error }
+    }
+  }
+
+  return { mode: enabled ? 'ses' : 'log', send, trySend }
+}

package/message.js

@@ -0,0 +1,245 @@
+/*
+  Turns what a caller passes to send() into one checked shape, or refuses it with a permanent SendError.
+  Both paths (Simple and Raw) and the log transport read only the result, so a message that would fail in
+  production fails the same way in development.
+
+  Refusal messages name the field, never its value: they end up in logs, and the values are addresses
+  and content.
+*/
+import { encodedWords, headerValue, NEEDS_ENCODING } from './encode.js'
+import { SendError } from './sendError.js'
+
+/**
+ * @typedef {object} NormalMessage
+ * @property {string} from
+ * @property {string[]} to
+ * @property {string[]} cc
+ * @property {string[]} bcc
+ * @property {string[]} replyTo
+ * @property {string} subject
+ * @property {string | undefined} text
+ * @property {string | undefined} html
+ * @property {Array<[string, string]>} headers
+ * @property {Array<{ filename: string, contentType: string, content: Buffer }>} attachments
+ * @property {string | undefined} configurationSet
+ */
+
+const invalid = (reason) => new SendError(`Email not sent: ${reason}`, 'permanent')
+
+// What we write ourselves, on one path or the other. A custom header with one of these names would
+// either be dropped by SES or give the message two of them.
+const RESERVED_HEADERS = new Set([
+  'bcc',
+  'cc',
+  'content-disposition',
+  'content-transfer-encoding',
+  'content-type',
+  'from',
+  'mime-version',
+  'reply-to',
+  'subject',
+  'to'
+])
+
+// RFC 5322 field name: printable ASCII except the colon.
+const HEADER_NAME = /^[!-9;-~]+$/
+// The addr-spec only, ASCII: no spaces, no list separators, no brackets or quotes.
+const ADDR_SPEC = /^[!#-'*+\-.-9=?A-Z^-~]+@[A-Za-z0-9.-]+$/
+// A display name that needs no quoting: atext and spaces.
+const PLAIN_NAME = /^[A-Za-z0-9!#$%&'*+\-/=?^_`{|}~ ]+$/
+const CONFIGURATION_SET = /^[A-Za-z0-9_-]{1,64}$/
+const MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/
+
+const TYPES = {
+  csv: 'text/csv',
+  gif: 'image/gif',
+  html: 'text/html',
+  ics: 'text/calendar',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  json: 'application/json',
+  pdf: 'application/pdf',
+  png: 'image/png',
+  svg: 'image/svg+xml',
+  txt: 'text/plain',
+  webp: 'image/webp',
+  xml: 'application/xml',
+  zip: 'application/zip'
+}
+
+/**
+ * One address, ready for a header and for SES's address fields: `Name <addr>` or a bare `addr`. A
+ * display name with specials is quoted; one with non-ASCII becomes encoded-words, which SES requires
+ * in FromEmailAddress and the destination lists too.
+ * @param {string} input
+ * @param {string} field where it came from, for the refusal message
+ * @returns {string}
+ */
+export function formatAddress(input, field) {
+  const raw = input.trim()
+  if (/[\r\n]/.test(raw)) throw invalid(`${field} contains a line break`)
+  const bracketed = /^(.*)<([^<>]*)>$/s.exec(raw)
+  const addr = (bracketed ? bracketed[2] : raw).trim()
+  if (!ADDR_SPEC.test(addr)) throw invalid(`${field} is not a single email address`)
+
+  let name = bracketed ? bracketed[1].trim() : ''
+  if (name.length >= 2 && name.startsWith('"') && name.endsWith('"')) {
+    name = name.slice(1, -1).replace(/\\(.)/g, '$1')
+  }
+  if (!name) return addr
+  if (NEEDS_ENCODING.test(name)) return `${encodedWords(name, ' ')} <${addr}>`
+  if (PLAIN_NAME.test(name)) return `${name} <${addr}>`
+  return `"${name.replace(/["\\]/g, '\\$&')}" <${addr}>`
+}
+
+/**
+ * `to`, `cc`, `bcc` or `replyTo`: one address or a flat list. Empty entries are dropped. A nested list
+ * is refused rather than flattened, because it means a wrapper somewhere wrapped a list again (icrotary
+ * lost 11 raffle notifications that way).
+ * @param {unknown} value
+ * @param {string} field
+ * @returns {string[]}
+ */
+function addressList(value, field) {
+  if (value === undefined || value === null || value === '') return []
+  if (typeof value === 'string') return [formatAddress(value, field)]
+  if (!Array.isArray(value)) throw invalid(`${field} must be an address or a list of addresses`)
+  const out = []
+  value.forEach((entry, i) => {
+    if (Array.isArray(entry)) throw invalid(`${field} is a nested list: pass a flat list of addresses`)
+    if (entry === undefined || entry === null || entry === '') return
+    if (typeof entry !== 'string') throw invalid(`${field}[${i}] is not a string`)
+    out.push(formatAddress(entry, `${field}[${i}]`))
+  })
+  return out
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} field
+ * @returns {string | undefined}
+ */
+function bodyPart(value, field) {
+  if (value === undefined || value === null || value === '') return undefined
+  if (typeof value !== 'string') throw invalid(`${field} must be a string`)
+  return value
+}
+
+/**
+ * @param {unknown} headers
+ * @returns {Array<[string, string]>}
+ */
+function headerList(headers) {
+  if (headers === undefined || headers === null) return []
+  if (typeof headers !== 'object' || Array.isArray(headers)) {
+    throw invalid('headers must be an object of header names to values')
+  }
+  return Object.entries(headers).map(([name, value]) => {
+    if (!HEADER_NAME.test(name)) throw invalid(`header name ${JSON.stringify(name)} is not a valid field name`)
+    if (RESERVED_HEADERS.has(name.toLowerCase())) {
+      throw invalid(`header ${name} is set by @coderize/email: use the message field instead`)
+    }
+    if (typeof value !== 'string' && typeof value !== 'number') throw invalid(`header ${name} must be a string`)
+    const text = String(value)
+    if (/[\r\n]/.test(text)) throw invalid(`header ${name} contains a line break`)
+    return [name, headerValue(text)]
+  })
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function cleanFilename(value) {
+  if (typeof value !== 'string') return ''
+  // Control characters out (a tab or CR would break the header line), then only the last path segment.
+  const printable = [...value].filter((c) => c >= ' ' && c !== '\x7f').join('')
+  return (printable.split(/[/\\]/).pop() ?? '').trim()
+}
+
+/**
+ * @param {unknown} attachment
+ * @param {number} i
+ */
+function attachmentPart(attachment, i) {
+  const field = `attachments[${i}]`
+  if (!attachment || typeof attachment !== 'object') throw invalid(`${field} must be an object`)
+  const { filename, content, contentType } = /** @type {Record<string, unknown>} */ (attachment)
+
+  let bytes
+  if (content instanceof Uint8Array) {
+    bytes = Buffer.from(content.buffer, content.byteOffset, content.byteLength)
+  } else if (typeof content === 'string') {
+    // Resend took base64 text, and callers moved from it still pass it. Anything else in a string (a CSV
+    // written as text, say) would be decoded into garbage, so it is refused instead.
+    const b64 = content.replace(/\s+/g, '')
+    if (b64.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(b64)) {
+      throw invalid(`${field}.content is a string but not base64: pass a Buffer for raw bytes`)
+    }
+    bytes = Buffer.from(b64, 'base64')
+  } else {
+    throw invalid(`${field}.content must be a Buffer, a Uint8Array or a base64 string`)
+  }
+
+  const name = cleanFilename(filename)
+  if (!name) throw invalid(`${field}.filename is required`)
+
+  const extension = name.includes('.') ? name.split('.').pop()?.toLowerCase() : undefined
+  const type = contentType ?? TYPES[/** @type {keyof typeof TYPES} */ (extension)] ?? 'application/octet-stream'
+  if (typeof type !== 'string' || !MEDIA_TYPE.test(type.toLowerCase())) {
+    throw invalid(`${field}.contentType is not a media type`)
+  }
+  return { filename: name, contentType: type.toLowerCase(), content: bytes }
+}
+
+/**
+ * Checks and normalises a message. Returns null when `to` is empty, which `send()` reports as skipped.
+ * @param {unknown} message
+ * @param {{ from?: string, configurationSet?: string }} [defaults]
+ * @returns {NormalMessage | null}
+ */
+export function normalizeMessage(message, defaults = {}) {
+  if (!message || typeof message !== 'object') throw invalid('the message must be an object')
+  const m = /** @type {Record<string, unknown>} */ (message)
+
+  const to = addressList(m.to, 'to')
+  if (to.length === 0) return null
+
+  const fromInput = m.from ?? defaults.from
+  if (fromInput === undefined || fromInput === null || fromInput === '') {
+    throw invalid('no from address: pass `from` to createMailer() or to send()')
+  }
+  if (typeof fromInput !== 'string') throw invalid('from must be a string')
+
+  if (typeof m.subject !== 'string' || m.subject.trim() === '') throw invalid('subject is required')
+  const text = bodyPart(m.text, 'text')
+  const html = bodyPart(m.html, 'html')
+  if (!text && !html) throw invalid('text or html is required')
+
+  if (m.attachments !== undefined && m.attachments !== null && !Array.isArray(m.attachments)) {
+    throw invalid('attachments must be a list')
+  }
+
+  const configurationSet = m.configurationSet ?? defaults.configurationSet
+  if (configurationSet !== undefined && configurationSet !== null && configurationSet !== '') {
+    if (typeof configurationSet !== 'string' || !CONFIGURATION_SET.test(configurationSet)) {
+      throw invalid('configurationSet is not a configuration set name')
+    }
+  }
+
+  return {
+    from: formatAddress(fromInput, 'from'),
+    to,
+    cc: addressList(m.cc, 'cc'),
+    bcc: addressList(m.bcc, 'bcc'),
+    replyTo: addressList(m.replyTo, 'replyTo'),
+    // Line breaks in a subject come from interpolated data (a name, an org): fold them into spaces
+    // rather than refuse the message, so they can never start a header of their own.
+    subject: m.subject.replace(/[\r\n]+/g, ' '),
+    text,
+    html,
+    headers: headerList(m.headers),
+    attachments: /** @type {unknown[] | undefined} */ (m.attachments ?? []).map(attachmentPart),
+    configurationSet: /** @type {string | undefined} */ (configurationSet || undefined)
+  }
+}

package/mime.js

@@ -0,0 +1,106 @@
+/*
+  The raw MIME message for a send with attachments (RFC 2045/2046):
+
+    multipart/mixed
+      multipart/alternative    (or a single text/plain or text/html part)
+        text/plain             base64
+        text/html              base64
+      attachment, one each     base64, 76-character lines
+
+  Every line ends in CRLF, every header is 7-bit (RFC 2047 for a non-ASCII subject, display name or
+  header value), and every body part is base64, so no line comes near the 998-octet limit whatever the
+  HTML looks like. Bcc is never written here: SES gets it in the envelope only, which is what keeps it
+  blind.
+
+  Why not SES's Simple.Attachments: PDFs sent that way opened blank in real mail clients (icrotary,
+  2026-07), and binaries go out as text unless each attachment says ContentTransferEncoding: 'BASE64'.
+  icrotary-com-mono's buildRawMessage is the fleet reference this follows.
+*/
+import { randomUUID } from 'node:crypto'
+
+import { base64Lines, CRLF, encodedWords, headerValue, NEEDS_ENCODING, percentEncoded, quoted } from './encode.js'
+import { normalizeMessage } from './message.js'
+import { SendError } from './sendError.js'
+
+/**
+ * @param {string} type
+ * @param {string} text
+ * @returns {string[]}
+ */
+function textPart(type, text) {
+  return [
+    `Content-Type: ${type}; charset=UTF-8`,
+    'Content-Transfer-Encoding: base64',
+    '',
+    base64Lines(Buffer.from(text, 'utf8'))
+  ]
+}
+
+/**
+ * @param {'alternative' | 'mixed'} subtype
+ * @param {string[][]} parts
+ * @returns {string[]}
+ */
+function multipart(subtype, parts) {
+  // "=_" can't occur in base64 text, so the boundary can't collide with a part's content.
+  const boundary = `=_${subtype}_${randomUUID()}`
+  const lines = [`Content-Type: multipart/${subtype};${CRLF} boundary="${boundary}"`, '']
+  for (const part of parts) lines.push(`--${boundary}`, ...part)
+  lines.push(`--${boundary}--`)
+  return lines
+}
+
+/**
+ * @param {{ filename: string, contentType: string, content: Buffer }} attachment
+ * @returns {string[]}
+ */
+function attachmentPart({ filename, contentType, content }) {
+  const ascii = !NEEDS_ENCODING.test(filename)
+  // RFC 2047 words inside the quoted name are what Gmail and Outlook read; filename* (RFC 2231) is the
+  // standard form, for the clients that prefer it.
+  const name = ascii ? quoted(filename) : encodedWords(filename, ' ')
+  const disposition = [`Content-Disposition: attachment;${CRLF} filename="${name}"`]
+  if (!ascii) disposition.push(`;${CRLF} filename*=UTF-8''${percentEncoded(filename)}`)
+  return [
+    `Content-Type: ${contentType};${CRLF} name="${name}"`,
+    'Content-Transfer-Encoding: base64',
+    disposition.join(''),
+    '',
+    base64Lines(content)
+  ]
+}
+
+/**
+ * The raw message for a normalised message.
+ * @param {import('./message.js').NormalMessage} m
+ * @returns {Buffer}
+ */
+export function renderRaw(m) {
+  const lines = [`From: ${m.from}`, `To: ${m.to.join(`,${CRLF} `)}`]
+  if (m.cc.length) lines.push(`Cc: ${m.cc.join(`,${CRLF} `)}`)
+  if (m.replyTo.length) lines.push(`Reply-To: ${m.replyTo.join(`,${CRLF} `)}`)
+  lines.push(`Subject: ${headerValue(m.subject)}`, 'MIME-Version: 1.0')
+  for (const [name, value] of m.headers) lines.push(`${name}: ${value}`)
+
+  const bodies = []
+  if (m.text) bodies.push(textPart('text/plain', m.text))
+  if (m.html) bodies.push(textPart('text/html', m.html))
+  const body = bodies.length === 2 ? multipart('alternative', bodies) : bodies[0]
+  lines.push(...(m.attachments.length ? multipart('mixed', [body, ...m.attachments.map(attachmentPart)]) : body))
+
+  return Buffer.from(`${lines.join(CRLF)}${CRLF}`, 'utf8')
+}
+
+/**
+ * Builds the raw MIME message `send()` hands SES for a message with attachments: the same input as
+ * `send()`, checked the same way. Exported for apps that need the bytes themselves (an .eml download, a
+ * test); sending goes through `send()`.
+ * @param {object} message
+ * @param {{ from?: string }} [defaults]
+ * @returns {Buffer}
+ */
+export function buildRawMessage(message, defaults) {
+  const normal = normalizeMessage(message, defaults)
+  if (!normal) throw new SendError('Email not sent: to is required', 'permanent')
+  return renderRaw(normal)
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@coderize/email",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Shared SES email sending for CoderizeDEV apps: one send switch, Simple or raw MIME with attachments, classified errors, an HTML escaper and an SNS signature verifier",
+  "keywords": [
+    "ses",
+    "email",
+    "coderize"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CoderizeDEV/coderize-platform.git",
+    "directory": "packages/email"
+  },
+  "license": "UNLICENSED",
+  "author": "Coderize",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./sns": {
+      "types": "./sns.d.ts",
+      "default": "./sns.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "CHANGELOG.md",
+    "encode.js",
+    "escape.js",
+    "index.d.ts",
+    "index.js",
+    "mailer.js",
+    "message.js",
+    "mime.js",
+    "sendError.js",
+    "sns.d.ts",
+    "sns.js"
+  ],
+  "devDependencies": {
+    "@aws-sdk/client-sesv2": "^3.1161.0",
+    "@types/node": "^24.19.2",
+    "postal-mime": "^4.2.0",
+    "typescript": "~6.0.3",
+    "vitest": "^5.0.4"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-sesv2": "^3.1127.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run && tsc -p test/types"
+  }
 }

package/sendError.js

@@ -0,0 +1,51 @@
+/**
+ * What `send()` throws when a message did not go out. `kind` tells the caller what to do about it:
+ *
+ * - `transient`: throttling, an SES 5xx or a network failure. Worth trying again later.
+ * - `permanent`: anything else (AccessDenied, an unverified identity, a message this package refused to
+ *   build). Retrying the same message won't help.
+ *
+ * The message never quotes an address or any content. A failed SES call says `Email not sent` and keeps
+ * the AWS error as `cause`; a message refused before sending says why (`Email not sent: subject is
+ * required`).
+ */
+export class SendError extends Error {
+  /**
+   * @param {string} message
+   * @param {'transient' | 'permanent'} kind
+   * @param {{ cause?: unknown }} [options]
+   */
+  constructor(message, kind, options) {
+    super(message, options)
+    this.name = 'SendError'
+    this.kind = kind
+  }
+}
+
+const TRANSIENT_NAMES = new Set([
+  'ThrottlingException',
+  'TooManyRequestsException',
+  'LimitExceededException',
+  'InternalServerException',
+  'InternalFailure',
+  'ServiceUnavailable',
+  'RequestTimeout',
+  'TimeoutError'
+])
+
+/**
+ * Whether an AWS SDK v3 error is worth retrying: the SDK marked it retryable, its name is a throttle or a
+ * server fault, SES answered 5xx, or there was no answer at all. An SDK error carries `$metadata` from
+ * the service, so one without it never reached SES (DNS, a reset connection, a timeout).
+ *
+ * Shared with SMS senders (SNS, End User Messaging), which fail the same ways.
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isTransientAwsError(error) {
+  const e = /** @type {any} */ (error)
+  if (e?.$retryable) return true
+  if (TRANSIENT_NAMES.has(e?.name)) return true
+  if (e?.$metadata?.httpStatusCode >= 500) return true
+  return !e?.$metadata && !e?.$fault
+}

package/sns.d.ts

@@ -0,0 +1,46 @@
+// Types for `@coderize/email/sns`. Hand-written to match sns.js; test/types/consumer.ts type-checks them.
+import type { KeyObject } from 'node:crypto'
+
+/** An SNS message as posted to an HTTPS subscription (JSON, sent as text/plain). */
+export interface SnsMessage {
+  Type: 'Notification' | 'SubscriptionConfirmation' | 'UnsubscribeConfirmation' | (string & {})
+  MessageId: string
+  TopicArn: string
+  Message: string
+  Timestamp: string
+  SignatureVersion: string
+  Signature: string
+  SigningCertURL: string
+  Subject?: string
+  SubscribeURL?: string
+  Token?: string
+  UnsubscribeURL?: string
+}
+
+/** The AWS region in an SNS topic ARN, or null. */
+export declare function topicRegion(topicArn: unknown): string | null
+
+/** Whether a URL is HTTPS on exactly `sns.<region>.amazonaws.com` (and ends in .pem when `pem`). */
+export declare function isSnsUrl(url: unknown, options?: { region?: string | null; pem?: boolean }): boolean
+
+/** The exact string SNS signed for this message, or null. */
+export declare function signingString(message: Record<string, unknown> | null | undefined): string | null
+
+/** Fetches (or reads from the cache) the signing certificate's public key. Throws unless it is valid now. */
+export declare function fetchSigningCert(url: string, options?: { fetch?: typeof fetch }): Promise<KeyObject>
+
+export interface VerifySnsOptions {
+  /** The topic, or topics, this route accepts. */
+  topicArn?: string | string[]
+  /** Replaces the certificate download (tests). */
+  fetchCert?: (url: string) => Promise<KeyObject | string>
+}
+
+/** Whether a message is genuinely from SNS (and from `topicArn`). Never throws. */
+export declare function verifySnsMessage(message: unknown, options?: VerifySnsOptions): Promise<boolean>
+
+/** GETs the SubscribeURL of a verified SubscriptionConfirmation. Throws when the URL is not SNS's. */
+export declare function confirmSubscription(
+  message: SnsMessage | Record<string, unknown>,
+  options?: { fetch?: typeof fetch }
+): Promise<{ ok: boolean; status: number }>