@fabrika/email 0.8.1 → 0.9.0-cloudflare.1

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;