@fabrika/email 0.3.3 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/email",
-	"version": "0.3.3",
+	"version": "0.4.1",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -24,6 +24,11 @@
 			"bun": "./src/resend.ts",
 			"types": "./src/resend.ts",
 			"default": "./src/resend.ts"
+		},
+		"./directory": {
+			"bun": "./src/directory.ts",
+			"types": "./src/directory.ts",
+			"default": "./src/directory.ts"
 		}
 	},
 	"scripts": {

package/src/directory.ts

@@ -0,0 +1,78 @@
+// A sender that keeps each message as a JSON file in a directory and delivers nothing: a local composition's mail
+// capture, which its own tests read back with `readCapturedEmails`. Bun and Node only. The files hold the bodies, and
+// with them every one-time link, so the directory belongs to the composition's disposable local state.
+
+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 { validateEmailMessage } from './validation.js'
+
+const capturedEmailSchema = z.object({
+	messageId: z.string().min(1),
+	to: z.string(),
+	subject: z.string(),
+	text: z.string(),
+	html: z.string().optional(),
+	capturedAt: z.number().int(),
+})
+
+export type CapturedEmail = z.infer<typeof capturedEmailSchema>
+
+export interface DirectoryEmailSenderOptions {
+	/** An existing directory, as an absolute path. */
+	readonly directory: string
+	readonly now?: () => number
+}
+
+export class DirectoryEmailSender implements EmailSender {
+	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 })
+		}
+		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> {
+		validateEmailMessage(message)
+		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(),
+		}
+		// 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`)
+		try {
+			await writeFile(pending, JSON.stringify(captured), { flag: 'wx' })
+			await link(pending, join(this.#directory, `${messageId}.json`)).catch((error: unknown) => {
+				if (!isAlreadyCaptured(error)) throw error
+			})
+		} catch {
+			throw new EmailDeliveryError('The mail capture directory could not be written', { code: 'provider_unavailable', retryable: true })
+		} finally {
+			await unlink(pending).catch(() => undefined)
+		}
+		return { status: 'accepted', provider: 'directory', messageId }
+	}
+}
+
+/** 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')))))
+	return emails.sort((left, right) => left.capturedAt - right.capturedAt || left.messageId.localeCompare(right.messageId))
+}
+
+function isAlreadyCaptured(error: unknown): boolean {
+	return error instanceof Error && 'code' in error && error.code === 'EEXIST'
+}

package/src/index.ts

@@ -1,3 +1,3 @@
 export { EmailDeliveryError } from './email.js'
 export type { EmailDeliveryErrorCode, EmailDeliveryErrorOptions, EmailDeliveryResult, EmailMessage, EmailSender } from './email.js'
-export { isValidEmailAddress, isValidEmailFrom, validateEmailMessage } from './validation.js'
+export { isValidEmailAddress, isValidEmailFrom, MAX_EMAIL_SUBJECT_LENGTH, validateEmailMessage } from './validation.js'

package/src/validation.ts

@@ -1,5 +1,8 @@
 import { EmailDeliveryError, type EmailMessage } from './email.js'
 
+/** The longest subject a message may have, in UTF-16 code units: RFC 5322's line limit. */
+export const MAX_EMAIL_SUBJECT_LENGTH = 998
+
 const DOT_ATOM_CHARACTER = /^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+$/
 const DOMAIN_LABEL = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/
 
@@ -32,7 +35,7 @@ export function isValidEmailFrom(value: string): boolean {
 
 export function validateEmailMessage(message: EmailMessage): void {
 	if (!isValidEmailAddress(message.to)) throw invalidMessage('Email recipient is invalid')
-	if (message.subject.length === 0 || message.subject.length > 998 || containsControlCharacter(message.subject)) {
+	if (message.subject.length === 0 || message.subject.length > MAX_EMAIL_SUBJECT_LENGTH || containsControlCharacter(message.subject)) {
 		throw invalidMessage('Email subject is invalid')
 	}
 	if (message.text.trim().length === 0) throw invalidMessage('Email text is empty')