@fabrika/email 0.8.1 → 0.9.0-cloudflare.1

package/src/resend.ts

@@ -1,80 +1,65 @@
 import { z } from 'zod'
-import { type EmailProvider, type EmailSenderIdentity, parseProviderVariables } from './config.js'
+import { type EmailProvider, parseProviderVariables } from './config.js'
 import { base64Of } from './content.js'
+import { EmailDeliveryError, type EmailMessage, type EmailSenderCapabilities, oneClickUnsubscribeHeaders } from './email.js'
 import {
-	EmailDeliveryError,
-	type EmailDeliveryResult,
-	type EmailFetch,
-	type EmailMessage,
-	type EmailSender,
-	type EmailSenderCapabilities,
-	oneClickUnsubscribeHeaders,
-} from './email.js'
-import { parseTimeout, postToProvider, type ProviderResponse } from './http.js'
-import { isValidEmailSenderIdentity, isVisibleAscii, validateEmailAttachments, validateEmailMessage } from './validation.js'
+	credentialVariable,
+	formatMailbox,
+	type HttpEmailRequest,
+	HttpEmailSender,
+	type HttpEmailSenderOptions,
+	isCredential,
+} from './http-sender.js'
+import type { ProviderResponse } from './http.js'
 
 const RESEND_EMAILS_URL = 'https://api.resend.com/emails'
 const LABEL = 'Resend'
-const resendSuccessSchema = z.object({ id: z.string().min(1) })
+const BROADCAST_TAG = { name: 'category', value: 'broadcast' }
+const resendSuccessSchema = z.object({ id: z.string() })
 const resendErrorSchema = z.object({ name: z.string() })
 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 = /[()[\]:;@,.]/
 /** Resend refuses a message over 40 MB once its attachments are base64; 25 MiB of bytes leaves room for the rest. */
 const RESEND_MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024
 
-export interface ResendEmailSenderOptions {
+export interface ResendEmailSenderOptions extends HttpEmailSenderOptions {
 	readonly apiKey: string
-	readonly from: EmailSenderIdentity
-	readonly fetch?: EmailFetch
-	readonly timeoutMs?: number
 }
 
-export class ResendEmailSender implements EmailSender {
+export class ResendEmailSender extends HttpEmailSender {
 	readonly capabilities: EmailSenderCapabilities = {
 		idempotent: true,
 		confirmation: 'sync',
 		maxBatch: 1,
 		listUnsubscribe: true,
 		maxAttachmentBytes: RESEND_MAX_ATTACHMENT_BYTES,
+		// Resend takes one-to-one marketing mail through this API, with consent and an unsubscribe; it has no channel apart.
+		broadcast: true,
 	}
 	readonly #apiKey: string
-	readonly #from: EmailSenderIdentity
-	readonly #fetch: EmailFetch
-	readonly #timeoutMs: number
 
 	constructor(options: ResendEmailSenderOptions) {
-		if (!validApiKey(options.apiKey)) {
+		if (!isCredential(options.apiKey)) {
 			throw new EmailDeliveryError('Resend API key is invalid', { code: 'invalid_configuration' })
 		}
-		if (!isValidEmailSenderIdentity(options.from)) {
-			throw new EmailDeliveryError('Resend sender is invalid', { code: 'invalid_configuration' })
-		}
-
+		super({ label: LABEL, provider: 'resend' }, options)
 		this.#apiKey = options.apiKey
-		this.#from = options.from
-		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)
-		validateEmailAttachments(message, this.capabilities, LABEL)
+	protected request(message: EmailMessage): HttpEmailRequest {
 		const attachments = message.attachments ?? []
-
-		const response = await postToProvider({
-			label: LABEL,
-			fetch: this.#fetch,
+		return {
 			url: RESEND_EMAILS_URL,
 			headers: { Authorization: `Bearer ${this.#apiKey}`, 'Idempotency-Key': message.idempotencyKey },
 			body: {
-				from: formatMailbox(this.#from.address, message.fromName ?? this.#from.name),
+				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 }),
 				...(message.unsubscribeUrl === undefined ? {} : { headers: oneClickUnsubscribeHeaders(message.unsubscribeUrl) }),
+				// Tagged, so the account's logs and webhooks tell broadcast mail from transactional.
+				...(message.broadcast === true ? { tags: [BROADCAST_TAG] } : {}),
 				...(attachments.length === 0
 					? {}
 					: {
@@ -85,22 +70,37 @@ export class ResendEmailSender implements EmailSender {
 						})),
 					}),
 			},
-			signal,
-			timeoutMs: this.#timeoutMs,
-		})
+		}
+	}
 
-		if (!response.ok) throw responseError(response)
+	protected messageId(response: ProviderResponse): string | undefined {
+		return resendSuccessSchema.safeParse(response.body).data?.id
+	}
 
-		const parsed = resendSuccessSchema.safeParse(response.body)
-		if (!parsed.success) {
-			throw new EmailDeliveryError('Resend returned an invalid success response', { code: 'malformed_response', httpStatus: response.status })
+	protected override refusal(response: ProviderResponse): EmailDeliveryError | undefined {
+		const status = response.status
+		const name = resendErrorSchema.safeParse(response.body).data?.name
+		if (status === 401 || status === 403) {
+			// A 403 is also an unverified sender domain.
+			return new EmailDeliveryError(`Resend refused the credentials or the sender (${status})`, { code: 'provider_unauthorized', httpStatus: status })
 		}
-
-		return { status: 'accepted', provider: 'resend', messageId: parsed.data.id }
+		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 (status === 409 && name === 'invalid_idempotent_request') {
+			return new EmailDeliveryError('Resend already accepted a different message under this idempotency key', {
+				code: 'idempotency_conflict',
+				httpStatus: status,
+			})
+		}
+		if (status === 429 && name !== undefined && QUOTA_ERRORS.has(name)) {
+			return new EmailDeliveryError('Resend sending quota exceeded', { code: 'quota_exceeded', httpStatus: status })
+		}
+		return undefined
 	}
 }
 
-const resendVariablesSchema = z.object({ FABRIKA_EMAIL_RESEND_API_KEY: z.string().refine(validApiKey) })
+const resendVariablesSchema = z.object({ FABRIKA_EMAIL_RESEND_API_KEY: credentialVariable })
 
 export const resendEmailProvider: EmailProvider = {
 	variables: [{ name: 'FABRIKA_EMAIL_RESEND_API_KEY', secret: true, required: true }],
@@ -109,40 +109,3 @@ export const resendEmailProvider: EmailProvider = {
 		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 (status === 409 && name === 'concurrent_idempotent_requests') {
-		return new EmailDeliveryError('A matching Resend request is still in progress', { code: 'request_in_progress', httpStatus: 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,
-		})
-	}
-	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 })
-}
-
-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 {
-	return value.length > 0 && isVisibleAscii(value)
-}

package/src/smartemailing.ts

@@ -2,83 +2,66 @@
 // 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 { type EmailProvider, parseProviderVariables } from './config.js'
+import { EmailDeliveryError, type EmailMessage, type EmailSenderCapabilities } from './email.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, validateEmailAttachments, validateEmailMessage } from './validation.js'
+	credentialVariable,
+	type HttpEmailRequest,
+	HttpEmailSender,
+	type HttpEmailSenderOptions,
+	isCredential,
+	optionalVariable,
+} from './http-sender.js'
+import type { ProviderResponse } from './http.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) })]) })
+const smartEmailingSuccessSchema = z.object({ data: z.tuple([z.object({ id: z.string() })]) })
 
-export interface SmartEmailingEmailSenderOptions {
+export interface SmartEmailingEmailSenderOptions extends HttpEmailSenderOptions {
 	/** 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. */
+/** Its error body's `message` is free text that may quote the request, so a refusal is classified by status alone. */
+export class SmartEmailingEmailSender extends HttpEmailSender {
+	/**
+	 * The API takes up to five tasks a request, but `send` carries one. Its API documents no message headers, so a
+	 * one-click unsubscribe is refused rather than sent without 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)) {
+		if (!isCredential(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' })
-		}
+		super({ label: 'SmartEmailing', provider: 'smartemailing' }, options)
 		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)
-		// Its API documents no message headers, so a one-click unsubscribe is refused rather than sent without one.
-		if (message.unsubscribeUrl !== undefined) {
-			throw new EmailDeliveryError('SmartEmailing cannot write the List-Unsubscribe headers', { code: 'invalid_message' })
-		}
-		validateEmailAttachments(message, this.capabilities, LABEL)
-
-		const senderName = message.fromName ?? this.#from.name
-		const response = await postToProvider({
-			label: LABEL,
-			fetch: this.#fetch,
+	protected request(message: EmailMessage): HttpEmailRequest {
+		const senderName = message.fromName ?? this.from.name
+		return {
 			url: SMARTEMAILING_SEND_URL,
 			headers: { Authorization: this.#authorization },
 			body: {
 				sender_credentials: {
-					from: this.#from.address,
+					from: this.from.address,
 					...(senderName === undefined ? {} : { sender_name: senderName }),
 					...(message.replyTo === undefined ? {} : { reply_to: message.replyTo }),
 				},
@@ -91,28 +74,18 @@ export class SmartEmailingEmailSender implements EmailSender {
 				},
 				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 }
+	protected messageId(response: ProviderResponse): string | undefined {
+		return smartEmailingSuccessSchema.safeParse(response.body).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)
-	),
+	FABRIKA_EMAIL_SMARTEMAILING_API_KEY: credentialVariable,
+	FABRIKA_EMAIL_SMARTEMAILING_TAG: optionalVariable((value) => TAG_PATTERN.test(value)),
 })
 
 export const smartEmailingEmailProvider: EmailProvider = {
@@ -133,23 +106,6 @@ export const smartEmailingEmailProvider: EmailProvider = {
 	},
 }
 
-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)
+	return isCredential(value) && !value.includes(':')
 }

package/src/validation.ts

@@ -64,6 +64,7 @@ export function validateEmailMessage(message: EmailMessage): void {
 	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')
 	if (message.unsubscribeUrl !== undefined && !isUnsubscribeUrl(message.unsubscribeUrl)) throw invalidMessage('Email unsubscribe URL is invalid')
+	if (message.broadcast === true && message.unsubscribeUrl === undefined) throw invalidMessage('A broadcast email needs an unsubscribe URL')
 	const attachments = message.attachments ?? []
 	if (attachments.length > MAX_EMAIL_ATTACHMENTS) throw invalidMessage(`Email has more than ${MAX_EMAIL_ATTACHMENTS} attachments`)
 	for (const attachment of attachments) {
@@ -73,15 +74,42 @@ export function validateEmailMessage(message: EmailMessage): void {
 }
 
 /**
- * Refuses a message whose attachments `capabilities` does not carry: any attachment where the transport sends none, or
- * more bytes together than its `maxAttachmentBytes`. `label` names the transport in the message.
+ * Refuses a message whose attachments `capabilities` does not carry: any attachment where the transport sends none,
+ * more bytes together than its `maxAttachmentBytes`, or a file whose extension it refuses. `label` names the transport
+ * in the message.
  */
 export function validateEmailAttachments(message: EmailMessage, capabilities: EmailSenderCapabilities, label: string): void {
-	if ((message.attachments ?? []).length === 0) return
+	const attachments = message.attachments ?? []
+	if (attachments.length === 0) return
 	const limit = capabilities.maxAttachmentBytes
 	if (limit === undefined) throw invalidMessage(`${label} sends no attachments`)
 	const bytes = attachmentBytes(message)
 	if (bytes > limit) throw invalidMessage(`Email attachments have ${bytes} bytes, more than the ${limit} ${label} sends`)
+	const refused = capabilities.refusedAttachmentExtensions ?? []
+	if (refused.length > 0 && attachments.some((attachment) => refused.includes(extensionOf(attachment.filename)))) {
+		throw invalidMessage(`${label} sends no attachment of this file type`)
+	}
+}
+
+/** Refuses a `broadcast` message where the transport sends none. */
+export function validateEmailBroadcast(message: EmailMessage, capabilities: EmailSenderCapabilities, label: string): void {
+	if (message.broadcast === true && capabilities.broadcast !== true) throw invalidMessage(`${label} sends no broadcast email`)
+}
+
+/** Refuses a text or HTML body shorter than the transport's `minBodyLength`, counted in characters once trimmed. */
+export function validateEmailBodies(message: EmailMessage, capabilities: EmailSenderCapabilities, label: string): void {
+	const min = capabilities.minBodyLength
+	if (min === undefined) return
+	const short = (body: string): boolean => [...body.trim()].length < min
+	if (short(message.text) || (message.html !== undefined && short(message.html))) {
+		throw invalidMessage(`${label} sends no body shorter than ${min} characters`)
+	}
+}
+
+/** The extension after the last dot, lowercase; empty without one. */
+function extensionOf(filename: string): string {
+	const dot = filename.lastIndexOf('.')
+	return dot < 0 ? '' : filename.slice(dot + 1).toLowerCase()
 }
 
 /** The most files one message carries. */

package/types/src/ahasend.d.ts

@@ -0,0 +1,26 @@
+import { type EmailProvider } from './config.js';
+import { EmailDeliveryError, type EmailMessage, type EmailSenderCapabilities } from './email.js';
+import { type HttpEmailRequest, HttpEmailSender, type HttpEmailSenderOptions } from './http-sender.js';
+import type { ProviderResponse } from './http.js';
+export interface AhaSendEmailSenderOptions extends HttpEmailSenderOptions {
+    /** An API key v2, scoped to `messages:send:{domain}` at least. */
+    readonly apiKey: string;
+    /** The account the key belongs to: the path of every request. */
+    readonly accountId: string;
+    /**
+     * The address a `broadcast` message is sent from, on a domain the account has configured as a Marketing domain:
+     * AhaSend's terms allow marketing mail through the API from such a domain only. Without it, a broadcast is refused.
+     */
+    readonly broadcastFrom?: string;
+}
+/** A refusal's body is one free-text `message`, so only the status is read. */
+export declare class AhaSendEmailSender extends HttpEmailSender {
+    #private;
+    /** `broadcast` only with `broadcastFrom`. */
+    readonly capabilities: EmailSenderCapabilities;
+    constructor(options: AhaSendEmailSenderOptions);
+    protected request(message: EmailMessage): Promise<HttpEmailRequest>;
+    protected messageId(response: ProviderResponse): string | undefined;
+    protected refusal(response: ProviderResponse): EmailDeliveryError | undefined;
+}
+export declare const ahaSendEmailProvider: EmailProvider;

package/types/src/cloudflare.d.ts

@@ -0,0 +1,20 @@
+import { type EmailProvider } from './config.js';
+import { EmailDeliveryError, type EmailMessage, type EmailSenderCapabilities } from './email.js';
+import { type HttpEmailRequest, HttpEmailSender, type HttpEmailSenderOptions } from './http-sender.js';
+import type { ProviderResponse } from './http.js';
+export interface CloudflareEmailSenderOptions extends HttpEmailSenderOptions {
+    /** An account API token with the Email Sending Write permission and nothing else. */
+    readonly apiToken: string;
+    /** The account the token sends for: the path of every request. */
+    readonly accountId: string;
+}
+/** A refusal's body carries numeric codes and machine-readable messages; only the status is read. */
+export declare class CloudflareEmailSender extends HttpEmailSender {
+    #private;
+    readonly capabilities: EmailSenderCapabilities;
+    constructor(options: CloudflareEmailSenderOptions);
+    protected request(message: EmailMessage): HttpEmailRequest;
+    protected messageId(response: ProviderResponse, message: EmailMessage): string | undefined;
+    protected refusal(response: ProviderResponse): EmailDeliveryError | undefined;
+}
+export declare const cloudflareEmailProvider: EmailProvider;

package/types/src/config.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { type EmailFetch, type EmailSender } from './email.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 declare 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 declare const NO_EMAIL_PROVIDER = "none";
+/** Throws one `invalid_configuration` listing every missing or invalid variable name. */
+export declare function readEmailTransportConfig(env: EmailEnvironment, registry: EmailProviderRegistry): EmailTransportConfig;
+/** null for `none` or an absent provider. */
+export declare function emailSenderFromEnv(env: EmailEnvironment, registry: EmailProviderRegistry, options?: {
+    readonly fetch?: EmailFetch;
+}): EmailSender | null;
+/** The non-empty string `FABRIKA_EMAIL_*` entries of any binding object (Worker bindings, process.env). */
+export declare function pickEmailEnvironment(source: object): EmailEnvironment;
+/**
+ * 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 declare function parseProviderVariables<Schema extends z.ZodTypeAny>(schema: Schema, env: EmailEnvironment): z.output<Schema>;

package/types/src/conformance.d.ts

@@ -0,0 +1,59 @@
+import { type EmailAttachmentContent } from './content.js';
+import { 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;
+    /** The URL of the `List-Unsubscribe` header, when `List-Unsubscribe-Post` says one click. */
+    readonly unsubscribeUrl?: string;
+    /** Each attachment with its bytes as base64. */
+    readonly attachments?: readonly EmailAttachmentContent[];
+    /** Whether the provider got it as broadcast mail, on its channel for them where it has one. */
+    readonly broadcast?: boolean;
+}
+/** A stored or sent message in wire terms: what a local harness answers for an `EmailMessage` it kept. */
+export declare function wireMessageOf(message: EmailMessage): WireMessage;
+/** 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;
+/**
+ * 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 declare function describeEmailSenderConformance(name: string, harness: EmailSenderConformanceHarness): void;

package/types/src/content.d.ts

@@ -0,0 +1,23 @@
+import type { EmailMessage } from './email.js';
+/** An attachment as a local sender keeps and compares it: the bytes as base64. */
+export interface EmailAttachmentContent {
+    readonly filename: string;
+    readonly contentType: string;
+    readonly content: string;
+}
+/** 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;
+    readonly unsubscribeUrl?: string;
+    readonly broadcast?: true;
+    readonly attachments?: readonly EmailAttachmentContent[];
+}
+export declare function sameEmailContent(left: EmailContent, right: EmailContent): boolean;
+export declare function emailContentOf(message: EmailMessage): EmailContent;
+/** `bytes` as standard base64, on every runtime: `btoa` over chunks, so a large file never overflows the call stack. */
+export declare function base64Of(bytes: Uint8Array): string;