@sdxc/mail 0.0.0-pre.1

package/dist/memory.d.ts

@@ -0,0 +1,81 @@
+/**
+ * In-memory transport that captures every delivery for assertions. As a full
+ * implementation of the transport contract, it lets tests assert on the message
+ * a caller actually produced — including the email object it came from, and
+ * the assembled MIME when it is asked for one — using state held in memory.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { MailError } from "./errors.js";
+import type { NormalizedMessage, SentMessage, Transport } from "./types.js";
+/** Configuration for what a memory transport records beyond the message itself. */
+export interface MemoryTransportOptions {
+    /**
+     * Assemble and record the raw MIME message for every delivery. Off by default,
+     * because most tests assert on the normalized message, and MIME only matters to
+     * the transports whose provider takes it.
+     */
+    mime?: boolean;
+}
+/** One recorded delivery: the message a provider would have received, and its wire form. */
+export interface RecordedDelivery {
+    /** The normalized message the transport was handed. */
+    message: NormalizedMessage;
+    /** The assembled MIME message, present only when MIME recording is enabled. */
+    mime?: string;
+}
+/**
+ * Transport that keeps deliveries in memory for assertions.
+ *
+ * Recorded messages are the normalized ones a provider receives; `message.email`
+ * keeps the original when a send came from one, so matching by type survives a copy.
+ *
+ * @example
+ * let transport = new MemoryTransport();
+ * await new Mailer({ transport, from: SENDER }).send(new TeamInviteEmail(invite));
+ * expect(transport.find((message) => message.email instanceof TeamInviteEmail)).toBeDefined();
+ *
+ * @example
+ * let transport = new MemoryTransport({ mime: true });
+ * await new Mailer({ transport, from: SENDER }).send(message);
+ * expect(transport.lastMime).toContain("Content-Type: multipart/alternative");
+ */
+export declare class MemoryTransport implements Transport {
+    #private;
+    /**
+     * Creates the transport.
+     *
+     * @param options - What to record; see {@link MemoryTransportOptions}.
+     */
+    constructor(options?: MemoryTransportOptions);
+    /** Every recorded delivery with its wire form, oldest first. */
+    get deliveries(): readonly RecordedDelivery[];
+    /** Every recorded delivery, oldest first. */
+    get messages(): readonly NormalizedMessage[];
+    /** Most recent delivery, or `undefined` when nothing has been sent yet. */
+    get last(): NormalizedMessage | undefined;
+    /**
+     * Raw MIME message of the most recent delivery. It is `undefined` when nothing has
+     * been sent, and also when the transport was not asked to record MIME, since
+     * assembling it for every test that never looks at it is wasted work.
+     */
+    get lastMime(): string | undefined;
+    /**
+     * Finds the first recorded delivery matching a predicate.
+     *
+     * @param predicate - Test applied to each message in delivery order.
+     * @returns The first matching message, or `undefined` when none matches.
+     */
+    find(predicate: (message: NormalizedMessage) => boolean): NormalizedMessage | undefined;
+    /** Forgets every recorded delivery, so one instance can be reused between tests. */
+    clear(): void;
+    /**
+     * Records the message and reports success.
+     *
+     * @param message - The normalized message to record.
+     * @returns Success carrying the message's own `Message-ID`, since no provider assigned one.
+     */
+    send(message: NormalizedMessage): Promise<Result<SentMessage, MailError>>;
+}

package/dist/memory.js

@@ -0,0 +1,84 @@
+/**
+ * In-memory transport that captures every delivery for assertions. As a full
+ * implementation of the transport contract, it lets tests assert on the message
+ * a caller actually produced — including the email object it came from, and
+ * the assembled MIME when it is asked for one — using state held in memory.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { success } from "@sdxc/result";
+import { buildMimeMessage } from "./mime.js";
+/**
+ * Transport that keeps deliveries in memory for assertions.
+ *
+ * Recorded messages are the normalized ones a provider receives; `message.email`
+ * keeps the original when a send came from one, so matching by type survives a copy.
+ *
+ * @example
+ * let transport = new MemoryTransport();
+ * await new Mailer({ transport, from: SENDER }).send(new TeamInviteEmail(invite));
+ * expect(transport.find((message) => message.email instanceof TeamInviteEmail)).toBeDefined();
+ *
+ * @example
+ * let transport = new MemoryTransport({ mime: true });
+ * await new Mailer({ transport, from: SENDER }).send(message);
+ * expect(transport.lastMime).toContain("Content-Type: multipart/alternative");
+ */
+export class MemoryTransport {
+    /** Deliveries recorded so far, oldest first. */
+    #deliveries = [];
+    /** Whether each delivery is recorded with its assembled MIME message. */
+    #mime;
+    /**
+     * Creates the transport.
+     *
+     * @param options - What to record; see {@link MemoryTransportOptions}.
+     */
+    constructor(options = {}) {
+        this.#mime = options.mime ?? false;
+    }
+    /** Every recorded delivery with its wire form, oldest first. */
+    get deliveries() {
+        return this.#deliveries;
+    }
+    /** Every recorded delivery, oldest first. */
+    get messages() {
+        return this.#deliveries.map((delivery) => delivery.message);
+    }
+    /** Most recent delivery, or `undefined` when nothing has been sent yet. */
+    get last() {
+        return this.#deliveries.at(-1)?.message;
+    }
+    /**
+     * Raw MIME message of the most recent delivery. It is `undefined` when nothing has
+     * been sent, and also when the transport was not asked to record MIME, since
+     * assembling it for every test that never looks at it is wasted work.
+     */
+    get lastMime() {
+        return this.#deliveries.at(-1)?.mime;
+    }
+    /**
+     * Finds the first recorded delivery matching a predicate.
+     *
+     * @param predicate - Test applied to each message in delivery order.
+     * @returns The first matching message, or `undefined` when none matches.
+     */
+    find(predicate) {
+        return this.messages.find(predicate);
+    }
+    /** Forgets every recorded delivery, so one instance can be reused between tests. */
+    clear() {
+        this.#deliveries.length = 0;
+    }
+    /**
+     * Records the message and reports success.
+     *
+     * @param message - The normalized message to record.
+     * @returns Success carrying the message's own `Message-ID`, since no provider assigned one.
+     */
+    async send(message) {
+        this.#deliveries.push({ message, mime: this.#mime ? buildMimeMessage(message) : undefined });
+        return success({ messageId: message.messageId });
+    }
+}

package/dist/middleware.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Remix fetch-router middleware that builds a mailer for the request and
+ * publishes it on the request context, so handlers send mail by calling
+ * `context.email`, using whichever transport the app configured. Messages
+ * queued with `later()` flush after the handler returns, and each outcome is
+ * recorded on the invocation's log.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Middleware, RequestContext } from "remix/router";
+import type { Address, Transport } from "./types.js";
+import { Mailer } from "./mailer.js";
+/**
+ * Declared here, in an imported module rather than an ambient .d.ts, so the
+ * augmentation is applied in consuming projects that import the middleware.
+ */
+declare module "remix/router" {
+    interface RequestContext {
+        /**
+         * The object that sends mail for the current request, configured by the
+         * mail middleware.
+         */
+        email: Mailer;
+    }
+}
+/** Options that configure the mail middleware. */
+export interface MailMiddlewareOptions {
+    /**
+     * Transport used for delivery, or a factory that resolves one per request. A
+     * transport built from a module-level binding needs no factory; one resolved
+     * through a service container uses the factory form.
+     */
+    transport: Transport | ((context: RequestContext) => Transport);
+    /** Sender identity for the app, applied to every message that does not set one. */
+    from: Address;
+    /** Where replies go by default; a message or email may override it. */
+    replyTo?: Address | Address[];
+    /** Headers added to every message the request sends. */
+    headers?: Record<string, string>;
+}
+/**
+ * Creates a middleware that publishes a request-scoped mailer as `context.email`,
+ * resolving a container-based transport once per request. The `later()` queue
+ * flushes in a `finally` after `next()`; the response is already decided by then,
+ * so a failed deferred send is a warning on the invocation's log rather than an error.
+ *
+ * @param options - Transport and sender configuration; see {@link MailMiddlewareOptions}.
+ * @returns A middleware that populates `context.email`.
+ * @example
+ * router.use(mail({ transport: new CloudflareTransport(env.EMAIL), from: SENDER }));
+ */
+export default function mail(options: MailMiddlewareOptions): Middleware;

package/dist/middleware.js

@@ -0,0 +1,50 @@
+/**
+ * Remix fetch-router middleware that builds a mailer for the request and
+ * publishes it on the request context, so handlers send mail by calling
+ * `context.email`, using whichever transport the app configured. Messages
+ * queued with `later()` flush after the handler returns, and each outcome is
+ * recorded on the invocation's log.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { currentLog } from "@sdxc/logger";
+import { isFailure } from "@sdxc/result";
+import { Mailer } from "./mailer.js";
+/**
+ * Creates a middleware that publishes a request-scoped mailer as `context.email`,
+ * resolving a container-based transport once per request. The `later()` queue
+ * flushes in a `finally` after `next()`; the response is already decided by then,
+ * so a failed deferred send is a warning on the invocation's log rather than an error.
+ *
+ * @param options - Transport and sender configuration; see {@link MailMiddlewareOptions}.
+ * @returns A middleware that populates `context.email`.
+ * @example
+ * router.use(mail({ transport: new CloudflareTransport(env.EMAIL), from: SENDER }));
+ */
+export default function mail(options) {
+    return async (context, next) => {
+        let transport = typeof options.transport === "function" ? options.transport(context) : options.transport;
+        let mailer = new Mailer({
+            transport,
+            from: options.from,
+            replyTo: options.replyTo,
+            headers: options.headers,
+        });
+        context.email = mailer;
+        try {
+            return await next();
+        }
+        finally {
+            let log = currentLog();
+            for (let result of await mailer.flush()) {
+                if (isFailure(result))
+                    log?.warn("mail.send_failed", { error: result.error.message });
+                else
+                    log
+                        ?.set({ mail: { sent: true } })
+                        .note("mail.sent", { message_id: result.data.messageId });
+            }
+        }
+    };
+}

package/dist/mime.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Assembles a normalized message into the raw RFC 5322 message a transport whose
+ * provider takes MIME has to hand over: folded headers, encoded words for
+ * non-ASCII text, a `multipart/alternative` body when both parts exist, and CRLF
+ * line endings throughout. It lives at the package root so any raw-MIME transport
+ * can reuse it and so its tests need no runtime-specific import.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { NormalizedMessage } from "./types.js";
+/**
+ * Assembles a normalized message into a raw RFC 5322 message, ordering plain text
+ * before HTML per RFC 2046 when both parts exist; with neither part, it yields an
+ * empty text part, since validation guarantees that case never reaches a transport.
+ *
+ * @param message - The normalized message a transport received.
+ * @returns The complete message, ready to hand to a provider that takes raw MIME.
+ * @example let raw = buildMimeMessage(message); // "From: ...\r\n\r\n..."
+ */
+export declare function buildMimeMessage(message: NormalizedMessage): string;

package/dist/mime.js

@@ -0,0 +1,374 @@
+/**
+ * Assembles a normalized message into the raw RFC 5322 message a transport whose
+ * provider takes MIME has to hand over: folded headers, encoded words for
+ * non-ASCII text, a `multipart/alternative` body when both parts exist, and CRLF
+ * line endings throughout. It lives at the package root so any raw-MIME transport
+ * can reuse it and so its tests need no runtime-specific import.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { formatAddress } from "./lib/address.js";
+/** Line ending every part of a MIME message uses, regardless of the host platform. */
+const CRLF = "\r\n";
+/** Length a header line should not exceed before it is folded, per RFC 5322. */
+const MAX_HEADER_LINE_LENGTH = 78;
+/** Length an encoded body line may reach, counting the soft break a wrap adds. */
+const MAX_ENCODED_LINE_LENGTH = 76;
+/** Opening of a base64 encoded word; UTF-8 because that is what the bodies are. */
+const ENCODED_WORD_PREFIX = "=?UTF-8?B?";
+/** Closing of an encoded word. */
+const ENCODED_WORD_SUFFIX = "?=";
+/** Longest an encoded word may be, delimiters included, per RFC 2047. */
+const MAX_ENCODED_WORD_LENGTH = 75;
+/** Characters an encoded word spends on its own delimiters rather than on content. */
+const ENCODED_WORD_OVERHEAD = ENCODED_WORD_PREFIX.length + ENCODED_WORD_SUFFIX.length;
+/** Smallest chunk a word may carry, so an unusually cramped line still makes progress. */
+const MIN_ENCODED_WORD_BYTES = 6;
+/** Printable ASCII, the only range a header value may hold without encoding. */
+const PRINTABLE_ASCII = /^[\x20-\x7E]*$/;
+/** Any of the three line endings a caller's body might arrive with. */
+const NEWLINE = /\r\n|\r|\n/g;
+/**
+ * Share of bytes that may need escaping before base64 becomes the cheaper
+ * encoding: quoted-printable spends 3 characters per escaped byte against
+ * base64's 4 per 3 bytes, so the two break even at one escaped byte in six.
+ */
+const QUOTED_PRINTABLE_ESCAPE_BUDGET = 1 / 6;
+/** Token a generated boundary is built on, using only characters RFC 2046 allows. */
+const BOUNDARY_PREFIX = "=_Part_";
+/** Day names in `Date#getUTCDay()` order; the header requires the English abbreviations. */
+const DAY_NAMES = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+/** Month names in `Date#getUTCMonth()` order, for the same reason as the day names. */
+const MONTH_NAMES = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+/**
+ * Headers this builder derives from the message itself. A custom header repeating
+ * one of these names is dropped rather than emitted twice, because a duplicate
+ * `From` or `Content-Type` is what makes a message get filed as spam.
+ */
+const RESERVED_HEADERS = new Set([
+    "bcc",
+    "cc",
+    "content-transfer-encoding",
+    "content-type",
+    "date",
+    "from",
+    "message-id",
+    "mime-version",
+    "reply-to",
+    "subject",
+    "to",
+]);
+/** Byte value of the horizontal tab, which may travel literally except at the end of a line. */
+const TAB = 9;
+/** Byte value of the line feed, which is message structure rather than part content. */
+const LINE_FEED = 10;
+/** Byte value of the carriage return, paired with the line feed in every break. */
+const CARRIAGE_RETURN = 13;
+/** Byte value of the space character, under the same end-of-line rule as the tab. */
+const SPACE = 32;
+/** Byte value of `-`, escaped at the start of a line so no body line can look like a boundary. */
+const HYPHEN = 45;
+/** Byte value of `=`, which quoted-printable always escapes because it is the escape character. */
+const EQUALS = 61;
+/** Highest byte quoted-printable may pass through literally. */
+const LAST_PRINTABLE = 126;
+/** Pads a number to the two digits the date header's fields are written with. */
+function pad(value) {
+    return String(value).padStart(2, "0");
+}
+/**
+ * Formats a date as an RFC 5322 `date-time`, always in UTC, using the numeric
+ * `+0000` zone, since some filters treat the obsolete `GMT` spelling as a sign of
+ * a hand-rolled sender.
+ */
+function formatDate(date) {
+    let day = DAY_NAMES[date.getUTCDay()] ?? DAY_NAMES[0];
+    let month = MONTH_NAMES[date.getUTCMonth()] ?? MONTH_NAMES[0];
+    let time = `${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}`;
+    return `${day}, ${pad(date.getUTCDate())} ${month} ${date.getUTCFullYear()} ${time} +0000`;
+}
+/** Base64-encodes bytes as one continuous string; callers below wrap it into lines. */
+function toBase64(bytes) {
+    let binary = "";
+    for (let byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+/** Wraps a chunk of bytes in the encoded-word delimiters RFC 2047 defines. */
+function toEncodedWord(bytes) {
+    return `${ENCODED_WORD_PREFIX}${toBase64(Uint8Array.from(bytes))}${ENCODED_WORD_SUFFIX}`;
+}
+/**
+ * Bytes one encoded word may carry without pushing a line already holding
+ * `reserved` characters past the limit; encoded words cannot be folded. Base64
+ * turns 3 bytes into 4 characters, so this is the largest multiple of 3 that fits.
+ */
+function encodedWordBytes(reserved) {
+    let available = Math.min(MAX_ENCODED_WORD_LENGTH, MAX_HEADER_LINE_LENGTH - reserved);
+    return Math.max(MIN_ENCODED_WORD_BYTES, Math.floor((available - ENCODED_WORD_OVERHEAD) / 4) * 3);
+}
+/**
+ * Encodes a header value as one or more RFC 2047 encoded words. Multi-byte
+ * characters are never split across words, since each decodes independently, and
+ * spaces travel inside the base64 because decoders drop whitespace between words.
+ *
+ * @param value - The text to encode.
+ * @param reserved - Characters the words must share their line with, such as `Subject: `.
+ */
+function encodeWords(value, reserved) {
+    let encoder = new TextEncoder();
+    let limit = encodedWordBytes(reserved);
+    let words = [];
+    let chunk = [];
+    for (let character of value) {
+        let bytes = encoder.encode(character);
+        if (chunk.length > 0 && chunk.length + bytes.length > limit) {
+            words.push(toEncodedWord(chunk));
+            chunk = [];
+        }
+        for (let byte of bytes)
+            chunk.push(byte);
+    }
+    if (chunk.length > 0 || words.length === 0)
+        words.push(toEncodedWord(chunk));
+    return words.join(" ");
+}
+/**
+ * Reports whether a header value can travel as written. A value that already
+ * looks like an encoded word is encoded anyway, so text a person typed as `=?x?=`
+ * reaches the receiving client exactly as typed.
+ */
+function isHeaderSafe(value) {
+    return PRINTABLE_ASCII.test(value) && !value.includes("=?");
+}
+/**
+ * Encodes unstructured header text, such as a subject, only when it has to be.
+ *
+ * @param name - Header name, whose length is what the first line has to give up.
+ * @param value - The value a caller wrote.
+ * @returns The value unchanged when it is plain ASCII, encoded words otherwise.
+ */
+function encodeHeaderText(name, value) {
+    if (isHeaderSafe(value))
+        return value;
+    return encodeWords(value, name.length + 2);
+}
+/**
+ * Formats a mailbox for a header, encoding a non-ASCII display name. Encoding
+ * replaces quoting, since a quoted encoded word reaches the reader literally, and
+ * reserves space for the address, fold indent, and list separator on that line.
+ */
+function encodeAddressHeader(address) {
+    let name = address.name?.trim();
+    if (!name || isHeaderSafe(name))
+        return formatAddress(address);
+    return `${encodeWords(name, address.email.length + 5)} <${address.email}>`;
+}
+/**
+ * Folds one header onto as many lines as it needs. The first line skips the colon's
+ * space, avoiding a bare `Name:` line, and a run with no space within the limit
+ * stays long, protecting the token it would otherwise split.
+ */
+function foldHeader(name, value) {
+    let lines = [];
+    let rest = `${name}: ${value}`;
+    let earliest = name.length + 1;
+    while (rest.length > MAX_HEADER_LINE_LENGTH) {
+        let breakAt = rest.lastIndexOf(" ", MAX_HEADER_LINE_LENGTH);
+        if (breakAt <= earliest)
+            breakAt = rest.indexOf(" ", MAX_HEADER_LINE_LENGTH);
+        if (breakAt === -1)
+            break;
+        lines.push(rest.slice(0, breakAt));
+        rest = rest.slice(breakAt);
+        earliest = 1;
+    }
+    lines.push(rest);
+    return lines.join(CRLF);
+}
+/** Rewrites every line ending as CRLF, which is the only one MIME allows. */
+function normalizeNewlines(value) {
+    return value.replace(NEWLINE, CRLF);
+}
+/**
+ * Reports whether quoted-printable has to escape a byte instead of passing it
+ * through. Line breaks are excluded: both encodings carry them structurally, so
+ * counting them would push short-lined plain text toward base64 for no gain.
+ */
+function requiresEscape(byte) {
+    if (byte === EQUALS)
+        return true;
+    if (byte > LAST_PRINTABLE)
+        return true;
+    if (byte === TAB || byte === LINE_FEED || byte === CARRIAGE_RETURN)
+        return false;
+    return byte < SPACE;
+}
+/** Escapes a byte as the `=XX` form quoted-printable uses, with the uppercase hex it prescribes. */
+function escapeByte(byte) {
+    return `=${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+}
+/**
+ * Encodes one byte for quoted-printable output. A leading `-` is escaped even
+ * though printable, so no encoded line can begin with a boundary's `--`; trailing
+ * whitespace is escaped too, since a relaying server may strip it and alter the body.
+ */
+function quotedPrintableToken(byte, atLineStart, atLineEnd) {
+    if (byte === HYPHEN && atLineStart)
+        return escapeByte(byte);
+    if ((byte === SPACE || byte === TAB) && atLineEnd)
+        return escapeByte(byte);
+    if (requiresEscape(byte))
+        return escapeByte(byte);
+    return String.fromCharCode(byte);
+}
+/**
+ * Encodes a single source line, soft-wrapping it as often as the length limit
+ * needs. A soft break is the decoder's signal to rejoin the line, so wrapping
+ * never changes the content it carries.
+ */
+function encodeQuotedPrintableLine(line) {
+    let bytes = new TextEncoder().encode(line);
+    let lines = [];
+    let current = "";
+    let lastIndex = bytes.length - 1;
+    for (let [index, byte] of bytes.entries()) {
+        let token = quotedPrintableToken(byte, current.length === 0, index === lastIndex);
+        if (current.length + token.length > MAX_ENCODED_LINE_LENGTH - 1) {
+            lines.push(`${current}=`);
+            current = "";
+            token = quotedPrintableToken(byte, true, index === lastIndex);
+        }
+        current += token;
+    }
+    lines.push(current);
+    return lines.join(CRLF);
+}
+/** Encodes a whole body as quoted-printable, keeping its hard line breaks intact. */
+function toQuotedPrintable(content) {
+    return normalizeNewlines(content).split(CRLF).map(encodeQuotedPrintableLine).join(CRLF);
+}
+/** Encodes a whole body as base64, wrapped to the line limit. */
+function toBase64Body(content) {
+    let base64 = toBase64(new TextEncoder().encode(normalizeNewlines(content)));
+    let lines = [];
+    for (let index = 0; index < base64.length; index += MAX_ENCODED_LINE_LENGTH) {
+        lines.push(base64.slice(index, index + MAX_ENCODED_LINE_LENGTH));
+    }
+    return lines.join(CRLF);
+}
+/**
+ * Encodes a body part with whichever transfer encoding costs less. Quoted-printable
+ * wins for ordinary text because the result stays readable in a raw message, and
+ * base64 takes over once escaping would inflate the body more than base64 does.
+ */
+function encodePart(contentType, content) {
+    let normalized = normalizeNewlines(content);
+    let bytes = new TextEncoder().encode(normalized);
+    let escaped = 0;
+    for (let byte of bytes)
+        if (requiresEscape(byte))
+            escaped++;
+    if (escaped > bytes.length * QUOTED_PRINTABLE_ESCAPE_BUDGET) {
+        return { contentType, encoding: "base64", body: toBase64Body(normalized) };
+    }
+    return { contentType, encoding: "quoted-printable", body: toQuotedPrintable(normalized) };
+}
+/**
+ * Picks a boundary no part can be confused with: the token carries a random UUID,
+ * and neither encoding can emit a line starting with `--` (base64 excludes `-`;
+ * quoted-printable escapes a leading one), checked directly against the bodies too.
+ */
+function selectBoundary(parts) {
+    let boundary = `${BOUNDARY_PREFIX}${crypto.randomUUID()}`;
+    while (parts.some((part) => part.body.includes(boundary))) {
+        boundary = `${BOUNDARY_PREFIX}${crypto.randomUUID()}`;
+    }
+    return boundary;
+}
+/** Wraps a message identifier in the angle brackets the header requires. */
+function toMessageIdHeader(messageId) {
+    let value = messageId.trim();
+    if (value.startsWith("<") && value.endsWith(">"))
+        return value;
+    return `<${value.replace(/^<|>$/g, "")}>`;
+}
+/**
+ * Builds the headers every message carries, in the order a reader of a raw message
+ * expects them. `Bcc` recipients are addressed through the envelope alone, since
+ * writing them into the message would expose them to everyone else.
+ */
+function buildHeaders(message) {
+    let headers = [
+        foldHeader("From", encodeAddressHeader(message.from)),
+        foldHeader("To", message.to.map(encodeAddressHeader).join(", ")),
+    ];
+    if (message.cc.length > 0) {
+        headers.push(foldHeader("Cc", message.cc.map(encodeAddressHeader).join(", ")));
+    }
+    if (message.replyTo.length > 0) {
+        headers.push(foldHeader("Reply-To", message.replyTo.map(encodeAddressHeader).join(", ")));
+    }
+    headers.push(foldHeader("Subject", encodeHeaderText("Subject", message.subject)), foldHeader("Date", formatDate(message.date)), foldHeader("Message-ID", toMessageIdHeader(message.messageId)), foldHeader("MIME-Version", "1.0"));
+    for (let [name, value] of Object.entries(message.headers)) {
+        if (RESERVED_HEADERS.has(name.toLowerCase()))
+            continue;
+        headers.push(foldHeader(name, encodeHeaderText(name, value)));
+    }
+    return headers;
+}
+/** Writes the `Content-*` headers that describe one part's type and encoding. */
+function buildContentHeaders(part) {
+    return [
+        foldHeader("Content-Type", `${part.contentType}; charset=utf-8`),
+        foldHeader("Content-Transfer-Encoding", part.encoding),
+    ];
+}
+/**
+ * Assembles a normalized message into a raw RFC 5322 message, ordering plain text
+ * before HTML per RFC 2046 when both parts exist; with neither part, it yields an
+ * empty text part, since validation guarantees that case never reaches a transport.
+ *
+ * @param message - The normalized message a transport received.
+ * @returns The complete message, ready to hand to a provider that takes raw MIME.
+ * @example let raw = buildMimeMessage(message); // "From: ...\r\n\r\n..."
+ */
+export function buildMimeMessage(message) {
+    let text = message.text ? encodePart("text/plain", message.text) : undefined;
+    let html = message.html ? encodePart("text/html", message.html) : undefined;
+    let headers = buildHeaders(message);
+    if (text && html) {
+        let boundary = selectBoundary([text, html]);
+        return [
+            ...headers,
+            foldHeader("Content-Type", `multipart/alternative; boundary="${boundary}"`),
+            "",
+            `--${boundary}`,
+            ...buildContentHeaders(text),
+            "",
+            text.body,
+            `--${boundary}`,
+            ...buildContentHeaders(html),
+            "",
+            html.body,
+            `--${boundary}--`,
+            "",
+        ].join(CRLF);
+    }
+    let part = text ?? html ?? encodePart("text/plain", "");
+    return [...headers, ...buildContentHeaders(part), "", part.body, ""].join(CRLF);
+}