@fabrika/email 0.4.8 → 0.5.1

package/src/resend.ts

@@ -1,133 +1,126 @@
 import { z } from 'zod'
-import { EmailDeliveryError, type EmailDeliveryResult, type EmailMessage, type EmailSender } from './email.js'
-import { isValidEmailFrom, validateEmailMessage } from './validation.js'
+import { type EmailProvider, type EmailSenderIdentity, parseProviderVariables } from './config.js'
+import {
+	EmailDeliveryError,
+	type EmailDeliveryResult,
+	type EmailFetch,
+	type EmailMessage,
+	type EmailSender,
+	type EmailSenderCapabilities,
+} from './email.js'
+import { parseTimeout, postToProvider, type ProviderResponse } from './http.js'
+import { isValidEmailSenderIdentity, isVisibleAscii, validateEmailMessage } from './validation.js'
 
 const RESEND_EMAILS_URL = 'https://api.resend.com/emails'
+const LABEL = 'Resend'
 const resendSuccessSchema = z.object({ id: z.string().min(1) })
 const resendErrorSchema = z.object({ name: z.string() })
-
-export type EmailFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+const QUOTA_ERRORS: ReadonlySet<string> = new Set(['daily_quota_exceeded', 'monthly_quota_exceeded'])
+/** RFC 5322 specials a display name may still hold after validation; any of them makes the name a quoted string. */
+const DISPLAY_NAME_SPECIALS = /[()[\]:;@,.]/
 
 export interface ResendEmailSenderOptions {
 	readonly apiKey: string
-	readonly from: string
+	readonly from: EmailSenderIdentity
 	readonly fetch?: EmailFetch
 	readonly timeoutMs?: number
 }
 
 export class ResendEmailSender implements EmailSender {
+	readonly capabilities: EmailSenderCapabilities = { idempotent: true, confirmation: 'sync', maxBatch: 1 }
 	readonly #apiKey: string
-	readonly #from: string
+	readonly #from: EmailSenderIdentity
 	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 })
+			throw new EmailDeliveryError('Resend API key is invalid', { code: 'invalid_configuration' })
 		}
-		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 })
+		if (!isValidEmailSenderIdentity(options.from)) {
+			throw new EmailDeliveryError('Resend sender is invalid', { code: 'invalid_configuration' })
 		}
 
 		this.#apiKey = options.apiKey
 		this.#from = options.from
 		this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init))
-		this.#timeoutMs = timeoutMs
+		this.#timeoutMs = parseTimeout(LABEL, options.timeoutMs)
 	}
 
-	async send(message: EmailMessage): Promise<EmailDeliveryResult> {
+	async send(message: EmailMessage, signal: AbortSignal): 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 })
-		}
+		const response = await postToProvider({
+			label: LABEL,
+			fetch: this.#fetch,
+			url: RESEND_EMAILS_URL,
+			headers: { Authorization: `Bearer ${this.#apiKey}`, 'Idempotency-Key': message.idempotencyKey },
+			body: {
+				from: formatMailbox(this.#from.address, message.fromName ?? this.#from.name),
+				to: message.to,
+				subject: message.subject,
+				text: message.text,
+				...(message.html === undefined ? {} : { html: message.html }),
+				...(message.replyTo === undefined ? {} : { reply_to: message.replyTo }),
+			},
+			signal,
+			timeoutMs: this.#timeoutMs,
+		})
 
-		if (!response.ok) throw await responseError(response)
+		if (!response.ok) throw 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,
-			})
+		const parsed = resendSuccessSchema.safeParse(response.body)
+		if (!parsed.success) {
+			throw new EmailDeliveryError('Resend returned an invalid success response', { code: 'malformed_response', httpStatus: response.status })
 		}
 
-		return { status: 'accepted', provider: 'resend', messageId }
+		return { status: 'accepted', provider: 'resend', messageId: parsed.data.id }
 	}
 }
 
-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 })
+const resendVariablesSchema = z.object({ FABRIKA_EMAIL_RESEND_API_KEY: z.string().refine(validApiKey) })
+
+export const resendEmailProvider: EmailProvider = {
+	variables: [{ name: 'FABRIKA_EMAIL_RESEND_API_KEY', secret: true, required: true }],
+	create({ from, env, fetch }) {
+		const variables = parseProviderVariables(resendVariablesSchema, env)
+		return new ResendEmailSender({ apiKey: variables.FABRIKA_EMAIL_RESEND_API_KEY, from, fetch })
+	},
+}
+
+function responseError(response: ProviderResponse): EmailDeliveryError {
+	const status = response.status
+	const parsed = resendErrorSchema.safeParse(response.body)
+	const name = parsed.success ? parsed.data.name : undefined
+	if (status === 401 || status === 403) {
+		return new EmailDeliveryError(`Resend refused the credentials or the sender (${status})`, { code: 'provider_unauthorized', httpStatus: status })
 	}
-	if (response.status >= 500) {
-		return new EmailDeliveryError('Resend is unavailable', { code: 'provider_unavailable', retryable: true, httpStatus: response.status })
+	if (status === 409 && name === 'concurrent_idempotent_requests') {
+		return new EmailDeliveryError('A matching Resend request is still in progress', { code: 'request_in_progress', httpStatus: 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,
+	if (status === 409 && name === 'invalid_idempotent_request') {
+		return new EmailDeliveryError('Resend already accepted a different message under this idempotency key', {
+			code: 'idempotency_conflict',
+			httpStatus: 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 parsed = resendSuccessSchema.safeParse(await readJson(response))
-	return parsed.success ? parsed.data.id : undefined
-}
-
-async function readProviderError(response: Response): Promise<string | undefined> {
-	const parsed = resendErrorSchema.safeParse(await readJson(response))
-	return parsed.success ? parsed.data.name : undefined
+	if (status === 429 && name !== undefined && QUOTA_ERRORS.has(name)) {
+		return new EmailDeliveryError('Resend sending quota exceeded', { code: 'quota_exceeded', httpStatus: status })
+	}
+	if (status === 429) {
+		return new EmailDeliveryError('Resend rate limit exceeded', { code: 'rate_limited', httpStatus: status })
+	}
+	if (status >= 500) {
+		return new EmailDeliveryError('Resend is unavailable', { code: 'provider_unavailable', httpStatus: status })
+	}
+	return new EmailDeliveryError(`Resend rejected the request (${status})`, { code: 'provider_rejected', httpStatus: status })
 }
 
-async function readJson(response: Response): Promise<unknown> {
-	try {
-		return await response.json()
-	} catch {
-		return undefined
-	}
+function formatMailbox(address: string, name: string | undefined): string {
+	if (name === undefined) return address
+	return DISPLAY_NAME_SPECIALS.test(name) ? `"${name}" <${address}>` : `${name} <${address}>`
 }
 
 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
+	return value.length > 0 && isVisibleAscii(value)
 }

package/src/smartemailing.ts

@@ -0,0 +1,150 @@
+// SmartEmailing's transactional API v3 (https://app.smartemailing.cz/docs/api/v3/), built from its OpenAPI document and
+// verified only against a stubbed fetch. It has no idempotency key, and a 201 only queues the request.
+
+import { z } from 'zod'
+import { type EmailProvider, type EmailSenderIdentity, parseProviderVariables } from './config.js'
+import {
+	EmailDeliveryError,
+	type EmailDeliveryResult,
+	type EmailFetch,
+	type EmailMessage,
+	type EmailSender,
+	type EmailSenderCapabilities,
+} from './email.js'
+import { parseTimeout, postToProvider } from './http.js'
+import { isValidEmailSenderIdentity, isVisibleAscii, validateEmailMessage } from './validation.js'
+
+const SMARTEMAILING_SEND_URL = 'https://app.smartemailing.cz/api/v3/send/transactional-emails-bulk'
+const LABEL = 'SmartEmailing'
+const DEFAULT_TAG = 'fabrika'
+const TAG_PATTERN = /^[A-Za-z0-9_-]{1,64}$/
+const smartEmailingSuccessSchema = z.object({ data: z.tuple([z.object({ id: z.string().min(1) })]) })
+
+export interface SmartEmailingEmailSenderOptions {
+	/** The account's user name or e-mail: the first half of the Basic credential. */
+	readonly username: string
+	readonly apiKey: string
+	readonly from: EmailSenderIdentity
+	/** Groups the messages in SmartEmailing's statistics. */
+	readonly tag?: string
+	readonly fetch?: EmailFetch
+	readonly timeoutMs?: number
+}
+
+export class SmartEmailingEmailSender implements EmailSender {
+	/** The API takes up to five tasks a request, but `send` carries one. */
+	readonly capabilities: EmailSenderCapabilities = { idempotent: false, confirmation: 'queued', maxBatch: 1 }
+	readonly #authorization: string
+	readonly #from: EmailSenderIdentity
+	readonly #tag: string
+	readonly #fetch: EmailFetch
+	readonly #timeoutMs: number
+
+	constructor(options: SmartEmailingEmailSenderOptions) {
+		if (!validUsername(options.username)) {
+			throw new EmailDeliveryError('SmartEmailing username is invalid', { code: 'invalid_configuration' })
+		}
+		if (!validApiKey(options.apiKey)) {
+			throw new EmailDeliveryError('SmartEmailing API key is invalid', { code: 'invalid_configuration' })
+		}
+		if (!isValidEmailSenderIdentity(options.from)) {
+			throw new EmailDeliveryError('SmartEmailing sender is invalid', { code: 'invalid_configuration' })
+		}
+		const tag = options.tag ?? DEFAULT_TAG
+		if (!TAG_PATTERN.test(tag)) {
+			throw new EmailDeliveryError('SmartEmailing tag is invalid', { code: 'invalid_configuration' })
+		}
+
+		this.#authorization = `Basic ${btoa(`${options.username}:${options.apiKey}`)}`
+		this.#from = options.from
+		this.#tag = tag
+		this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init))
+		this.#timeoutMs = parseTimeout(LABEL, options.timeoutMs)
+	}
+
+	async send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult> {
+		validateEmailMessage(message)
+
+		const senderName = message.fromName ?? this.#from.name
+		const response = await postToProvider({
+			label: LABEL,
+			fetch: this.#fetch,
+			url: SMARTEMAILING_SEND_URL,
+			headers: { Authorization: this.#authorization },
+			body: {
+				sender_credentials: {
+					from: this.#from.address,
+					...(senderName === undefined ? {} : { sender_name: senderName }),
+					...(message.replyTo === undefined ? {} : { reply_to: message.replyTo }),
+				},
+				tag: this.#tag,
+				// Unverified: the API documents no rule for a message without `html_body`.
+				message_contents: {
+					subject: message.subject,
+					text_body: message.text,
+					...(message.html === undefined ? {} : { html_body: message.html }),
+				},
+				tasks: [{ recipient: { emailaddress: message.to } }],
+			},
+			signal,
+			timeoutMs: this.#timeoutMs,
+		})
+
+		// The error body's `message` is free text that may quote the request, so only the status is classified.
+		if (!response.ok) throw responseError(response.status)
+
+		const parsed = smartEmailingSuccessSchema.safeParse(response.body)
+		if (!parsed.success) {
+			throw new EmailDeliveryError('SmartEmailing returned an invalid success response', { code: 'malformed_response', httpStatus: response.status })
+		}
+
+		return { status: 'accepted', provider: 'smartemailing', messageId: parsed.data.data[0].id }
+	}
+}
+
+const smartEmailingVariablesSchema = z.object({
+	FABRIKA_EMAIL_SMARTEMAILING_USERNAME: z.string().refine(validUsername),
+	FABRIKA_EMAIL_SMARTEMAILING_API_KEY: z.string().refine(validApiKey),
+	FABRIKA_EMAIL_SMARTEMAILING_TAG: z.string().optional().transform((value) => (value === '' ? undefined : value)).refine((value) =>
+		value === undefined || TAG_PATTERN.test(value)
+	),
+})
+
+export const smartEmailingEmailProvider: EmailProvider = {
+	variables: [
+		{ name: 'FABRIKA_EMAIL_SMARTEMAILING_USERNAME', secret: true, required: true },
+		{ name: 'FABRIKA_EMAIL_SMARTEMAILING_API_KEY', secret: true, required: true },
+		{ name: 'FABRIKA_EMAIL_SMARTEMAILING_TAG', secret: false, required: false },
+	],
+	create({ from, env, fetch }) {
+		const variables = parseProviderVariables(smartEmailingVariablesSchema, env)
+		return new SmartEmailingEmailSender({
+			username: variables.FABRIKA_EMAIL_SMARTEMAILING_USERNAME,
+			apiKey: variables.FABRIKA_EMAIL_SMARTEMAILING_API_KEY,
+			from,
+			tag: variables.FABRIKA_EMAIL_SMARTEMAILING_TAG,
+			fetch,
+		})
+	},
+}
+
+function responseError(status: number): EmailDeliveryError {
+	if (status === 401 || status === 403) {
+		return new EmailDeliveryError(`SmartEmailing refused the credentials (${status})`, { code: 'provider_unauthorized', httpStatus: status })
+	}
+	if (status === 429) {
+		return new EmailDeliveryError('SmartEmailing rate limit exceeded', { code: 'rate_limited', httpStatus: status })
+	}
+	if (status >= 500) {
+		return new EmailDeliveryError('SmartEmailing is unavailable', { code: 'provider_unavailable', httpStatus: status })
+	}
+	return new EmailDeliveryError(`SmartEmailing rejected the request (${status})`, { code: 'provider_rejected', httpStatus: status })
+}
+
+function validUsername(value: string): boolean {
+	return validApiKey(value) && !value.includes(':')
+}
+
+function validApiKey(value: string): boolean {
+	return value.length > 0 && isVisibleAscii(value)
+}

package/src/validation.ts

@@ -1,3 +1,4 @@
+import type { EmailSenderIdentity } from './config.js'
 import { EmailDeliveryError, type EmailMessage } from './email.js'
 
 /** The longest subject a message may have, in UTF-16 code units: RFC 5322's line limit. */
@@ -20,17 +21,35 @@ export function isValidEmailAddress(value: string): boolean {
 	return domain.split('.').every((label) => label.length <= 63 && DOMAIN_LABEL.test(label))
 }
 
+/** A mailbox address, or the legacy `Name <address>` form. */
 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
+	return parseEmailFrom(value) !== null
+}
+
+/**
+ * Splits a bare address or the legacy `Name <address>` form. A name in one pair of double quotes loses them, since a
+ * transport quotes the name itself when it has to.
+ */
+export function parseEmailFrom(value: string): EmailSenderIdentity | null {
+	if (isValidEmailAddress(value)) return { address: value }
+	if (value.length === 0 || value.length > 384 || value.trim() !== value || containsControlCharacter(value) || !value.endsWith('>')) return null
 
 	const openingBracket = value.lastIndexOf('<')
-	if (openingBracket <= 0 || value.indexOf('<') !== openingBracket || value.indexOf('>') !== value.length - 1) return false
+	if (openingBracket <= 0 || value.indexOf('<') !== openingBracket || value.indexOf('>') !== value.length - 1) return null
 
-	const displayName = value.slice(0, openingBracket).trim()
+	const displayName = unquoted(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)
+	if (!isValidEmailDisplayName(displayName) || !isValidEmailAddress(address)) return null
+	return { address, name: displayName }
+}
+
+/** 1..128 characters, no control characters and none of `<>"\`, so a transport can always quote it. */
+export function isValidEmailDisplayName(value: string): boolean {
+	return value.length > 0 && value.length <= 128 && !containsControlCharacter(value) && !/[<>"\\]/.test(value)
+}
+
+export function isValidEmailSenderIdentity(identity: EmailSenderIdentity): boolean {
+	return isValidEmailAddress(identity.address) && (identity.name === undefined || isValidEmailDisplayName(identity.name))
 }
 
 export function validateEmailMessage(message: EmailMessage): void {
@@ -42,10 +61,12 @@ export function validateEmailMessage(message: EmailMessage): void {
 	if (message.idempotencyKey.length === 0 || message.idempotencyKey.length > 256 || !isVisibleAscii(message.idempotencyKey)) {
 		throw invalidMessage('Email idempotency key is invalid')
 	}
+	if (message.replyTo !== undefined && !isValidEmailAddress(message.replyTo)) throw invalidMessage('Email reply-to address is invalid')
+	if (message.fromName !== undefined && !isValidEmailDisplayName(message.fromName)) throw invalidMessage('Email sender name is invalid')
 }
 
 function invalidMessage(message: string): EmailDeliveryError {
-	return new EmailDeliveryError(message, { code: 'invalid_message', retryable: false })
+	return new EmailDeliveryError(message, { code: 'invalid_message' })
 }
 
 function containsControlCharacter(value: string): boolean {
@@ -56,7 +77,11 @@ function containsControlCharacter(value: string): boolean {
 	return false
 }
 
-function isVisibleAscii(value: string): boolean {
+function unquoted(value: string): string {
+	return value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value
+}
+
+export function isVisibleAscii(value: string): boolean {
 	for (const character of value) {
 		const code = character.charCodeAt(0)
 		if (code < 33 || code > 126) return false