@fabrika/email 0.0.1

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@fabrika/email",
+	"version": "0.0.1",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/email"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./resend": {
+			"bun": "./src/resend.ts",
+			"types": "./src/resend.ts",
+			"default": "./src/resend.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test src/__tests__"
+	}
+}

package/src/email.ts

@@ -0,0 +1,48 @@
+export interface EmailMessage {
+	readonly to: string
+	readonly subject: string
+	readonly text: string
+	readonly html?: string
+	readonly idempotencyKey: string
+}
+
+export interface EmailDeliveryResult {
+	readonly status: 'accepted'
+	readonly provider: string
+	readonly messageId: string
+}
+
+export interface EmailSender {
+	send(message: EmailMessage): Promise<EmailDeliveryResult>
+}
+
+export type EmailDeliveryErrorCode =
+	| 'invalid_configuration'
+	| 'invalid_message'
+	| 'network_error'
+	| 'request_timeout'
+	| 'rate_limited'
+	| 'request_in_progress'
+	| 'provider_rejected'
+	| 'provider_unavailable'
+	| 'malformed_response'
+
+export interface EmailDeliveryErrorOptions {
+	readonly code: EmailDeliveryErrorCode
+	readonly retryable: boolean
+	readonly httpStatus?: number
+}
+
+export class EmailDeliveryError extends Error {
+	readonly code: EmailDeliveryErrorCode
+	readonly retryable: boolean
+	readonly httpStatus: number | undefined
+
+	constructor(message: string, options: EmailDeliveryErrorOptions) {
+		super(message)
+		this.name = 'EmailDeliveryError'
+		this.code = options.code
+		this.retryable = options.retryable
+		this.httpStatus = options.httpStatus
+	}
+}

package/src/index.ts

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

package/src/resend.ts

@@ -0,0 +1,138 @@
+import { EmailDeliveryError, type EmailDeliveryResult, type EmailMessage, type EmailSender } from './email.js'
+import { isValidEmailFrom, validateEmailMessage } from './validation.js'
+
+const RESEND_EMAILS_URL = 'https://api.resend.com/emails'
+
+export type EmailFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+
+export interface ResendEmailSenderOptions {
+	readonly apiKey: string
+	readonly from: string
+	readonly fetch?: EmailFetch
+	readonly timeoutMs?: number
+}
+
+export class ResendEmailSender implements EmailSender {
+	readonly #apiKey: string
+	readonly #from: string
+	readonly #fetch: EmailFetch
+	readonly #timeoutMs: number
+
+	constructor(options: ResendEmailSenderOptions) {
+		if (!validApiKey(options.apiKey)) {
+			throw new EmailDeliveryError('Resend API key is invalid', { code: 'invalid_configuration', retryable: false })
+		}
+		if (!isValidEmailFrom(options.from)) {
+			throw new EmailDeliveryError('Resend sender is invalid', { code: 'invalid_configuration', retryable: false })
+		}
+		const timeoutMs = options.timeoutMs ?? 10_000
+		if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 120_000) {
+			throw new EmailDeliveryError('Resend timeout is invalid', { code: 'invalid_configuration', retryable: false })
+		}
+
+		this.#apiKey = options.apiKey
+		this.#from = options.from
+		this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init))
+		this.#timeoutMs = timeoutMs
+	}
+
+	async send(message: EmailMessage): Promise<EmailDeliveryResult> {
+		validateEmailMessage(message)
+
+		let response: Response
+		const signal = AbortSignal.timeout(this.#timeoutMs)
+		try {
+			response = await this.#fetch(RESEND_EMAILS_URL, {
+				method: 'POST',
+				headers: {
+					Authorization: `Bearer ${this.#apiKey}`,
+					'Content-Type': 'application/json',
+					'Idempotency-Key': message.idempotencyKey,
+				},
+				signal,
+				body: JSON.stringify({
+					from: this.#from,
+					to: message.to,
+					subject: message.subject,
+					text: message.text,
+					...(message.html === undefined ? {} : { html: message.html }),
+				}),
+			})
+		} catch {
+			if (signal.aborted) {
+				throw new EmailDeliveryError('Resend request timed out', { code: 'request_timeout', retryable: true })
+			}
+			throw new EmailDeliveryError('Resend request failed', { code: 'network_error', retryable: true })
+		}
+
+		if (!response.ok) throw await responseError(response)
+
+		const messageId = await readMessageId(response)
+		if (messageId === undefined) {
+			throw new EmailDeliveryError('Resend returned an invalid success response', {
+				code: 'malformed_response',
+				retryable: true,
+				httpStatus: response.status,
+			})
+		}
+
+		return { status: 'accepted', provider: 'resend', messageId }
+	}
+}
+
+async function responseError(response: Response): Promise<EmailDeliveryError> {
+	const providerError = await readProviderError(response)
+	if (response.status === 429) {
+		return new EmailDeliveryError('Resend rate limit exceeded', { code: 'rate_limited', retryable: true, httpStatus: response.status })
+	}
+	if (response.status >= 500) {
+		return new EmailDeliveryError('Resend is unavailable', { code: 'provider_unavailable', retryable: true, httpStatus: response.status })
+	}
+	if (response.status === 409 && providerError === 'concurrent_idempotent_requests') {
+		return new EmailDeliveryError('A matching Resend request is still in progress', {
+			code: 'request_in_progress',
+			retryable: true,
+			httpStatus: response.status,
+		})
+	}
+	return new EmailDeliveryError(`Resend rejected the request (${response.status})`, {
+		code: 'provider_rejected',
+		retryable: false,
+		httpStatus: response.status,
+	})
+}
+
+async function readMessageId(response: Response): Promise<string | undefined> {
+	const body = await readJson(response)
+	if (!isRecord(body)) return undefined
+	const id: unknown = Reflect.get(body, 'id')
+	return typeof id === 'string' && id.length > 0 ? id : undefined
+}
+
+async function readProviderError(response: Response): Promise<string | undefined> {
+	const body = await readJson(response)
+	if (!isRecord(body)) return undefined
+	const name: unknown = Reflect.get(body, 'name')
+	return typeof name === 'string' ? name : undefined
+}
+
+async function readJson(response: Response): Promise<unknown> {
+	try {
+		return await response.json()
+	} catch {
+		return undefined
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function validApiKey(value: string): boolean {
+	if (value.length === 0 || value.trim() !== value) return false
+	for (const character of value) {
+		const code = character.charCodeAt(0)
+		if (code < 33 || code > 126) return false
+	}
+	return true
+}

package/src/validation.ts

@@ -0,0 +1,62 @@
+import { EmailDeliveryError, type EmailMessage } from './email.js'
+
+const DOT_ATOM_CHARACTER = /^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+$/
+const DOMAIN_LABEL = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/
+
+export function isValidEmailAddress(value: string): boolean {
+	if (value.length === 0 || value.length > 254 || value.trim() !== value || containsControlCharacter(value)) return false
+
+	const separator = value.indexOf('@')
+	if (separator <= 0 || separator !== value.lastIndexOf('@')) return false
+
+	const local = value.slice(0, separator)
+	const domain = value.slice(separator + 1)
+	if (local.length > 64 || domain.length === 0 || domain.length > 253 || !domain.includes('.')) return false
+	if (!local.split('.').every((part) => part.length > 0 && DOT_ATOM_CHARACTER.test(part))) return false
+
+	return domain.split('.').every((label) => label.length <= 63 && DOMAIN_LABEL.test(label))
+}
+
+export function isValidEmailFrom(value: string): boolean {
+	if (isValidEmailAddress(value)) return true
+	if (value.length === 0 || value.length > 384 || value.trim() !== value || containsControlCharacter(value) || !value.endsWith('>')) return false
+
+	const openingBracket = value.lastIndexOf('<')
+	if (openingBracket <= 0 || value.indexOf('<') !== openingBracket || value.indexOf('>') !== value.length - 1) return false
+
+	const displayName = value.slice(0, openingBracket).trim()
+	const address = value.slice(openingBracket + 1, -1)
+	return displayName.length > 0 && displayName.length <= 128 && !displayName.includes('<') && !displayName.includes('>')
+		&& isValidEmailAddress(address)
+}
+
+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)) {
+		throw invalidMessage('Email subject is invalid')
+	}
+	if (message.text.trim().length === 0) throw invalidMessage('Email text is empty')
+	if (message.idempotencyKey.length === 0 || message.idempotencyKey.length > 256 || !isVisibleAscii(message.idempotencyKey)) {
+		throw invalidMessage('Email idempotency key is invalid')
+	}
+}
+
+function invalidMessage(message: string): EmailDeliveryError {
+	return new EmailDeliveryError(message, { code: 'invalid_message', retryable: false })
+}
+
+function containsControlCharacter(value: string): boolean {
+	for (const character of value) {
+		const code = character.charCodeAt(0)
+		if (code < 32 || code === 127) return true
+	}
+	return false
+}
+
+function isVisibleAscii(value: string): boolean {
+	for (const character of value) {
+		const code = character.charCodeAt(0)
+		if (code < 33 || code > 126) return false
+	}
+	return true
+}