@fabrika/email 0.9.0-dev.1 → 0.9.0-dev.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/email",
-	"version": "0.9.0-dev.1",
+	"version": "0.9.0-dev.3",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,47 +12,48 @@
 	},
 	"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"
 		},
 		"./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/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,57 @@
+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[];
+}
+/** 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,22 @@
+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 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,81 @@
+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>;
+    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;
+    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;
+    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,130 @@
+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;
+    /**
+     * 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;
+}
+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.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, validateEmailMessage, } from './validation.js';

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/providers.d.ts

@@ -0,0 +1,5 @@
+/** The providers `FABRIKA_EMAIL_PROVIDER` can name in a stock installation. Memory and Directory are composition inputs. */
+export declare const builtinEmailProviders: {
+    resend: import("./config.js").EmailProvider;
+    smartemailing: import("./config.js").EmailProvider;
+};

package/types/src/resend.d.ts

@@ -0,0 +1,15 @@
+import { type EmailProvider, type EmailSenderIdentity } from './config.js';
+import { type EmailDeliveryResult, type EmailFetch, type EmailMessage, type EmailSender, type EmailSenderCapabilities } from './email.js';
+export interface ResendEmailSenderOptions {
+    readonly apiKey: string;
+    readonly from: EmailSenderIdentity;
+    readonly fetch?: EmailFetch;
+    readonly timeoutMs?: number;
+}
+export declare class ResendEmailSender implements EmailSender {
+    #private;
+    readonly capabilities: EmailSenderCapabilities;
+    constructor(options: ResendEmailSenderOptions);
+    send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult>;
+}
+export declare const resendEmailProvider: EmailProvider;

package/types/src/smartemailing.d.ts

@@ -0,0 +1,20 @@
+import { type EmailProvider, type EmailSenderIdentity } from './config.js';
+import { type EmailDeliveryResult, type EmailFetch, type EmailMessage, type EmailSender, type EmailSenderCapabilities } from './email.js';
+export interface SmartEmailingEmailSenderOptions {
+    /** The account's user name or e-mail: the first half of the Basic credential. */
+    readonly username: string;
+    readonly apiKey: string;
+    readonly from: EmailSenderIdentity;
+    /** Groups the messages in SmartEmailing's statistics. */
+    readonly tag?: string;
+    readonly fetch?: EmailFetch;
+    readonly timeoutMs?: number;
+}
+export declare class SmartEmailingEmailSender implements EmailSender {
+    #private;
+    /** The API takes up to five tasks a request, but `send` carries one. */
+    readonly capabilities: EmailSenderCapabilities;
+    constructor(options: SmartEmailingEmailSenderOptions);
+    send(message: EmailMessage, signal: AbortSignal): Promise<EmailDeliveryResult>;
+}
+export declare const smartEmailingEmailProvider: EmailProvider;

package/types/src/validation.d.ts

@@ -0,0 +1,30 @@
+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, or
+ * more bytes together than its `maxAttachmentBytes`. `label` names the transport in the message.
+ */
+export declare function validateEmailAttachments(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;