@fabrika/email 0.8.2 → 0.9.0-cloudflare.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/email",
-	"version": "0.8.2",
+	"version": "0.9.0-cloudflare.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,62 +12,68 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		},
 		"./resend": {
 			"bun": "./src/resend.ts",
-			"types": "./src/resend.ts",
+			"types": "./types/src/resend.d.ts",
 			"default": "./src/resend.ts"
 		},
 		"./postmark": {
 			"bun": "./src/postmark.ts",
-			"types": "./src/postmark.ts",
+			"types": "./types/src/postmark.d.ts",
 			"default": "./src/postmark.ts"
 		},
 		"./ahasend": {
 			"bun": "./src/ahasend.ts",
-			"types": "./src/ahasend.ts",
+			"types": "./types/src/ahasend.d.ts",
 			"default": "./src/ahasend.ts"
 		},
+		"./cloudflare": {
+			"bun": "./src/cloudflare.ts",
+			"types": "./types/src/cloudflare.d.ts",
+			"default": "./src/cloudflare.ts"
+		},
 		"./lettermint": {
 			"bun": "./src/lettermint.ts",
-			"types": "./src/lettermint.ts",
+			"types": "./types/src/lettermint.d.ts",
 			"default": "./src/lettermint.ts"
 		},
 		"./directory": {
 			"bun": "./src/directory.ts",
-			"types": "./src/directory.ts",
+			"types": "./types/src/directory.d.ts",
 			"default": "./src/directory.ts"
 		},
 		"./memory": {
 			"bun": "./src/memory.ts",
-			"types": "./src/memory.ts",
+			"types": "./types/src/memory.d.ts",
 			"default": "./src/memory.ts"
 		},
 		"./smartemailing": {
 			"bun": "./src/smartemailing.ts",
-			"types": "./src/smartemailing.ts",
+			"types": "./types/src/smartemailing.d.ts",
 			"default": "./src/smartemailing.ts"
 		},
 		"./providers": {
 			"bun": "./src/providers.ts",
-			"types": "./src/providers.ts",
+			"types": "./types/src/providers.d.ts",
 			"default": "./src/providers.ts"
 		},
 		"./platform": {
 			"bun": "./src/platform.ts",
-			"types": "./src/platform.ts",
+			"types": "./types/src/platform.d.ts",
 			"default": "./src/platform.ts"
 		},
 		"./conformance": {
 			"bun": "./src/conformance.ts",
-			"types": "./src/conformance.ts",
+			"types": "./types/src/conformance.d.ts",
 			"default": "./src/conformance.ts"
 		}
 	},

package/src/cloudflare.ts

@@ -0,0 +1,142 @@
+// Cloudflare Email Service's Email Sending REST API (https://developers.cloudflare.com/email-service/api/send-emails/rest-api/),
+// built from its documentation in October 2026 and verified only against a stubbed fetch. It has no idempotency key,
+// and Cloudflare takes transactional mail only. The REST API, not the Workers `send_email` binding, so the transport is
+// one set of `FABRIKA_EMAIL_*` on every runtime that sends: a Worker, a Bun process on Zerops, an application.
+
+import { z } from 'zod'
+import { type EmailProvider, parseProviderVariables } from './config.js'
+import { base64Of } from './content.js'
+import { EmailDeliveryError, type EmailMessage, type EmailSenderCapabilities, oneClickUnsubscribeHeaders } from './email.js'
+import { credentialVariable, type HttpEmailRequest, HttpEmailSender, type HttpEmailSenderOptions, isCredential } from './http-sender.js'
+import type { ProviderResponse } from './http.js'
+
+const CLOUDFLARE_ACCOUNTS_URL = 'https://api.cloudflare.com/client/v4/accounts'
+/** A Cloudflare account ID: 32 hexadecimal digits, the path of every request. */
+const ACCOUNT_ID_PATTERN = /^[0-9a-fA-F]{32}$/
+const cloudflareSuccessSchema = z.object({
+	success: z.literal(true),
+	result: z.object({
+		message_id: z.string().optional(),
+		delivered: z.array(z.string()).optional(),
+		queued: z.array(z.string()).optional(),
+		permanent_bounces: z.array(z.string()).optional(),
+		suppressed_recipients: z.array(z.string()).optional(),
+	}),
+})
+/** Cloudflare bounds a custom header's value at 2,048 bytes; the URL travels inside `<…>`. */
+const MAX_HEADER_VALUE_BYTES = 2048
+/**
+ * Cloudflare counts the whole message, attachments base64 and MIME-wrapped, against 5 MiB; 3 MiB of bytes leaves
+ * about a mebibyte for the bodies and the headers.
+ */
+const CLOUDFLARE_MAX_ATTACHMENT_BYTES = 3 * 1024 * 1024
+
+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 class CloudflareEmailSender extends HttpEmailSender {
+	readonly capabilities: EmailSenderCapabilities = {
+		idempotent: false,
+		confirmation: 'sync',
+		maxBatch: 1,
+		listUnsubscribe: true,
+		maxAttachmentBytes: CLOUDFLARE_MAX_ATTACHMENT_BYTES,
+		// Cloudflare Email Service takes transactional mail only, so it sends no broadcast.
+	}
+	readonly #apiToken: string
+	readonly #sendUrl: string
+
+	constructor(options: CloudflareEmailSenderOptions) {
+		if (!isCredential(options.apiToken)) {
+			throw new EmailDeliveryError('Cloudflare API token is invalid', { code: 'invalid_configuration' })
+		}
+		if (!ACCOUNT_ID_PATTERN.test(options.accountId)) {
+			throw new EmailDeliveryError('Cloudflare account ID is invalid', { code: 'invalid_configuration' })
+		}
+		super({ label: 'Cloudflare', provider: 'cloudflare' }, options)
+		this.#apiToken = options.apiToken
+		this.#sendUrl = `${CLOUDFLARE_ACCOUNTS_URL}/${options.accountId}/email/sending/send`
+	}
+
+	protected request(message: EmailMessage): HttpEmailRequest {
+		if (message.unsubscribeUrl !== undefined && new TextEncoder().encode(`<${message.unsubscribeUrl}>`).byteLength > MAX_HEADER_VALUE_BYTES) {
+			throw new EmailDeliveryError('Email unsubscribe URL is invalid', { code: 'invalid_message' })
+		}
+		const senderName = message.fromName ?? this.from.name
+		const attachments = message.attachments ?? []
+		return {
+			url: this.#sendUrl,
+			headers: { Authorization: `Bearer ${this.#apiToken}` },
+			body: {
+				from: { address: this.from.address, ...(senderName === undefined ? {} : { name: senderName }) },
+				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) }),
+				...(attachments.length === 0
+					? {}
+					: {
+						attachments: attachments.map((attachment) => ({
+							content: base64Of(attachment.content),
+							filename: attachment.filename,
+							type: attachment.contentType,
+							disposition: 'attachment',
+						})),
+					}),
+			},
+		}
+	}
+
+	protected messageId(response: ProviderResponse, message: EmailMessage): string | undefined {
+		const result = cloudflareSuccessSchema.safeParse(response.body).data?.result
+		if (result === undefined) return undefined
+		const listed = (addresses: readonly string[] | undefined): boolean =>
+			(addresses ?? []).some((address) => address.toLowerCase() === message.to.toLowerCase())
+		// A 200 groups the recipients by outcome; the one recipient listed as bounced or suppressed got nothing. The
+		// lists name the address, so they stay out of the refusal.
+		if (listed(result.permanent_bounces) || listed(result.suppressed_recipients)) {
+			throw new EmailDeliveryError(`Cloudflare refused the recipient (${response.status})`, { code: 'provider_rejected', httpStatus: response.status })
+		}
+		if (result.message_id !== undefined && result.message_id !== '') return result.message_id
+		// The REST guide documents a 200 with the recipients' status and no `message_id`. A recipient delivered or queued
+		// was taken, and the message's own key names that send, the same on every retry of it.
+		if (listed(result.delivered) || listed(result.queued)) return `cloudflare:${message.idempotencyKey}`
+		return undefined
+	}
+
+	protected override refusal(response: ProviderResponse): EmailDeliveryError | undefined {
+		// Documented as a resource not found: under this path, an account the token cannot reach.
+		if (response.status === 404) {
+			return new EmailDeliveryError('Cloudflare knows no such account (404)', { code: 'provider_unauthorized', httpStatus: response.status })
+		}
+		return undefined
+	}
+}
+
+const cloudflareVariablesSchema = z.object({
+	FABRIKA_EMAIL_CLOUDFLARE_API_TOKEN: credentialVariable,
+	FABRIKA_EMAIL_CLOUDFLARE_ACCOUNT_ID: z.string().regex(ACCOUNT_ID_PATTERN),
+})
+
+export const cloudflareEmailProvider: EmailProvider = {
+	variables: [
+		{ name: 'FABRIKA_EMAIL_CLOUDFLARE_API_TOKEN', secret: true, required: true },
+		{ name: 'FABRIKA_EMAIL_CLOUDFLARE_ACCOUNT_ID', secret: false, required: true },
+	],
+	create({ from, env, fetch }) {
+		const variables = parseProviderVariables(cloudflareVariablesSchema, env)
+		return new CloudflareEmailSender({
+			apiToken: variables.FABRIKA_EMAIL_CLOUDFLARE_API_TOKEN,
+			accountId: variables.FABRIKA_EMAIL_CLOUDFLARE_ACCOUNT_ID,
+			from,
+			fetch,
+		})
+	},
+}

package/src/http-sender.ts

@@ -58,8 +58,8 @@ export abstract class HttpEmailSender implements EmailSender {
 	/** The request for a message that passed validation. */
 	protected abstract request(message: EmailMessage): HttpEmailRequest | Promise<HttpEmailRequest>
 
-	/** The message id of a 2xx answer; undefined when the answer is not a valid success. May throw a refusal. */
-	protected abstract messageId(response: ProviderResponse): string | undefined
+	/** The message id of a 2xx answer to `message`; undefined when the answer is not a valid success. May throw a refusal. */
+	protected abstract messageId(response: ProviderResponse, message: EmailMessage): string | undefined
 
 	/** A failed answer to the message the provider tells apart beyond its status; undefined leaves it to `refusalByStatus`. */
 	protected refusal(_response: ProviderResponse, _message: EmailMessage): EmailDeliveryError | undefined {
@@ -79,7 +79,7 @@ export abstract class HttpEmailSender implements EmailSender {
 		const response = await postToProvider({ label: this.#label, fetch: this.#fetch, ...request, signal, timeoutMs: this.#timeoutMs })
 		if (!response.ok) throw this.refusal(response, message) ?? refusalByStatus(this.#label, response.status)
 
-		const messageId = this.messageId(response)
+		const messageId = this.messageId(response, message)
 		if (messageId === undefined || messageId === '') {
 			throw new EmailDeliveryError(`${this.#label} returned an invalid success response`, {
 				code: 'malformed_response',

package/src/providers.ts

@@ -1,4 +1,5 @@
 import { ahaSendEmailProvider } from './ahasend.js'
+import { cloudflareEmailProvider } from './cloudflare.js'
 import type { EmailProviderRegistry, EmailProviderVariable } from './config.js'
 import { lettermintEmailProvider } from './lettermint.js'
 import { postmarkEmailProvider } from './postmark.js'
@@ -11,6 +12,7 @@ import { smartEmailingEmailProvider } from './smartemailing.js'
  */
 export const builtinEmailProviders = {
 	ahasend: ahaSendEmailProvider,
+	cloudflare: cloudflareEmailProvider,
 	lettermint: lettermintEmailProvider,
 	postmark: postmarkEmailProvider,
 	resend: resendEmailProvider,
@@ -30,6 +32,7 @@ export const builtinEmailProviderVariables: readonly EmailProviderVariable[] = O
  */
 export const builtinEmailProviderSince = {
 	ahasend: '0.8.2',
+	cloudflare: '0.9.0',
 	lettermint: '0.8.2',
 	postmark: '0.8.2',
 	resend: null,

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;

package/types/src/directory.d.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { type EmailProvider } from './config.js';
+import { type EmailDeliveryResult, type EmailMessage, type EmailSender, type EmailSenderCapabilities } from './email.js';
+declare const capturedEmailSchema: z.ZodObject<{
+    messageId: z.ZodString;
+    idempotencyKey: z.ZodString;
+    to: z.ZodString;
+    subject: z.ZodString;
+    text: z.ZodString;
+    html: z.ZodOptional<z.ZodString>;
+    replyTo: z.ZodOptional<z.ZodString>;
+    fromName: z.ZodOptional<z.ZodString>;
+    unsubscribeUrl: z.ZodOptional<z.ZodString>;
+    broadcast: z.ZodOptional<z.ZodLiteral<true>>;
+    attachments: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        filename: z.ZodString;
+        contentType: z.ZodString;
+        content: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        filename: string;
+        contentType: string;
+        content: string;
+    }, {
+        filename: string;
+        contentType: string;
+        content: string;
+    }>, "many">>>;
+    capturedAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    messageId: string;
+    idempotencyKey: string;
+    to: string;
+    subject: string;
+    text: string;
+    capturedAt: number;
+    html?: string | undefined;
+    replyTo?: string | undefined;
+    fromName?: string | undefined;
+    unsubscribeUrl?: string | undefined;
+    broadcast?: true | undefined;
+    attachments?: readonly {
+        filename: string;
+        contentType: string;
+        content: string;
+    }[] | undefined;
+}, {
+    messageId: string;
+    idempotencyKey: string;
+    to: string;
+    subject: string;
+    text: string;
+    capturedAt: number;
+    html?: string | undefined;
+    replyTo?: string | undefined;
+    fromName?: string | undefined;
+    unsubscribeUrl?: string | undefined;
+    broadcast?: true | undefined;
+    attachments?: readonly {
+        filename: string;
+        contentType: string;
+        content: string;
+    }[] | undefined;
+}>;
+export type CapturedEmail = z.infer<typeof capturedEmailSchema>;
+export interface DirectoryEmailSenderOptions {
+    /** An existing directory, as an absolute path. */
+    readonly directory: string;
+    readonly now?: () => number;
+}
+export declare class DirectoryEmailSender implements EmailSender {
+    #private;
+    readonly capabilities: EmailSenderCapabilities;
+    constructor(options: DirectoryEmailSenderOptions);
+    /** One file per idempotency key: a repeated send of the same message answers the first id, as a provider does. */
+    send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult>;
+}
+/**
+ * `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 declare const directoryEmailProvider: EmailProvider;
+/** Every message a `DirectoryEmailSender` captured in `directory`, oldest first. */
+export declare function readCapturedEmails(directory: string): Promise<CapturedEmail[]>;
+export {};

package/types/src/email.d.ts

@@ -0,0 +1,142 @@
+export type EmailFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/** One file a message carries: the name the recipient sees, its media type and its bytes. */
+export interface EmailAttachment {
+    readonly filename: string;
+    readonly contentType: string;
+    readonly content: Uint8Array;
+}
+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;
+    /**
+     * An `https:` URL that unsubscribes the recipient in one click (RFC 8058): the transport writes `List-Unsubscribe:
+     * <url>` and `List-Unsubscribe-Post: List-Unsubscribe=One-Click`. A transport without `listUnsubscribe` refuses it.
+     */
+    readonly unsubscribeUrl?: string;
+    /**
+     * One message of a send to many recipients (a newsletter, an announcement), not a reply to what the recipient did.
+     * A provider keeps such mail apart from transactional mail, and the law and the mailbox providers ask it to carry
+     * an unsubscribe, so it needs `unsubscribeUrl`. A transport without `broadcast` refuses it.
+     */
+    readonly broadcast?: boolean;
+    /**
+     * Files the message carries, at most `MAX_EMAIL_ATTACHMENTS`, together at most the transport's `maxAttachmentBytes`.
+     * A transport without `maxAttachmentBytes` refuses a message that has any; an empty list is none.
+     */
+    readonly attachments?: readonly EmailAttachment[];
+}
+export interface EmailDeliveryResult {
+    readonly status: 'accepted';
+    readonly provider: string;
+    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;
+    /** Whether it writes a message's one-click unsubscribe headers (`unsubscribeUrl`); absent is no. */
+    readonly listUnsubscribe?: boolean;
+    /** The most attachment bytes one message carries, every file together; absent: it sends no attachments. */
+    readonly maxAttachmentBytes?: number;
+    /** File extensions it refuses an attachment for, lowercase and without the dot; absent: none. */
+    readonly refusedAttachmentExtensions?: readonly string[];
+    /** The fewest characters a text or HTML body has once trimmed; absent: any body that is not blank. */
+    readonly minBodyLength?: number;
+    /** Whether it sends a `broadcast` message, on its provider's channel for them where it has one; absent is no. */
+    readonly broadcast?: boolean;
+}
+export interface EmailSender {
+    readonly capabilities: EmailSenderCapabilities;
+    send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult>;
+}
+/** '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 declare const EMAIL_DELIVERY_ERRORS: {
+    readonly invalid_configuration: {
+        readonly retryable: false;
+        readonly outcome: "not_sent";
+    };
+    readonly invalid_message: {
+        readonly retryable: false;
+        readonly outcome: "not_sent";
+    };
+    readonly mail_not_configured: {
+        readonly retryable: false;
+        readonly outcome: "not_sent";
+    };
+    readonly aborted: {
+        readonly retryable: true;
+        readonly outcome: "unknown";
+    };
+    readonly network_error: {
+        readonly retryable: true;
+        readonly outcome: "unknown";
+    };
+    readonly request_timeout: {
+        readonly retryable: true;
+        readonly outcome: "unknown";
+    };
+    readonly request_in_progress: {
+        readonly retryable: true;
+        readonly outcome: "unknown";
+    };
+    readonly idempotency_conflict: {
+        readonly retryable: false;
+        readonly outcome: "unknown";
+    };
+    readonly provider_unauthorized: {
+        readonly retryable: false;
+        readonly outcome: "not_sent";
+    };
+    readonly rate_limited: {
+        readonly retryable: true;
+        readonly outcome: "not_sent";
+    };
+    readonly quota_exceeded: {
+        readonly retryable: true;
+        readonly outcome: "not_sent";
+    };
+    readonly provider_rejected: {
+        readonly retryable: false;
+        readonly outcome: "not_sent";
+    };
+    readonly provider_unavailable: {
+        readonly retryable: true;
+        readonly outcome: "unknown";
+    };
+    readonly malformed_response: {
+        readonly retryable: true;
+        readonly outcome: "unknown";
+    };
+};
+export type EmailDeliveryErrorCode = keyof typeof EMAIL_DELIVERY_ERRORS;
+export interface EmailDeliveryErrorOptions {
+    readonly code: EmailDeliveryErrorCode;
+    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 declare class EmailDeliveryError extends Error {
+    readonly code: EmailDeliveryErrorCode;
+    readonly retryable: boolean;
+    readonly outcome: EmailDeliveryOutcome;
+    readonly httpStatus: number | undefined;
+    constructor(message: string, options: EmailDeliveryErrorOptions);
+}
+/** The two headers of a one-click unsubscribe (RFC 8058), as a transport writes them for `unsubscribeUrl`. */
+export declare function oneClickUnsubscribeHeaders(url: string): Readonly<Record<string, string>>;
+/** The one retry rule: an unknown outcome is retried only over an idempotent transport. */
+export declare function mayRetryDelivery(error: EmailDeliveryError, capabilities: EmailSenderCapabilities): boolean;
+/** The bytes of every attachment of `message` together. */
+export declare function attachmentBytes(message: EmailMessage): number;

package/types/src/http-sender.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import type { EmailSenderIdentity } from './config.js';
+import { EmailDeliveryError, type EmailDeliveryResult, type EmailFetch, type EmailMessage, type EmailSender, type EmailSenderCapabilities } from './email.js';
+import { type ProviderResponse } from './http.js';
+/** The options every HTTP adapter takes beside its credentials. */
+export interface HttpEmailSenderOptions {
+    readonly from: EmailSenderIdentity;
+    readonly fetch?: EmailFetch;
+    readonly timeoutMs?: number;
+}
+export interface HttpEmailRequest {
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: unknown;
+}
+export declare abstract class HttpEmailSender implements EmailSender {
+    #private;
+    abstract readonly capabilities: EmailSenderCapabilities;
+    protected readonly from: EmailSenderIdentity;
+    /** `label` names the provider in every message, `provider` in every result. An adapter checks its credentials first. */
+    protected constructor(names: {
+        readonly label: string;
+        readonly provider: string;
+    }, options: HttpEmailSenderOptions);
+    /** The request for a message that passed validation. */
+    protected abstract request(message: EmailMessage): HttpEmailRequest | Promise<HttpEmailRequest>;
+    /** The message id of a 2xx answer to `message`; undefined when the answer is not a valid success. May throw a refusal. */
+    protected abstract messageId(response: ProviderResponse, message: EmailMessage): string | undefined;
+    /** A failed answer to the message the provider tells apart beyond its status; undefined leaves it to `refusalByStatus`. */
+    protected refusal(_response: ProviderResponse, _message: EmailMessage): EmailDeliveryError | undefined;
+    send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult>;
+}
+/** The classification of a failed answer by its status alone, for every answer an adapter does not tell apart. */
+export declare function refusalByStatus(label: string, status: number): EmailDeliveryError;
+/** `Name <address>` for an API that takes the sender as one header value; validation keeps the name quotable. */
+export declare function formatMailbox(address: string, name: string | undefined): string;
+/** An API key or token: non-empty visible ASCII, so it fits a header unchanged. */
+export declare function isCredential(value: string): boolean;
+/** The name of a provider's stream or route: 1..64 letters, digits, `_` and `-`. */
+export declare function isChannelName(value: string): boolean;
+/** A provider variable that holds a credential. */
+export declare const credentialVariable: z.ZodEffects<z.ZodString, string, string>;
+/** An optional provider variable: empty is absent, and a present value must pass `valid`. */
+export declare function optionalVariable(valid: (value: string) => boolean): z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, string | undefined>, string | undefined, string | undefined>;
+/**
+ * The message's key as a provider that takes at most `maxLength` characters sends it. A longer key is sent as its
+ * SHA-256, which keeps one key one key: a retry sends the same digest, another message another.
+ */
+export declare function providerIdempotencyKey(key: string, maxLength: number): Promise<string>;

package/types/src/http.d.ts

@@ -0,0 +1,20 @@
+import { 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 declare function postToProvider(request: ProviderRequest): Promise<ProviderResponse>;
+export declare function parseTimeout(label: string, value: number | undefined): number;

package/types/src/index.d.ts

@@ -0,0 +1,5 @@
+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 { attachmentBytes, EMAIL_DELIVERY_ERRORS, EmailDeliveryError, mayRetryDelivery, oneClickUnsubscribeHeaders } from './email.js';
+export type { EmailAttachment, EmailDeliveryErrorCode, EmailDeliveryErrorOptions, EmailDeliveryOutcome, EmailDeliveryResult, EmailFetch, EmailMessage, EmailSender, EmailSenderCapabilities, } from './email.js';
+export { isUnsubscribeUrl, isValidAttachmentFilename, isValidEmailAddress, isValidEmailDisplayName, isValidEmailFrom, MAX_EMAIL_ATTACHMENTS, MAX_EMAIL_SUBJECT_LENGTH, MAX_UNSUBSCRIBE_URL_LENGTH, validateEmailAttachments, validateEmailBodies, validateEmailBroadcast, validateEmailMessage, } from './validation.js';

package/types/src/lettermint.d.ts

@@ -0,0 +1,19 @@
+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 LettermintEmailSenderOptions extends HttpEmailSenderOptions {
+    /** A project API token: it sends through that project's default route. */
+    readonly projectToken: string;
+    /** The slug of the project's broadcast route, which a `broadcast` message goes through; `broadcast` by default. */
+    readonly broadcastRoute?: string;
+}
+export declare class LettermintEmailSender extends HttpEmailSender {
+    #private;
+    readonly capabilities: EmailSenderCapabilities;
+    constructor(options: LettermintEmailSenderOptions);
+    protected request(message: EmailMessage): Promise<HttpEmailRequest>;
+    protected messageId(response: ProviderResponse): string | undefined;
+    protected refusal(response: ProviderResponse, message: EmailMessage): EmailDeliveryError | undefined;
+}
+export declare const lettermintEmailProvider: EmailProvider;

package/types/src/memory.d.ts

@@ -0,0 +1,42 @@
+import { type EmailDeliveryErrorCode, type EmailDeliveryResult, type EmailMessage, type EmailSender, type EmailSenderCapabilities } from './email.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>;
+export declare class MemoryEmailSender implements EmailSender {
+    #private;
+    readonly capabilities: EmailSenderCapabilities;
+    constructor(options?: MemoryEmailSenderOptions);
+    /** What reached the inbox, oldest first. */
+    get accepted(): readonly MemoryEmail[];
+    /** Every call that passed validation and the abort check. */
+    get handoffs(): readonly MemoryHandoff[];
+    /** Every following call is refused with `code` and takes nothing. */
+    refuse(code?: MemoryRefusal): void;
+    /** Every following call answers `provider_unavailable` and takes nothing. */
+    unavailable(): void;
+    /** Every following call answers `network_error` and takes nothing. */
+    unreachable(): void;
+    /** The next `count` calls take the message, then answer `network_error`. */
+    loseAnswers(count: number): void;
+    /** 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;
+    heal(): void;
+    send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult>;
+}
+export {};

package/types/src/platform-wire.d.ts

@@ -0,0 +1,63 @@
+import { type EmailDeliveryErrorCode, type EmailMessage, type EmailSenderCapabilities } from './email.js';
+/** The relay's path under the receiver's URL (`FABRIKA_PLATFORM_MAIL_URL`). */
+export declare const PLATFORM_MAIL_SEND_PATH = "/platform/mail/send";
+/** What the relay promises: it records the message under its key and dispatches it later, perhaps after a person releases it. */
+export declare const PLATFORM_MAIL_CAPABILITIES: EmailSenderCapabilities;
+/**
+ * The request body as JSON text. It is canonical: two messages with the same content encode to the same text, so the
+ * relay fingerprints and stores this form.
+ */
+export declare function encodePlatformMailRequest(message: EmailMessage): string;
+/** The SHA-256 (hex) of the canonical request body: what tells a repeated send from a different one under the same key. */
+export declare function platformMailFingerprint(message: EmailMessage): Promise<string>;
+/** The SHA-256 (hex) of a transport key: the only form the receiver stores. */
+export declare function hashPlatformKey(key: string): Promise<string>;
+/**
+ * The key an installation service (IAM) sends to the relay with: derived from the installation secret both it and
+ * Control already hold, so an existing installation needs no new secret.
+ */
+export declare function installationMailKey(installationSecret: string): Promise<string>;
+export type PlatformMailRequestResult = {
+    readonly ok: true;
+    readonly message: EmailMessage;
+}
+/** `reason` is a fixed text that names no recipient, subject or body. */
+ | {
+    readonly ok: false;
+    readonly code: 'invalid_message';
+    readonly reason: string;
+};
+/** The relay's one parser of a request body (parsed JSON): a message the package's own validation accepts, or a refusal. */
+export declare function parsePlatformMailRequest(body: unknown): PlatformMailRequestResult;
+/** The HTTP status of each error the relay answers. */
+export declare const PLATFORM_MAIL_ERROR_STATUS: {
+    readonly invalid_message: 400;
+    readonly provider_unauthorized: 401;
+    readonly idempotency_conflict: 409;
+    readonly mail_not_configured: 503;
+    readonly provider_unavailable: 503;
+};
+export type PlatformMailErrorCode = keyof typeof PLATFORM_MAIL_ERROR_STATUS;
+export interface PlatformMailAccepted {
+    readonly status: 'accepted';
+    readonly messageId: string;
+}
+/** The relay's answer as a sender reads it: any `EmailDeliveryErrorCode`, so its `retryable` and `outcome` carry over. */
+export type PlatformMailAnswer = PlatformMailAccepted | {
+    readonly error: {
+        readonly code: EmailDeliveryErrorCode;
+    };
+};
+/** The relay's answer as it writes one: an acceptance, or an error that has a status. */
+export type PlatformMailReply = PlatformMailAccepted | {
+    readonly error: {
+        readonly code: PlatformMailErrorCode;
+    };
+};
+/** `200 { status: 'accepted', messageId }`, or the error's status with `{ error: { code } }`. */
+export declare function platformMailAnswerResponse(reply: PlatformMailReply): Response;
+/**
+ * The relay's answer from its status and parsed JSON body, or `null` when it is no answer the relay writes: an
+ * acceptance under any status but 200, an error code under a success status, or anything else.
+ */
+export declare function parsePlatformMailAnswer(status: number, body: unknown): PlatformMailAnswer | null;

package/types/src/platform.d.ts

@@ -0,0 +1,19 @@
+import { type EmailDeliveryResult, type EmailFetch, type EmailMessage, type EmailSender, type EmailSenderCapabilities } from './email.js';
+export { encodePlatformMailRequest, hashPlatformKey, installationMailKey, parsePlatformMailAnswer, parsePlatformMailRequest, PLATFORM_MAIL_CAPABILITIES, PLATFORM_MAIL_ERROR_STATUS, PLATFORM_MAIL_SEND_PATH, platformMailAnswerResponse, platformMailFingerprint, } from './platform-wire.js';
+export type { PlatformMailAccepted, PlatformMailAnswer, PlatformMailErrorCode, PlatformMailReply, PlatformMailRequestResult, } from './platform-wire.js';
+/** `FABRIKA_EMAIL_PROVIDER=platform`: the application sends through the platform's relay, not a provider of its own. */
+export declare const PLATFORM_EMAIL_PROVIDER = "platform";
+export interface PlatformEmailSenderOptions {
+    /** The receiver's http(s) origin (`FABRIKA_PLATFORM_MAIL_URL`); the send path is appended to it. */
+    readonly url: string;
+    readonly key: string;
+    readonly fetch?: EmailFetch;
+    readonly timeoutMs?: number;
+}
+/** Hands each message to the platform's relay, which records it under its key and dispatches it later. */
+export declare class PlatformEmailSender implements EmailSender {
+    #private;
+    readonly capabilities: EmailSenderCapabilities;
+    constructor(options: PlatformEmailSenderOptions);
+    send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult>;
+}

package/types/src/postmark.d.ts

@@ -0,0 +1,19 @@
+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 PostmarkEmailSenderOptions extends HttpEmailSenderOptions {
+    /** A server token: it sends through that server's default transactional stream. */
+    readonly serverToken: string;
+    /** The ID of the server's broadcast stream, which a `broadcast` message goes through; `broadcast` by default. */
+    readonly broadcastStream?: string;
+}
+export declare class PostmarkEmailSender extends HttpEmailSender {
+    #private;
+    readonly capabilities: EmailSenderCapabilities;
+    constructor(options: PostmarkEmailSenderOptions);
+    protected request(message: EmailMessage): HttpEmailRequest;
+    protected messageId(response: ProviderResponse): string | undefined;
+    protected refusal(response: ProviderResponse): EmailDeliveryError | undefined;
+}
+export declare const postmarkEmailProvider: EmailProvider;

package/types/src/providers.d.ts

@@ -0,0 +1,29 @@
+import type { EmailProviderVariable } from './config.js';
+/**
+ * The providers `FABRIKA_EMAIL_PROVIDER` can name in a stock installation, sorted by name: the order every help text
+ * and refusal lists them in. Memory and Directory are composition inputs.
+ */
+export declare const builtinEmailProviders: {
+    ahasend: import("./config.js").EmailProvider;
+    cloudflare: import("./config.js").EmailProvider;
+    lettermint: import("./config.js").EmailProvider;
+    postmark: import("./config.js").EmailProvider;
+    resend: import("./config.js").EmailProvider;
+    smartemailing: import("./config.js").EmailProvider;
+};
+/** Every built-in provider's own variables, in registry order: what the installers write and the workflow passes on. */
+export declare const builtinEmailProviderVariables: readonly EmailProviderVariable[];
+/**
+ * The first framework release whose registry holds each built-in provider. An application on an older release builds
+ * its sender from its own registry, so it cannot be handed one it lacks; Control refuses that deploy. `null`: every
+ * release that sends through the installation (`mailer: 'installation'`, from 0.5.0) holds it. A new provider names
+ * the release after the newest one published without it.
+ */
+export declare const builtinEmailProviderSince: {
+    readonly ahasend: "0.8.2";
+    readonly cloudflare: "0.9.0";
+    readonly lettermint: "0.8.2";
+    readonly postmark: "0.8.2";
+    readonly resend: null;
+    readonly smartemailing: null;
+};

package/types/src/resend.d.ts

@@ -0,0 +1,16 @@
+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 ResendEmailSenderOptions extends HttpEmailSenderOptions {
+    readonly apiKey: string;
+}
+export declare class ResendEmailSender extends HttpEmailSender {
+    #private;
+    readonly capabilities: EmailSenderCapabilities;
+    constructor(options: ResendEmailSenderOptions);
+    protected request(message: EmailMessage): HttpEmailRequest;
+    protected messageId(response: ProviderResponse): string | undefined;
+    protected refusal(response: ProviderResponse): EmailDeliveryError | undefined;
+}
+export declare const resendEmailProvider: EmailProvider;

package/types/src/smartemailing.d.ts

@@ -0,0 +1,24 @@
+import { type EmailProvider } from './config.js';
+import { 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 SmartEmailingEmailSenderOptions extends HttpEmailSenderOptions {
+    /** The account's user name or e-mail: the first half of the Basic credential. */
+    readonly username: string;
+    readonly apiKey: string;
+    /** Groups the messages in SmartEmailing's statistics. */
+    readonly tag?: string;
+}
+/** Its error body's `message` is free text that may quote the request, so a refusal is classified by status alone. */
+export declare class SmartEmailingEmailSender extends HttpEmailSender {
+    #private;
+    /**
+     * 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;
+    constructor(options: SmartEmailingEmailSenderOptions);
+    protected request(message: EmailMessage): HttpEmailRequest;
+    protected messageId(response: ProviderResponse): string | undefined;
+}
+export declare const smartEmailingEmailProvider: EmailProvider;

package/types/src/validation.d.ts

@@ -0,0 +1,35 @@
+import type { EmailSenderIdentity } from './config.js';
+import { type EmailMessage, type EmailSenderCapabilities } from './email.js';
+/** The longest subject a message may have, in UTF-16 code units: RFC 5322's line limit. */
+export declare const MAX_EMAIL_SUBJECT_LENGTH = 998;
+export declare function isValidEmailAddress(value: string): boolean;
+/** A mailbox address, or the legacy `Name <address>` form. */
+export declare function isValidEmailFrom(value: string): boolean;
+/**
+ * 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 declare function parseEmailFrom(value: string): EmailSenderIdentity | null;
+/** 1..128 characters, no control characters and none of `<>"\`, so a transport can always quote it. */
+export declare function isValidEmailDisplayName(value: string): boolean;
+export declare function isValidEmailSenderIdentity(identity: EmailSenderIdentity): boolean;
+export declare function validateEmailMessage(message: EmailMessage): void;
+/**
+ * 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 declare function validateEmailAttachments(message: EmailMessage, capabilities: EmailSenderCapabilities, label: string): void;
+/** Refuses a `broadcast` message where the transport sends none. */
+export declare function validateEmailBroadcast(message: EmailMessage, capabilities: EmailSenderCapabilities, label: string): void;
+/** Refuses a text or HTML body shorter than the transport's `minBodyLength`, counted in characters once trimmed. */
+export declare function validateEmailBodies(message: EmailMessage, capabilities: EmailSenderCapabilities, label: string): void;
+/** The most files one message carries. */
+export declare const MAX_EMAIL_ATTACHMENTS = 20;
+/** 1..255 characters, no control characters, no path separator and no `"`, so every transport can quote it. */
+export declare function isValidAttachmentFilename(value: string): boolean;
+/** The longest unsubscribe URL a header carries: one header line, with room for its name. */
+export declare const MAX_UNSUBSCRIBE_URL_LENGTH = 2048;
+/** An absolute `https:` URL as it is written, which a `<…>` header value carries unchanged. */
+export declare function isUnsubscribeUrl(value: string): boolean;
+export declare function isVisibleAscii(value: string): boolean;