@fabrika/email 0.4.8 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/email",
-	"version": "0.4.8",
+	"version": "0.5.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -29,6 +29,26 @@
 			"bun": "./src/directory.ts",
 			"types": "./src/directory.ts",
 			"default": "./src/directory.ts"
+		},
+		"./memory": {
+			"bun": "./src/memory.ts",
+			"types": "./src/memory.ts",
+			"default": "./src/memory.ts"
+		},
+		"./smartemailing": {
+			"bun": "./src/smartemailing.ts",
+			"types": "./src/smartemailing.ts",
+			"default": "./src/smartemailing.ts"
+		},
+		"./providers": {
+			"bun": "./src/providers.ts",
+			"types": "./src/providers.ts",
+			"default": "./src/providers.ts"
+		},
+		"./conformance": {
+			"bun": "./src/conformance.ts",
+			"types": "./src/conformance.ts",
+			"default": "./src/conformance.ts"
 		}
 	},
 	"scripts": {

package/src/config.ts

@@ -0,0 +1,166 @@
+// The installation's mail transport as environment variables: `FABRIKA_EMAIL_PROVIDER` picks a provider from the
+// registry the composition hands in, and each provider declares and parses its own variables. Every refusal names
+// variables and never a value, because most of them are credentials.
+
+import { z } from 'zod'
+import { EmailDeliveryError, type EmailFetch, type EmailSender } from './email.js'
+import { isValidEmailDisplayName, parseEmailFrom } from './validation.js'
+
+export type EmailEnvironment = Readonly<Record<string, string | undefined>>
+
+export interface EmailSenderIdentity {
+	readonly address: string
+	readonly name?: string
+}
+
+export interface EmailProviderVariable {
+	readonly name: string
+	readonly secret: boolean
+	readonly required: boolean
+}
+
+export interface EmailProvider {
+	/** Provider-specific variables, beside FABRIKA_EMAIL_PROVIDER/FROM/FROM_NAME. */
+	readonly variables: readonly EmailProviderVariable[]
+	/** Parses its own variables; throws `invalid_configuration` naming the variable, never its value. */
+	create(input: { readonly from: EmailSenderIdentity; readonly env: EmailEnvironment; readonly fetch?: EmailFetch }): EmailSender
+}
+
+export type EmailProviderRegistry = Readonly<Record<string, EmailProvider>>
+
+export type EmailTransportConfig =
+	| { readonly kind: 'none' }
+	| { readonly kind: 'provider'; readonly provider: string; readonly from: EmailSenderIdentity; readonly variables: readonly EmailProviderVariable[] }
+
+/** The variable that selects the provider. */
+export const EMAIL_PROVIDER_VARIABLE = 'FABRIKA_EMAIL_PROVIDER'
+/** `FABRIKA_EMAIL_PROVIDER=none`: the installation states it has no transport, which an absent variable does not. */
+export const NO_EMAIL_PROVIDER = 'none'
+const FROM_VARIABLE = 'FABRIKA_EMAIL_FROM'
+const FROM_NAME_VARIABLE = 'FABRIKA_EMAIL_FROM_NAME'
+const EMAIL_VARIABLE_PREFIX = 'FABRIKA_EMAIL_'
+const UNSET_SENDER: EmailSenderIdentity = { address: 'unset@example.invalid' }
+
+const senderSchema = z.string().transform((value, context): EmailSenderIdentity => {
+	const identity = parseEmailFrom(value)
+	if (identity === null) {
+		context.addIssue({ code: z.ZodIssueCode.custom })
+		return z.NEVER
+	}
+	return identity
+})
+const displayNameSchema = z.string().refine(isValidEmailDisplayName)
+
+interface Transport {
+	readonly config: EmailTransportConfig
+	readonly sender: EmailSender | null
+}
+
+interface ConfigurationProblem {
+	/** The variable the problem names; empty when a provider's refusal names none. */
+	readonly variable: string
+	readonly text: string
+}
+
+/** An `invalid_configuration` that keeps its problems apart, so `readTransport` can merge a provider's into its own. */
+class EmailConfigurationError extends EmailDeliveryError {
+	readonly problems: readonly ConfigurationProblem[]
+
+	constructor(problems: readonly ConfigurationProblem[]) {
+		super(`Email configuration is invalid: ${problems.map((problem) => problem.text).join('; ')}`, { code: 'invalid_configuration' })
+		this.problems = problems
+	}
+}
+
+/** Throws one `invalid_configuration` listing every missing or invalid variable name. */
+export function readEmailTransportConfig(env: EmailEnvironment, registry: EmailProviderRegistry): EmailTransportConfig {
+	return readTransport(env, registry, undefined).config
+}
+
+/** null for `none` or an absent provider. */
+export function emailSenderFromEnv(
+	env: EmailEnvironment,
+	registry: EmailProviderRegistry,
+	options: { readonly fetch?: EmailFetch } = {},
+): EmailSender | null {
+	return readTransport(env, registry, options.fetch).sender
+}
+
+/** The non-empty string `FABRIKA_EMAIL_*` entries of any binding object (Worker bindings, process.env). */
+export function pickEmailEnvironment(source: object): EmailEnvironment {
+	const entries: [string, unknown][] = Object.entries(source)
+	const picked: Record<string, string> = {}
+	for (const [name, value] of entries) {
+		if (name.startsWith(EMAIL_VARIABLE_PREFIX) && typeof value === 'string' && value !== '') picked[name] = value
+	}
+	return picked
+}
+
+/**
+ * A provider's own variables through its schema. A failure is one `invalid_configuration` naming each offending
+ * variable and never its value, in the form `readEmailTransportConfig` merges into its own refusal.
+ */
+export function parseProviderVariables<Schema extends z.ZodTypeAny>(schema: Schema, env: EmailEnvironment): z.output<Schema> {
+	const parsed = schema.safeParse(env)
+	if (parsed.success) return parsed.data
+	const names = [...new Set(parsed.error.issues.map((issue) => String(issue.path[0] ?? '')))]
+	throw new EmailConfigurationError(names.map((name) => ({ variable: name, text: `${name || 'a variable'} is missing or invalid` })))
+}
+
+function readTransport(env: EmailEnvironment, registry: EmailProviderRegistry, fetch: EmailFetch | undefined): Transport {
+	const providerName = presentValue(env[EMAIL_PROVIDER_VARIABLE])
+	if (providerName === undefined || providerName === NO_EMAIL_PROVIDER) return { config: { kind: 'none' }, sender: null }
+	const provider = Object.hasOwn(registry, providerName) ? registry[providerName] : undefined
+	if (provider === undefined) {
+		throw new EmailDeliveryError(`${EMAIL_PROVIDER_VARIABLE} must be none or one of: ${Object.keys(registry).join(', ')}`, {
+			code: 'invalid_configuration',
+		})
+	}
+
+	const problems: ConfigurationProblem[] = []
+	const problem = (variable: string, text: string): void => {
+		problems.push({ variable, text: `${variable} ${text}` })
+	}
+	const fromValue = presentValue(env[FROM_VARIABLE])
+	const parsedFrom = fromValue === undefined ? undefined : senderSchema.safeParse(fromValue).data
+	if (fromValue === undefined) problem(FROM_VARIABLE, 'is missing')
+	else if (parsedFrom === undefined) problem(FROM_VARIABLE, 'is invalid')
+	const fromName = presentValue(env[FROM_NAME_VARIABLE])
+	if (fromName !== undefined && !displayNameSchema.safeParse(fromName).success) problem(FROM_NAME_VARIABLE, 'is invalid')
+	else if (fromName !== undefined && parsedFrom?.name !== undefined) {
+		problem(FROM_NAME_VARIABLE, `is refused because ${FROM_VARIABLE} already carries a display name`)
+	}
+	for (const variable of provider.variables) {
+		if (variable.required && presentValue(env[variable.name]) === undefined) problem(variable.name, 'is missing')
+	}
+	const from = parsedFrom === undefined || fromName === undefined || parsedFrom.name !== undefined
+		? parsedFrom
+		: { address: parsedFrom.address, name: fromName }
+
+	// The provider checks its own values; building it does no I/O. Without a usable sender a stand-in identity still
+	// lets it report its variables, and that sender is never returned.
+	let sender: EmailSender | null = null
+	try {
+		sender = provider.create({ from: from ?? UNSET_SENDER, env, fetch })
+	} catch (error) {
+		problems.push(...providerProblems(error, problems))
+	}
+	if (from === undefined || sender === null || problems.length > 0) throw new EmailConfigurationError(problems)
+
+	return { config: { kind: 'provider', provider: providerName, from, variables: provider.variables }, sender }
+}
+
+/** A provider's refusal as problems, without those for a variable already reported. */
+function providerProblems(error: unknown, reported: readonly ConfigurationProblem[]): ConfigurationProblem[] {
+	if (error instanceof EmailConfigurationError) {
+		return error.problems.filter((candidate) => !reported.some((problem) => problem.variable !== '' && problem.variable === candidate.variable))
+	}
+	// An error message is a fixed string by the `EmailDeliveryError` contract, so it may join the refusal.
+	if (error instanceof EmailDeliveryError && error.code === 'invalid_configuration') return [{ variable: '', text: error.message }]
+	throw error
+}
+
+/** Deploy tooling (GitHub Actions among it) passes an unset variable as an empty string, so empty means absent. */
+function presentValue(value: string | undefined): string | undefined {
+	return value === undefined || value === '' ? undefined : value
+}

package/src/conformance.ts

@@ -0,0 +1,414 @@
+// The cases every `EmailSender` passes, built-in or not. An adapter's own test file calls
+// `describeEmailSenderConformance` once with a harness: an HTTP adapter gets a stubbed fetch and says how to read its
+// request and how its provider answers; a local sender says where it stores what it took.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import {
+	EMAIL_DELIVERY_ERRORS,
+	EmailDeliveryError,
+	type EmailDeliveryErrorCode,
+	type EmailFetch,
+	type EmailMessage,
+	type EmailSender,
+} from './email.js'
+
+/** What the provider received, or what a local sender stored, in the message's own terms. */
+export interface WireMessage {
+	readonly to: string
+	readonly subject: string
+	readonly text: string
+	readonly html?: string
+	readonly replyTo?: string
+	readonly fromName?: string
+	readonly idempotencyKey?: string
+}
+
+/** How the provider answers. `inProgress` and `idempotencyConflict` are required when the sender is idempotent. */
+export interface ProviderAnswers {
+	accepted(request: Request): Response
+	malformedSuccess(): Response
+	unauthorized(): Response
+	rejected(): Response
+	rateLimited(): Response
+	unavailable(): Response
+	quotaExceeded?(): Response
+	inProgress?(): Response
+	idempotencyConflict?(): Response
+}
+
+export interface EmailSenderHttpHarness {
+	readonly kind: 'http'
+	/** Credentials the sender holds; none may appear in an error or a log line. */
+	readonly secrets: readonly string[]
+	create(fetch: EmailFetch, options: { readonly timeoutMs: number }): EmailSender
+	readRequest(request: Request): Promise<WireMessage>
+	readonly answers: ProviderAnswers
+}
+
+/** A local sender's I/O cannot be held open from outside, so the abort-during-I/O cases run for HTTP senders only. */
+export interface EmailSenderLocalHarness {
+	readonly kind: 'local'
+	/** Called before each case. */
+	create(): Promise<EmailSender>
+	/** What the sender created by the last `create` stored, oldest first. */
+	stored(): Promise<readonly WireMessage[]>
+	/** Called after each case. */
+	cleanup?(): Promise<void>
+}
+
+export type EmailSenderConformanceHarness = EmailSenderHttpHarness | EmailSenderLocalHarness
+
+const TIMEOUT_MS = 50
+const SUBJECT = 'Conformance subject 5d1c'
+const TEXT = 'Conformance text body 8e2f'
+const HTML = '<p>Conformance html body 3a7b</p>'
+const MESSAGE_MARKERS = [SUBJECT, TEXT, HTML]
+/** Shorter strings in a response body are field names and statuses, which an error message may share by chance. */
+const MIN_BODY_MARKER_LENGTH = 8
+
+const FULL_MESSAGE: EmailMessage = {
+	to: 'recipient@example.test',
+	subject: SUBJECT,
+	text: TEXT,
+	html: HTML,
+	idempotencyKey: 'conformance/full-1',
+	replyTo: 'replies@example.test',
+	fromName: 'Conformance Sender',
+}
+
+const MINIMAL_MESSAGE: EmailMessage = {
+	to: 'recipient@example.test',
+	subject: SUBJECT,
+	text: TEXT,
+	idempotencyKey: 'conformance/minimal-1',
+}
+
+const INVALID_MESSAGES: readonly { readonly problem: string; readonly message: EmailMessage }[] = [
+	{ problem: 'a bad recipient', message: { ...MINIMAL_MESSAGE, to: 'not-an-address' } },
+	{ problem: 'an empty subject', message: { ...MINIMAL_MESSAGE, subject: '' } },
+	{ problem: 'a subject with CRLF', message: { ...MINIMAL_MESSAGE, subject: 'Bad\r\nsubject' } },
+	{ problem: 'a blank text', message: { ...MINIMAL_MESSAGE, text: '   ' } },
+	{ problem: 'an empty key', message: { ...MINIMAL_MESSAGE, idempotencyKey: '' } },
+	{ problem: 'a key with a space', message: { ...MINIMAL_MESSAGE, idempotencyKey: 'has space' } },
+	{ problem: 'a key over 256 characters', message: { ...MINIMAL_MESSAGE, idempotencyKey: 'x'.repeat(257) } },
+	{ problem: 'a bad reply-to', message: { ...MINIMAL_MESSAGE, replyTo: 'not-an-address' } },
+	{ problem: 'a sender name with brackets', message: { ...MINIMAL_MESSAGE, fromName: 'Bad <name>' } },
+	{ problem: 'a sender name over 128 characters', message: { ...MINIMAL_MESSAGE, fromName: 'x'.repeat(129) } },
+]
+
+/**
+ * Registers the conformance cases for one sender. HTTP harnesses also get the provider answer table, the thrown and
+ * silent fetch, and an abort or a timeout while the request or the answer body is in flight; a local harness gets
+ * only the already-aborted case, because nothing can hold its I/O open.
+ */
+export function describeEmailSenderConformance(name: string, harness: EmailSenderConformanceHarness): void {
+	describe(`${name} conforms to EmailSender`, () => {
+		if (harness.kind === 'http') describeHttpSender(harness)
+		else describeLocalSender(harness)
+	})
+}
+
+type Handler = (request: Request, signal: AbortSignal | undefined) => Promise<Response>
+
+interface HttpCase {
+	readonly sender: EmailSender
+	readonly requests: Request[]
+	/** Every string of length ≥ MIN_BODY_MARKER_LENGTH in the bodies the provider answered with. */
+	readonly bodyMarkers: string[]
+	/** The status of each answer, in order. */
+	readonly statuses: number[]
+}
+
+function describeHttpSender(harness: EmailSenderHttpHarness): void {
+	/** Read after the call settles, when the answer bodies are known. */
+	const forbidden = (current: HttpCase) => (): string[] => [...MESSAGE_MARKERS, ...harness.secrets, ...current.bodyMarkers]
+
+	/** `stalledBody`: the handler answers a body that never ends, which the stub must not read itself. */
+	function httpCase(handler: Handler, options: { readonly stalledBody?: boolean } = {}): HttpCase {
+		const requests: Request[] = []
+		const bodyMarkers: string[] = []
+		const statuses: number[] = []
+		const fetch: EmailFetch = async (input, init) => {
+			const request = new Request(input, init)
+			requests.push(request.clone())
+			const response = await handler(request, init?.signal ?? undefined)
+			statuses.push(response.status)
+			if (options.stalledBody !== true) bodyMarkers.push(...markersOf(await response.clone().text()))
+			return response
+		}
+		return { sender: harness.create(fetch, { timeoutMs: TIMEOUT_MS }), requests, bodyMarkers, statuses }
+	}
+
+	const answering = (answer: () => Response): HttpCase => httpCase(async () => answer())
+
+	test('reports its capabilities', () => {
+		expectCapabilities(answering(() => harness.answers.malformedSuccess()).sender)
+	})
+
+	test('answers an accepted result', async () => {
+		const current = httpCase(async (request) => harness.answers.accepted(request))
+		expectAccepted(await current.sender.send(FULL_MESSAGE, new AbortController().signal))
+		expect(current.requests).toHaveLength(1)
+	})
+
+	test('hands every field of the message to the provider', async () => {
+		const current = httpCase(async (request) => harness.answers.accepted(request))
+		await current.sender.send(FULL_MESSAGE, new AbortController().signal)
+		const wire = await harness.readRequest(only(current.requests))
+		expect(wire).toMatchObject(contentOf(FULL_MESSAGE))
+		if (current.sender.capabilities.idempotent) expect(wire.idempotencyKey).toBe(FULL_MESSAGE.idempotencyKey)
+	})
+
+	test('leaves html, reply-to and sender name out when the message has none', async () => {
+		const current = httpCase(async (request) => harness.answers.accepted(request))
+		await current.sender.send(MINIMAL_MESSAGE, new AbortController().signal)
+		expectOptionalFieldsAbsent(await harness.readRequest(only(current.requests)))
+	})
+
+	test.each(INVALID_MESSAGES)('refuses $problem as invalid_message without a request', async ({ message }) => {
+		const current = httpCase(async (request) => harness.answers.accepted(request))
+		await expectRejection(() => current.sender.send(message, new AbortController().signal), 'invalid_message', forbidden(current))
+		expect(current.requests).toHaveLength(0)
+	})
+
+	test('an already aborted signal answers aborted without a request', async () => {
+		const current = httpCase(async (request) => harness.answers.accepted(request))
+		await expectRejection(() => current.sender.send(FULL_MESSAGE, AbortSignal.abort()), 'aborted', forbidden(current))
+		expect(current.requests).toHaveLength(0)
+	})
+
+	test('an abort during the request answers aborted with an unknown outcome', async () => {
+		const controller = new AbortController()
+		const current = httpCase((_request, signal) => {
+			if (signal === undefined) return Promise.reject(new Error('the request carries no signal'))
+			const pending = new Promise<Response>((_resolve, reject) => {
+				signal.addEventListener('abort', () => reject(new Error('aborted')), { once: true })
+			})
+			controller.abort()
+			return pending
+		})
+		const error = await expectRejection(() => current.sender.send(FULL_MESSAGE, controller.signal), 'aborted', forbidden(current))
+		expect(error.outcome).toBe('unknown')
+	})
+
+	test('every provider answer maps to its code and keeps the HTTP status', async () => {
+		const probe = answering(() => harness.answers.malformedSuccess()).sender
+		const answers = harness.answers
+		const table: [string, (() => Response) | undefined, EmailDeliveryErrorCode][] = [
+			['unauthorized', () => answers.unauthorized(), 'provider_unauthorized'],
+			['rejected', () => answers.rejected(), 'provider_rejected'],
+			['rateLimited', () => answers.rateLimited(), 'rate_limited'],
+			['unavailable', () => answers.unavailable(), 'provider_unavailable'],
+			['malformedSuccess', () => answers.malformedSuccess(), 'malformed_response'],
+			['quotaExceeded', answers.quotaExceeded?.bind(answers), 'quota_exceeded'],
+			['inProgress', answers.inProgress?.bind(answers), 'request_in_progress'],
+			['idempotencyConflict', answers.idempotencyConflict?.bind(answers), 'idempotency_conflict'],
+		]
+		for (const [answerName, answer, code] of table) {
+			if (answer === undefined) {
+				const requiredByIdempotency = code === 'request_in_progress' || code === 'idempotency_conflict'
+				if (requiredByIdempotency && probe.capabilities.idempotent) throw new Error(`An idempotent sender's harness must supply ${answerName}`)
+				continue
+			}
+			const current = answering(answer)
+			const error = await expectRejection(() => current.sender.send(FULL_MESSAGE, new AbortController().signal), code, forbidden(current))
+			expect(error.httpStatus).toBe(only(current.statuses))
+		}
+	})
+
+	test('a fetch that throws answers network_error', async () => {
+		const current = httpCase(() => Promise.reject(new Error(`socket closed ${harness.secrets.join(' ')} ${TEXT}`)))
+		await expectRejection(() => current.sender.send(FULL_MESSAGE, new AbortController().signal), 'network_error', forbidden(current))
+	})
+
+	test('a provider that never answers times out at the configured timeout', async () => {
+		const current = httpCase((_request, signal) =>
+			new Promise<Response>((_resolve, reject) => {
+				signal?.addEventListener('abort', () => reject(new Error('timed out')), { once: true })
+			})
+		)
+		const started = Date.now()
+		await expectRejection(() => current.sender.send(FULL_MESSAGE, new AbortController().signal), 'request_timeout', forbidden(current))
+		expect(Date.now() - started).toBeGreaterThanOrEqual(TIMEOUT_MS - 5)
+	})
+
+	test('an abort while the answer body arrives answers aborted', async () => {
+		const controller = new AbortController()
+		const current = httpCase(async () => {
+			setTimeout(() => controller.abort(), 5)
+			return stalledAnswer()
+		}, { stalledBody: true })
+		const error = await expectRejection(() => current.sender.send(FULL_MESSAGE, controller.signal), 'aborted', forbidden(current))
+		expect(error.outcome).toBe('unknown')
+	})
+
+	test('an answer body that never finishes times out', async () => {
+		const current = httpCase(async () => stalledAnswer(), { stalledBody: true })
+		await expectRejection(() => current.sender.send(FULL_MESSAGE, new AbortController().signal), 'request_timeout', forbidden(current))
+	})
+}
+
+/** A 200 whose body never ends. */
+function stalledAnswer(): Response {
+	return new Response(new ReadableStream({ start() {} }), { status: 200 })
+}
+
+function describeLocalSender(harness: EmailSenderLocalHarness): void {
+	let sender: EmailSender | null = null
+	const current = (): EmailSender => {
+		if (sender === null) throw new Error('the harness created no sender')
+		return sender
+	}
+
+	beforeEach(async () => {
+		sender = await harness.create()
+	})
+
+	afterEach(async () => {
+		sender = null
+		await harness.cleanup?.()
+	})
+
+	test('reports its capabilities', () => {
+		expectCapabilities(current())
+	})
+
+	test('answers an accepted result', async () => {
+		expectAccepted(await current().send(FULL_MESSAGE, new AbortController().signal))
+	})
+
+	test('stores every field of the message', async () => {
+		await current().send(FULL_MESSAGE, new AbortController().signal)
+		expect(only(await harness.stored())).toMatchObject(contentOf(FULL_MESSAGE))
+	})
+
+	test('leaves html, reply-to and sender name out when the message has none', async () => {
+		await current().send(MINIMAL_MESSAGE, new AbortController().signal)
+		expectOptionalFieldsAbsent(only(await harness.stored()))
+	})
+
+	test.each(INVALID_MESSAGES)('refuses $problem as invalid_message and stores nothing', async ({ message }) => {
+		await expectRejection(() => current().send(message, new AbortController().signal), 'invalid_message', () => MESSAGE_MARKERS)
+		expect(await harness.stored()).toHaveLength(0)
+	})
+
+	test('an already aborted signal answers aborted and stores nothing', async () => {
+		await expectRejection(() => current().send(FULL_MESSAGE, AbortSignal.abort()), 'aborted', () => MESSAGE_MARKERS)
+		expect(await harness.stored()).toHaveLength(0)
+	})
+
+	test('an idempotent sender stores a repeated message once and refuses a different one under the same key', async () => {
+		const target = current()
+		if (!target.capabilities.idempotent) return
+		const first = await target.send(FULL_MESSAGE, new AbortController().signal)
+		const repeated = await target.send(FULL_MESSAGE, new AbortController().signal)
+		expect(repeated.messageId).toBe(first.messageId)
+		expect(await harness.stored()).toHaveLength(1)
+		await expectRejection(
+			() => target.send({ ...FULL_MESSAGE, text: `${TEXT} changed` }, new AbortController().signal),
+			'idempotency_conflict',
+			() => MESSAGE_MARKERS,
+		)
+		expect(await harness.stored()).toHaveLength(1)
+	})
+}
+
+function expectCapabilities(sender: EmailSender): void {
+	const { idempotent, confirmation, maxBatch } = sender.capabilities
+	expect(typeof idempotent).toBe('boolean')
+	expect(['sync', 'queued']).toContain(confirmation)
+	expect(Number.isSafeInteger(maxBatch) && maxBatch > 0).toBe(true)
+}
+
+function expectAccepted(result: Awaited<ReturnType<EmailSender['send']>>): void {
+	expect(result.status).toBe('accepted')
+	expect(result.provider).not.toBe('')
+	expect(result.messageId).not.toBe('')
+}
+
+function expectOptionalFieldsAbsent(wire: WireMessage): void {
+	expect(wire.html).toBeUndefined()
+	expect(wire.replyTo).toBeUndefined()
+	expect(wire.fromName).toBeUndefined()
+}
+
+function contentOf(message: EmailMessage): WireMessage {
+	return {
+		to: message.to,
+		subject: message.subject,
+		text: message.text,
+		...(message.html === undefined ? {} : { html: message.html }),
+		...(message.replyTo === undefined ? {} : { replyTo: message.replyTo }),
+		...(message.fromName === undefined ? {} : { fromName: message.fromName }),
+	}
+}
+
+/** The rejection, checked against the classification table and for anything it must never carry. */
+async function expectRejection(
+	run: () => Promise<unknown>,
+	code: EmailDeliveryErrorCode,
+	forbidden: () => readonly string[],
+): Promise<EmailDeliveryError> {
+	const logged: string[] = []
+	const restore = captureConsole(logged)
+	let reason: unknown
+	try {
+		reason = await run().then(() => undefined, (error: unknown) => error)
+	} finally {
+		restore()
+	}
+	if (!(reason instanceof EmailDeliveryError)) throw new Error(`expected an EmailDeliveryError with code ${code}`)
+	expect(reason.code).toBe(code)
+	expect({ retryable: reason.retryable, outcome: reason.outcome }).toEqual(EMAIL_DELIVERY_ERRORS[code])
+	const surfaces = [reason.message, String(reason), JSON.stringify(reason), ...logged]
+	for (const value of forbidden()) {
+		for (const surface of surfaces) expect(surface).not.toContain(value)
+	}
+	return reason
+}
+
+function captureConsole(logged: string[]): () => void {
+	const originals = { log: console.log, info: console.info, warn: console.warn, error: console.error, debug: console.debug }
+	const record = (...args: unknown[]): void => {
+		logged.push(args.map((arg) => (arg instanceof Error ? `${arg.message} ${arg.stack ?? ''}` : safeString(arg))).join(' '))
+	}
+	console.log = record
+	console.info = record
+	console.warn = record
+	console.error = record
+	console.debug = record
+	return () => {
+		Object.assign(console, originals)
+	}
+}
+
+function safeString(value: unknown): string {
+	if (typeof value === 'string') return value
+	try {
+		return JSON.stringify(value) ?? String(value)
+	} catch {
+		return String(value)
+	}
+}
+
+function markersOf(body: string): string[] {
+	const markers: string[] = []
+	const collect = (value: unknown): void => {
+		if (typeof value === 'string' && value.length >= MIN_BODY_MARKER_LENGTH) markers.push(value)
+		else if (Array.isArray(value)) value.forEach(collect)
+		else if (typeof value === 'object' && value !== null) Object.values(value).forEach(collect)
+	}
+	try {
+		collect(JSON.parse(body))
+	} catch {
+		collect(body)
+	}
+	return markers
+}
+
+function only<T>(items: readonly T[]): T {
+	expect(items).toHaveLength(1)
+	const item = items[0]
+	if (item === undefined) throw new Error('expected exactly one item')
+	return item
+}

package/src/content.ts

@@ -0,0 +1,27 @@
+import type { EmailMessage } from './email.js'
+
+/** What a local sender compares when one idempotency key arrives twice: everything the recipient would see. */
+export interface EmailContent {
+	readonly to: string
+	readonly subject: string
+	readonly text: string
+	readonly html?: string
+	readonly replyTo?: string
+	readonly fromName?: string
+}
+
+export function sameEmailContent(left: EmailContent, right: EmailContent): boolean {
+	return left.to === right.to && left.subject === right.subject && left.text === right.text && left.html === right.html
+		&& left.replyTo === right.replyTo && left.fromName === right.fromName
+}
+
+export function emailContentOf(message: EmailMessage): EmailContent {
+	return {
+		to: message.to,
+		subject: message.subject,
+		text: message.text,
+		...(message.html === undefined ? {} : { html: message.html }),
+		...(message.replyTo === undefined ? {} : { replyTo: message.replyTo }),
+		...(message.fromName === undefined ? {} : { fromName: message.fromName }),
+	}
+}