@fabrika/email 0.4.7 → 0.5.0

package/src/directory.ts

@@ -6,15 +6,20 @@ import { createHash, randomUUID } from 'node:crypto'
 import { link, readdir, readFile, unlink, writeFile } from 'node:fs/promises'
 import { isAbsolute, join } from 'node:path'
 import { z } from 'zod'
-import { EmailDeliveryError, type EmailDeliveryResult, type EmailMessage, type EmailSender } from './email.js'
+import { type EmailProvider, parseProviderVariables } from './config.js'
+import { emailContentOf, sameEmailContent } from './content.js'
+import { EmailDeliveryError, type EmailDeliveryResult, type EmailMessage, type EmailSender, type EmailSenderCapabilities } from './email.js'
 import { validateEmailMessage } from './validation.js'
 
 const capturedEmailSchema = z.object({
 	messageId: z.string().min(1),
+	idempotencyKey: z.string(),
 	to: z.string(),
 	subject: z.string(),
 	text: z.string(),
 	html: z.string().optional(),
+	replyTo: z.string().optional(),
+	fromName: z.string().optional(),
 	capturedAt: z.number().int(),
 })
 
@@ -27,52 +32,68 @@ export interface DirectoryEmailSenderOptions {
 }
 
 export class DirectoryEmailSender implements EmailSender {
+	readonly capabilities: EmailSenderCapabilities = { idempotent: true, confirmation: 'sync', maxBatch: 1 }
 	readonly #directory: string
 	readonly #now: () => number
 
 	constructor(options: DirectoryEmailSenderOptions) {
 		if (!isAbsolute(options.directory)) {
-			throw new EmailDeliveryError('The mail capture directory must be an absolute path', { code: 'invalid_configuration', retryable: false })
+			throw new EmailDeliveryError('The mail capture directory must be an absolute path', { code: 'invalid_configuration' })
 		}
 		this.#directory = options.directory
 		this.#now = options.now ?? Date.now
 	}
 
-	/** One file per idempotency key: a repeated send keeps the first message and answers the same id, as a provider does. */
-	async send(message: EmailMessage): Promise<EmailDeliveryResult> {
+	/** One file per idempotency key: a repeated send of the same message answers the first id, as a provider does. */
+	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
 		validateEmailMessage(message)
+		if (signal.aborted) throw new EmailDeliveryError('The mail capture was aborted by the caller', { code: 'aborted' })
 		const messageId = createHash('sha256').update(message.idempotencyKey).digest('hex')
-		const captured: CapturedEmail = {
-			messageId,
-			to: message.to,
-			subject: message.subject,
-			text: message.text,
-			...(message.html === undefined ? {} : { html: message.html }),
-			capturedAt: this.#now(),
-		}
+		const captured: CapturedEmail = { messageId, idempotencyKey: message.idempotencyKey, ...emailContentOf(message), capturedAt: this.#now() }
+		const path = join(this.#directory, `${messageId}.json`)
 		// Written aside and linked in, so a reader never sees a partial file and an existing one is never replaced.
 		const pending = join(this.#directory, `.${messageId}.${randomUUID()}.tmp`)
+		let existing: CapturedEmail | null
 		try {
 			await writeFile(pending, JSON.stringify(captured), { flag: 'wx' })
-			await link(pending, join(this.#directory, `${messageId}.json`)).catch((error: unknown) => {
+			existing = await link(pending, path).then(() => null, async (error: unknown) => {
 				if (!isAlreadyCaptured(error)) throw error
+				return readCapturedEmail(path)
 			})
 		} catch {
-			throw new EmailDeliveryError('The mail capture directory could not be written', { code: 'provider_unavailable', retryable: true })
+			throw new EmailDeliveryError('The mail capture directory could not be written', { code: 'provider_unavailable' })
 		} finally {
 			await unlink(pending).catch(() => undefined)
 		}
+		if (existing !== null && !sameEmailContent(existing, captured)) {
+			throw new EmailDeliveryError('A different message was already captured under this idempotency key', { code: 'idempotency_conflict' })
+		}
 		return { status: 'accepted', provider: 'directory', messageId }
 	}
 }
 
+const directoryVariablesSchema = z.object({ FABRIKA_EMAIL_DIRECTORY: z.string() })
+
+/**
+ * `FABRIKA_EMAIL_PROVIDER=directory`: a local composition's capture. Never in `builtinEmailProviders`; a composition
+ * registers it. The capture records content only, so `FABRIKA_EMAIL_FROM` is not used.
+ */
+export const directoryEmailProvider: EmailProvider = {
+	variables: [{ name: 'FABRIKA_EMAIL_DIRECTORY', secret: false, required: true }],
+	create: ({ env }) => new DirectoryEmailSender({ directory: parseProviderVariables(directoryVariablesSchema, env).FABRIKA_EMAIL_DIRECTORY }),
+}
+
 /** Every message a `DirectoryEmailSender` captured in `directory`, oldest first. */
 export async function readCapturedEmails(directory: string): Promise<CapturedEmail[]> {
 	const names = (await readdir(directory)).filter((name) => name.endsWith('.json') && !name.startsWith('.'))
-	const emails = await Promise.all(names.map(async (name) => capturedEmailSchema.parse(JSON.parse(await readFile(join(directory, name), 'utf8')))))
+	const emails = await Promise.all(names.map((name) => readCapturedEmail(join(directory, name))))
 	return emails.sort((left, right) => left.capturedAt - right.capturedAt || left.messageId.localeCompare(right.messageId))
 }
 
+async function readCapturedEmail(path: string): Promise<CapturedEmail> {
+	return capturedEmailSchema.parse(JSON.parse(await readFile(path, 'utf8')))
+}
+
 function isAlreadyCaptured(error: unknown): boolean {
 	return error instanceof Error && 'code' in error && error.code === 'EEXIST'
 }

package/src/email.ts

@@ -1,9 +1,16 @@
+export type EmailFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+
 export interface EmailMessage {
 	readonly to: string
 	readonly subject: string
 	readonly text: string
 	readonly html?: string
+	/** 1..256 visible ASCII characters (Resend's limit). A prefix the caller adds must fit inside it. */
 	readonly idempotencyKey: string
+	/** One mailbox address. */
+	readonly replyTo?: string
+	/** Replaces the transport's display name for this message. */
+	readonly fromName?: string
 }
 
 export interface EmailDeliveryResult {
@@ -12,37 +19,67 @@ export interface EmailDeliveryResult {
 	readonly messageId: string
 }
 
+export interface EmailSenderCapabilities {
+	/** A repeated send under one key with the same message is not delivered again. */
+	readonly idempotent: boolean
+	/** 'sync': `accepted` means the provider took the message. 'queued': it queued the request and may still drop it. */
+	readonly confirmation: 'sync' | 'queued'
+	/** The most messages one call carries. `send` carries one, so every built-in adapter reports 1. */
+	readonly maxBatch: number
+}
+
 export interface EmailSender {
-	send(message: EmailMessage): Promise<EmailDeliveryResult>
+	readonly capabilities: EmailSenderCapabilities
+	send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult>
 }
 
-export type EmailDeliveryErrorCode =
-	| 'invalid_configuration'
-	| 'invalid_message'
-	| 'network_error'
-	| 'request_timeout'
-	| 'rate_limited'
-	| 'request_in_progress'
-	| 'provider_rejected'
-	| 'provider_unavailable'
-	| 'malformed_response'
+/** 'not_sent': the provider did not take the message. 'unknown': it may have taken it. */
+export type EmailDeliveryOutcome = 'not_sent' | 'unknown'
+
+/** The one classification of every failure: an adapter names the code, and the code decides the rest. */
+export const EMAIL_DELIVERY_ERRORS = {
+	invalid_configuration: { retryable: false, outcome: 'not_sent' },
+	invalid_message: { retryable: false, outcome: 'not_sent' },
+	// The installation has no transport (`FABRIKA_EMAIL_PROVIDER=none`): the message waits for one, it is not refused.
+	mail_not_configured: { retryable: false, outcome: 'not_sent' },
+	aborted: { retryable: true, outcome: 'unknown' },
+	network_error: { retryable: true, outcome: 'unknown' },
+	request_timeout: { retryable: true, outcome: 'unknown' },
+	request_in_progress: { retryable: true, outcome: 'unknown' },
+	idempotency_conflict: { retryable: false, outcome: 'unknown' },
+	provider_unauthorized: { retryable: false, outcome: 'not_sent' },
+	rate_limited: { retryable: true, outcome: 'not_sent' },
+	quota_exceeded: { retryable: true, outcome: 'not_sent' },
+	provider_rejected: { retryable: false, outcome: 'not_sent' },
+	provider_unavailable: { retryable: true, outcome: 'unknown' },
+	malformed_response: { retryable: true, outcome: 'unknown' },
+} as const satisfies Record<string, { readonly retryable: boolean; readonly outcome: EmailDeliveryOutcome }>
+
+export type EmailDeliveryErrorCode = keyof typeof EMAIL_DELIVERY_ERRORS
 
 export interface EmailDeliveryErrorOptions {
 	readonly code: EmailDeliveryErrorCode
-	readonly retryable: boolean
 	readonly httpStatus?: number
 }
 
+/** Its message is a fixed string plus the HTTP status: never a credential, a response body, a subject or a body. */
 export class EmailDeliveryError extends Error {
 	readonly code: EmailDeliveryErrorCode
 	readonly retryable: boolean
+	readonly outcome: EmailDeliveryOutcome
 	readonly httpStatus: number | undefined
 
 	constructor(message: string, options: EmailDeliveryErrorOptions) {
 		super(message)
 		this.name = 'EmailDeliveryError'
 		this.code = options.code
-		this.retryable = options.retryable
+		this.retryable = EMAIL_DELIVERY_ERRORS[options.code].retryable
+		this.outcome = EMAIL_DELIVERY_ERRORS[options.code].outcome
 		this.httpStatus = options.httpStatus
 	}
 }
+
+/** The one retry rule: an unknown outcome is retried only over an idempotent transport. */
+export function mayRetryDelivery(error: EmailDeliveryError, capabilities: EmailSenderCapabilities): boolean {
+	return error.retryable && (error.outcome === 'not_sent' || capabilities.idempotent)
+}

package/src/http.ts

@@ -0,0 +1,72 @@
+// The request half both HTTP adapters share: the caller's signal, the adapter's own timeout, and how a thrown fetch
+// is classified. Messages name the provider and nothing the request carried.
+
+import { EmailDeliveryError, type EmailFetch } from './email.js'
+
+export interface ProviderRequest {
+	/** The provider's name as it appears in error messages. */
+	readonly label: string
+	readonly fetch: EmailFetch
+	readonly url: string
+	readonly headers: Readonly<Record<string, string>>
+	readonly body: unknown
+	readonly signal: AbortSignal
+	readonly timeoutMs: number
+}
+
+export interface ProviderResponse {
+	readonly ok: boolean
+	readonly status: number
+	/** The parsed JSON body, or undefined when it is not JSON. Never put into an error. */
+	readonly body: unknown
+}
+
+/** The answer with its body already read, so an abort or a timeout while the body arrives is classified as one. */
+export async function postToProvider(request: ProviderRequest): Promise<ProviderResponse> {
+	if (request.signal.aborted) throw abortedError(request.label)
+	const timeout = AbortSignal.timeout(request.timeoutMs)
+	const signal = AbortSignal.any([request.signal, timeout])
+	try {
+		const response = await request.fetch(request.url, {
+			method: 'POST',
+			headers: { ...request.headers, 'Content-Type': 'application/json' },
+			signal,
+			body: JSON.stringify(request.body),
+		})
+		const text = await untilAborted(response.text(), signal)
+		return { ok: response.ok, status: response.status, body: parseJson(text) }
+	} catch {
+		if (request.signal.aborted) throw abortedError(request.label)
+		if (timeout.aborted) throw new EmailDeliveryError(`${request.label} request timed out`, { code: 'request_timeout' })
+		throw new EmailDeliveryError(`${request.label} request failed`, { code: 'network_error' })
+	}
+}
+
+export function parseTimeout(label: string, value: number | undefined): number {
+	const timeoutMs = value ?? 10_000
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 120_000) {
+		throw new EmailDeliveryError(`${label} timeout is invalid`, { code: 'invalid_configuration' })
+	}
+	return timeoutMs
+}
+
+/** An injected fetch's body need not follow the signal, so the read races it. */
+function untilAborted<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const onAbort = (): void => reject(signal.reason)
+		signal.addEventListener('abort', onAbort, { once: true })
+		pending.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort))
+	})
+}
+
+function parseJson(text: string): unknown {
+	try {
+		return JSON.parse(text)
+	} catch {
+		return undefined
+	}
+}
+
+function abortedError(label: string): EmailDeliveryError {
+	return new EmailDeliveryError(`${label} request was aborted by the caller`, { code: 'aborted' })
+}

package/src/index.ts

@@ -1,3 +1,28 @@
-export { EmailDeliveryError } from './email.js'
-export type { EmailDeliveryErrorCode, EmailDeliveryErrorOptions, EmailDeliveryResult, EmailMessage, EmailSender } from './email.js'
-export { isValidEmailAddress, isValidEmailFrom, MAX_EMAIL_SUBJECT_LENGTH, validateEmailMessage } from './validation.js'
+export {
+	EMAIL_PROVIDER_VARIABLE,
+	emailSenderFromEnv,
+	NO_EMAIL_PROVIDER,
+	parseProviderVariables,
+	pickEmailEnvironment,
+	readEmailTransportConfig,
+} from './config.js'
+export type {
+	EmailEnvironment,
+	EmailProvider,
+	EmailProviderRegistry,
+	EmailProviderVariable,
+	EmailSenderIdentity,
+	EmailTransportConfig,
+} from './config.js'
+export { EMAIL_DELIVERY_ERRORS, EmailDeliveryError, mayRetryDelivery } from './email.js'
+export type {
+	EmailDeliveryErrorCode,
+	EmailDeliveryErrorOptions,
+	EmailDeliveryOutcome,
+	EmailDeliveryResult,
+	EmailFetch,
+	EmailMessage,
+	EmailSender,
+	EmailSenderCapabilities,
+} from './email.js'
+export { isValidEmailAddress, isValidEmailDisplayName, isValidEmailFrom, MAX_EMAIL_SUBJECT_LENGTH, validateEmailMessage } from './validation.js'

package/src/memory.ts

@@ -0,0 +1,174 @@
+// A sender that keeps every message in memory and delivers nothing: the stand-in for tests and local development.
+// Runtime-neutral. Its faults let a test reproduce each answer a provider can give, including the one where the
+// provider took the message and the answer was lost.
+
+import { type EmailContent, emailContentOf, sameEmailContent } from './content.js'
+import {
+	EmailDeliveryError,
+	type EmailDeliveryErrorCode,
+	type EmailDeliveryResult,
+	type EmailMessage,
+	type EmailSender,
+	type EmailSenderCapabilities,
+} from './email.js'
+import { validateEmailMessage } from './validation.js'
+
+export interface MemoryEmail {
+	readonly message: EmailMessage
+	readonly messageId: string
+	readonly acceptedAt: number
+}
+
+export interface MemoryHandoff {
+	readonly message: EmailMessage
+	readonly at: number
+	/** Whether this call added the message to `accepted`. */
+	readonly taken: boolean
+	readonly answer: 'accepted' | EmailDeliveryErrorCode
+}
+
+export type MemoryRefusal = 'provider_rejected' | 'provider_unauthorized' | 'rate_limited' | 'quota_exceeded'
+
+export interface MemoryEmailSenderOptions {
+	readonly capabilities?: Partial<EmailSenderCapabilities>
+	readonly provider?: string
+	readonly now?: () => number
+}
+
+type MemoryHook = (message: EmailMessage, signal: AbortSignal) => Promise<void>
+type MemoryFault = MemoryRefusal | 'provider_unavailable' | 'network_error'
+type MemoryFailure = MemoryFault | 'aborted' | 'idempotency_conflict'
+
+interface MutableHandoff {
+	readonly message: EmailMessage
+	readonly at: number
+	taken: boolean
+	answer: 'accepted' | EmailDeliveryErrorCode
+}
+
+interface KeyedEmail {
+	readonly content: EmailContent
+	readonly messageId: string
+}
+
+const FAULT_MESSAGES: Readonly<Record<MemoryFault, string>> = {
+	provider_rejected: 'The memory sender rejected the message',
+	provider_unauthorized: 'The memory sender refused the credentials',
+	rate_limited: 'The memory sender rate limit was exceeded',
+	quota_exceeded: 'The memory sender quota was exceeded',
+	provider_unavailable: 'The memory sender is unavailable',
+	network_error: 'The memory sender could not be reached',
+}
+
+export class MemoryEmailSender implements EmailSender {
+	readonly capabilities: EmailSenderCapabilities
+	readonly #provider: string
+	readonly #now: () => number
+	readonly #accepted: MemoryEmail[] = []
+	readonly #handoffs: MutableHandoff[] = []
+	readonly #byKey = new Map<string, KeyedEmail>()
+	#fault: MemoryFault | null = null
+	#lostAnswers = 0
+	#during: MemoryHook | null = null
+	#taken = 0
+
+	constructor(options: MemoryEmailSenderOptions = {}) {
+		this.capabilities = { idempotent: true, confirmation: 'sync', maxBatch: 1, ...options.capabilities }
+		if (!Number.isSafeInteger(this.capabilities.maxBatch) || this.capabilities.maxBatch < 1) {
+			throw new EmailDeliveryError('The memory sender batch size is invalid', { code: 'invalid_configuration' })
+		}
+		this.#provider = options.provider ?? 'memory'
+		this.#now = options.now ?? Date.now
+	}
+
+	/** What reached the inbox, oldest first. */
+	get accepted(): readonly MemoryEmail[] {
+		return [...this.#accepted]
+	}
+
+	/** Every call that passed validation and the abort check. */
+	get handoffs(): readonly MemoryHandoff[] {
+		return this.#handoffs.map((handoff) => ({ ...handoff }))
+	}
+
+	/** Every following call is refused with `code` and takes nothing. */
+	refuse(code: MemoryRefusal = 'provider_rejected'): void {
+		this.#fault = code
+	}
+
+	/** Every following call answers `provider_unavailable` and takes nothing. */
+	unavailable(): void {
+		this.#fault = 'provider_unavailable'
+	}
+
+	/** Every following call answers `network_error` and takes nothing. */
+	unreachable(): void {
+		this.#fault = 'network_error'
+	}
+
+	/** The next `count` calls take the message, then answer `network_error`. */
+	loseAnswers(count: number): void {
+		this.#lostAnswers = count
+	}
+
+	/** Runs after the handoff is recorded and before the answer; a rejection becomes `aborted` once the signal aborted, else `network_error`. */
+	during(hook: MemoryHook | null): void {
+		this.#during = hook
+	}
+
+	heal(): void {
+		this.#fault = null
+		this.#lostAnswers = 0
+		this.#during = null
+	}
+
+	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
+		validateEmailMessage(message)
+		if (signal.aborted) throw failure('aborted')
+		const handoff: MutableHandoff = { message, at: this.#now(), taken: false, answer: 'network_error' }
+		this.#handoffs.push(handoff)
+		const answer = (code: MemoryFailure): EmailDeliveryError => {
+			handoff.answer = code
+			return failure(code)
+		}
+
+		if (this.#during !== null) {
+			try {
+				await this.#during(message, signal)
+			} catch {
+				throw answer(signal.aborted ? 'aborted' : 'network_error')
+			}
+		}
+		if (signal.aborted) throw answer('aborted')
+		if (this.#fault !== null) throw answer(this.#fault)
+
+		const content = emailContentOf(message)
+		const previous = this.capabilities.idempotent ? this.#byKey.get(message.idempotencyKey) : undefined
+		if (previous !== undefined && !sameEmailContent(previous.content, content)) throw answer('idempotency_conflict')
+		const messageId = previous?.messageId ?? this.#take(message, content)
+		handoff.taken = previous === undefined
+
+		if (this.#lostAnswers > 0) {
+			this.#lostAnswers -= 1
+			throw answer('network_error')
+		}
+		handoff.answer = 'accepted'
+		return { status: 'accepted', provider: this.#provider, messageId }
+	}
+
+	#take(message: EmailMessage, content: EmailContent): string {
+		this.#taken += 1
+		const messageId = `memory-${this.#taken}`
+		this.#accepted.push({ message, messageId, acceptedAt: this.#now() })
+		if (this.capabilities.idempotent) this.#byKey.set(message.idempotencyKey, { content, messageId })
+		return messageId
+	}
+}
+
+function failure(code: MemoryFailure): EmailDeliveryError {
+	if (code === 'aborted') return new EmailDeliveryError('The memory sender call was aborted by the caller', { code })
+	if (code === 'idempotency_conflict') {
+		return new EmailDeliveryError('A different message was already accepted under this idempotency key', { code })
+	}
+	return new EmailDeliveryError(FAULT_MESSAGES[code], { code })
+}

package/src/providers.ts

@@ -0,0 +1,9 @@
+import type { EmailProviderRegistry } from './config.js'
+import { resendEmailProvider } from './resend.js'
+import { smartEmailingEmailProvider } from './smartemailing.js'
+
+/** The providers `FABRIKA_EMAIL_PROVIDER` can name in a stock installation. Memory and Directory are composition inputs. */
+export const builtinEmailProviders = {
+	resend: resendEmailProvider,
+	smartemailing: smartEmailingEmailProvider,
+} satisfies EmailProviderRegistry