@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/test-helpers/fake-imap.js

@@ -0,0 +1,508 @@
+import { Readable } from "node:stream";
+import { simpleParser } from "mailparser";
+/** An error shaped the way ImapFlow reports a tagged NO from the server. */
+export const imapError = (code, text) => Object.assign(new Error(`Command failed: [${code}] ${text}`), {
+    serverResponseCode: code,
+    responseText: text,
+});
+const nonexistent = (path) => imapError("NONEXISTENT", `Mailbox doesn't exist: ${path}`);
+export const eml = (headers, body = "body") => Buffer.from([
+    ...Object.entries({
+        From: "Sender <sender@example.com>",
+        To: "me@example.com",
+        Subject: "Hello",
+        "Content-Type": "text/plain",
+        ...headers,
+    })
+        .filter(([, value]) => value !== "")
+        .map(([name, value]) => `${name}: ${value}`),
+    "",
+    body,
+].join("\r\n"));
+const toAddresses = (value) => (value?.value ?? [])
+    .filter((entry) => entry.address)
+    .map((entry) => {
+    const [mailbox, host] = (entry.address ?? "").split("@");
+    return { name: entry.name || undefined, mailbox, host };
+});
+const single = (value) => Array.isArray(value) ? value[0] : value;
+const messageIdOf = (raw) => /^Message-ID:\s*(.+?)\s*$/im.exec(raw.toString("utf8"))?.[1] ?? "";
+const UID_RANGE = /^(\d+)(?::(\d+|\*))?$/;
+/** Whether `uid` is in an IMAP sequence set such as `3`, `1,4` or `2:*`. */
+const inUidSet = (set, uid, highest) => set.split(",").some((part) => {
+    const match = UID_RANGE.exec(part);
+    if (!match)
+        throw new Error(`the fake server cannot read UID set ${set}`);
+    const from = Number(match[1]);
+    const to = match[2] === undefined
+        ? from
+        : match[2] === "*"
+            ? Math.max(highest, from)
+            : Number(match[2]);
+    return uid >= Math.min(from, to) && uid <= Math.max(from, to);
+});
+/**
+ * An IMAP server held in memory, behind the same connection port the imapflow
+ * adapter implements. It refuses what a server refuses: a folder that does not
+ * exist is `NONEXISTENT`, a transfer or APPEND to one is `TRYCREATE`, and a
+ * SEARCH it does not model throws rather than matching everything. FETCH rows
+ * are derived from the raw bytes the way the adapter derives them. `log`
+ * records every command that would reach the wire.
+ */
+export class FakeImapServer {
+    folders = new Map();
+    modseq = 1n;
+    nextUidValidity = 1000;
+    log = [];
+    failNext = {};
+    ignoreNext = new Set();
+    condstore = true;
+    uidplus = true;
+    namespacePrefix = "";
+    connections = 0;
+    onFetchBody = async () => { };
+    addFolder(path, options = {}) {
+        if (this.folders.has(path))
+            throw new Error(`${path} already exists`);
+        this.folders.set(path, {
+            uidValidity: options.uidValidity ?? 7,
+            uidNext: 1,
+            attributes: options.attributes ?? [],
+            subscribed: true,
+            messages: new Map(),
+        });
+    }
+    hasFolder(path) {
+        return this.folders.has(path);
+    }
+    /** Another client deleted the folder. */
+    removeFolder(path) {
+        if (!this.folders.delete(path))
+            throw nonexistent(path);
+    }
+    isSubscribed(path) {
+        return this.folder(path).subscribed;
+    }
+    folder(path) {
+        const folder = this.folders.get(path);
+        if (!folder)
+            throw nonexistent(path);
+        return folder;
+    }
+    paths() {
+        return [...this.folders.keys()];
+    }
+    deliver(path, raw, options = {}) {
+        const folder = this.folder(path);
+        const uid = options.uid ?? folder.uidNext;
+        if (folder.messages.has(uid))
+            throw new Error(`uid ${uid} is taken in ${path}`);
+        folder.uidNext = Math.max(folder.uidNext, uid + 1);
+        folder.messages.set(uid, {
+            raw,
+            flags: new Set(options.flags ?? []),
+            modseq: this.modseq++,
+            internalDate: new Date(1_700_000_000_000 + uid * 1000),
+            bodyStructure: options.bodyStructure,
+        });
+        return uid;
+    }
+    /** Another client expunged the message. */
+    expunge(path, uid) {
+        if (!this.folder(path).messages.delete(uid)) {
+            throw new Error(`no uid ${uid} in ${path}`);
+        }
+    }
+    /** Another client expunged everything in the folder. */
+    empty(path) {
+        this.folder(path).messages.clear();
+    }
+    /** One STORE from another client: every message it touches shares the new mod-sequence. */
+    store(path, uids, flags) {
+        const modseq = this.modseq++;
+        for (const uid of uids) {
+            const message = this.folder(path).messages.get(uid);
+            if (!message)
+                throw new Error(`no uid ${uid} in ${path}`);
+            message.flags = new Set(flags);
+            message.modseq = modseq;
+        }
+    }
+    /** The server renumbered the folder: a new UIDVALIDITY, UIDs from 1. */
+    renumber(path, uidValidity) {
+        const folder = this.folder(path);
+        const messages = [...folder.messages.values()];
+        folder.uidValidity = uidValidity;
+        folder.messages = new Map(messages.map((message, i) => [i + 1, message]));
+        folder.uidNext = messages.length + 1;
+    }
+    flagsOf(path, uid) {
+        return [...(this.folder(path).messages.get(uid)?.flags ?? [])].sort();
+    }
+    uids(path, messageIdHeader) {
+        return [...this.folder(path).messages]
+            .filter(([, message]) => messageIdHeader === undefined ||
+            messageIdOf(message.raw) === messageIdHeader)
+            .map(([uid]) => uid);
+    }
+    /** What the server holds in a folder, as another client would read it. */
+    messages(path) {
+        return [...this.folder(path).messages].map(([uid, message]) => ({
+            uid,
+            messageIdHeader: messageIdOf(message.raw),
+            flags: [...message.flags].sort(),
+            raw: message.raw,
+        }));
+    }
+    /** The server changed UIDVALIDITY without renumbering what it serves. */
+    setUidValidity(path, uidValidity) {
+        this.folder(path).uidValidity = uidValidity;
+    }
+    uidValidityOf(path) {
+        return this.folder(path).uidValidity;
+    }
+    highestModseq() {
+        return this.modseq - 1n;
+    }
+    bumpModseq() {
+        return this.modseq++;
+    }
+    commands(verb) {
+        return this.log.filter((line) => line.startsWith(`${verb} `));
+    }
+    run(verb, detail) {
+        this.log.push(`${verb} ${detail}`);
+        const failure = this.failNext[verb];
+        if (failure) {
+            delete this.failNext[verb];
+            throw failure;
+        }
+    }
+    createFolder(path) {
+        if (this.folders.has(path))
+            return false;
+        this.nextUidValidity += 1;
+        this.addFolder(path, { uidValidity: this.nextUidValidity });
+        return true;
+    }
+    renameFolder(oldPath, newPath) {
+        this.folder(oldPath);
+        if (this.folders.has(newPath)) {
+            throw imapError("ALREADYEXISTS", `Mailbox already exists: ${newPath}`);
+        }
+        for (const [path, folder] of [...this.folders]) {
+            if (path !== oldPath && !path.startsWith(`${oldPath}/`))
+                continue;
+            this.folders.delete(path);
+            this.folders.set(newPath + path.slice(oldPath.length), folder);
+        }
+    }
+    deleteFolder(path) {
+        if (path === "INBOX")
+            throw imapError("CANNOT", "Cannot delete INBOX");
+        this.folder(path);
+        for (const key of [...this.folders.keys()]) {
+            if (key === path || key.startsWith(`${path}/`))
+                this.folders.delete(key);
+        }
+    }
+    connection() {
+        this.connections += 1;
+        return new FakeImapConnection(this);
+    }
+}
+export class FakeImapConnection {
+    server;
+    state = "authenticated";
+    isConnected = true;
+    selected = null;
+    constructor(server) {
+        this.server = server;
+    }
+    open() {
+        if (this.selected === null)
+            throw new Error("No mailbox selected");
+        return this.server.folder(this.selected);
+    }
+    uidList = (uids) => uids.join(",");
+    connect = async () => { };
+    disconnect = async () => { };
+    getNamespaces = async () => {
+        this.server.run("NAMESPACE", "");
+        return {
+            personal: [{ prefix: this.server.namespacePrefix, delimiter: "/" }],
+            other: [],
+            shared: [],
+        };
+    };
+    listMailboxes = async () => {
+        this.server.run("LIST", "");
+        return this.server.paths().map((fullPath) => {
+            const separator = fullPath.lastIndexOf("/");
+            return {
+                fullPath,
+                name: separator === -1 ? fullPath : fullPath.slice(separator + 1),
+                delimiter: "/",
+                attributes: this.server.folder(fullPath).attributes,
+                parentPath: separator === -1 ? null : fullPath.slice(0, separator),
+            };
+        });
+    };
+    openBox = async (path, readOnly = false) => {
+        this.server.run(readOnly ? "EXAMINE" : "SELECT", path);
+        const folder = this.server.folder(path);
+        this.selected = path;
+        return {
+            name: path,
+            readOnly,
+            uidvalidity: folder.uidValidity,
+            uidnext: folder.uidNext,
+            flags: [],
+            permFlags: [],
+            persistentUIDs: true,
+            messages: { total: folder.messages.size, new: 0 },
+            newKeywords: false,
+        };
+    };
+    closeBox = async () => {
+        this.server.run("CLOSE", `${this.selected}`);
+        this.selected = null;
+    };
+    search = async (criteria) => {
+        this.server.run("SEARCH", `${this.selected} ${JSON.stringify(criteria)}`);
+        const folder = this.open();
+        const all = [...folder.messages.keys()];
+        const [first] = criteria;
+        if (criteria.length === 1 && first === "ALL")
+            return all;
+        if (criteria.length === 1 &&
+            Array.isArray(first) &&
+            first.length === 2 &&
+            first[0] === "UID") {
+            const highest = Math.max(0, ...all);
+            return all.filter((uid) => inUidSet(String(first[1]), uid, highest));
+        }
+        if (criteria.length === 1 &&
+            Array.isArray(first) &&
+            first.length === 3 &&
+            first[0] === "HEADER" &&
+            String(first[1]).toLowerCase() === "message-id") {
+            return all.filter((uid) => messageIdOf(folder.messages.get(uid)?.raw ?? Buffer.alloc(0)) ===
+                first[2]);
+        }
+        throw new Error(`the fake server does not answer SEARCH ${JSON.stringify(criteria)}`);
+    };
+    toImapMessage = async (uid, stored) => {
+        const parsed = await simpleParser(stored.raw);
+        const header = (name) => {
+            const value = parsed.headers.get(name);
+            return typeof value === "string" ? value : "";
+        };
+        const contentType = single(parsed.headers.get("content-type"));
+        const headerStructure = {
+            type: contentType?.value ?? "text/plain",
+            parameters: contentType?.params,
+            encoding: header("content-transfer-encoding") || "7bit",
+            size: stored.raw.length,
+        };
+        const references = parsed.references;
+        return {
+            uid,
+            seq: uid,
+            flags: [...stored.flags],
+            internalDate: stored.internalDate,
+            size: stored.raw.length,
+            envelope: {
+                date: parsed.date?.toISOString() ?? "",
+                subject: parsed.subject ?? "",
+                from: toAddresses(single(parsed.from)),
+                sender: toAddresses(single(parsed.from)),
+                replyTo: toAddresses(single(parsed.replyTo)),
+                to: toAddresses(single(parsed.to)),
+                cc: toAddresses(single(parsed.cc)),
+                bcc: [],
+                inReplyTo: header("in-reply-to"),
+                messageId: header("message-id"),
+            },
+            references: references === undefined
+                ? undefined
+                : Array.isArray(references)
+                    ? references
+                    : [references],
+            ...(stored.bodyStructure === null
+                ? {}
+                : { bodyStructure: stored.bodyStructure ?? headerStructure }),
+            ...(this.server.condstore ? { modseq: stored.modseq.toString() } : {}),
+        };
+    };
+    fetchRows = async (uids) => {
+        const folder = this.open();
+        const rows = [];
+        for (const uid of uids) {
+            const stored = folder.messages.get(uid);
+            if (stored)
+                rows.push(await this.toImapMessage(uid, stored));
+        }
+        return rows;
+    };
+    fetchMessages = async (uids) => {
+        this.server.run("FETCH", `${this.selected} ${this.uidList(uids)}`);
+        return this.fetchRows(uids);
+    };
+    supportsCondstore = () => this.server.condstore;
+    fetchMessagesChangedSince = async (sinceModseq) => {
+        this.server.run("FETCH", `${this.selected} 1:* CHANGEDSINCE ${sinceModseq}`);
+        if (!this.server.condstore) {
+            throw new Error("CHANGEDSINCE requires CONDSTORE");
+        }
+        const folder = this.open();
+        const rows = [];
+        for (const [uid, stored] of folder.messages) {
+            if (stored.modseq > sinceModseq) {
+                rows.push(await this.toImapMessage(uid, stored));
+            }
+        }
+        return rows;
+    };
+    fetchEnvelopeSnapshots = async (uids) => {
+        this.server.run("FETCH", `${this.selected} ${this.uidList(uids)} ENVELOPE`);
+        const rows = await this.fetchRows(uids);
+        return rows.map((row) => ({
+            uid: row.uid,
+            messageId: row.envelope?.messageId ?? "",
+            internalDate: row.internalDate,
+        }));
+    };
+    fetchMessageBody = async (uid) => {
+        this.server.run("BODY", `${this.selected} ${uid}`);
+        await this.server.onFetchBody(uid);
+        return this.open().messages.get(uid)?.raw ?? null;
+    };
+    async *fetchMessageBodies(uids) {
+        this.server.run("BODY", `${this.selected} ${this.uidList(uids)}`);
+        const folder = this.open();
+        for (const uid of uids) {
+            const stored = folder.messages.get(uid);
+            if (stored)
+                yield { uid, source: Readable.from([stored.raw]) };
+        }
+    }
+    touch = (detail, uids, change) => {
+        this.server.run("STORE", `${this.selected} ${this.uidList(uids)} ${detail}`);
+        const folder = this.open();
+        const modseq = this.server.bumpModseq();
+        for (const uid of uids) {
+            const stored = folder.messages.get(uid);
+            if (!stored)
+                continue;
+            change(stored.flags);
+            stored.modseq = modseq;
+        }
+    };
+    addFlags = async (uids, flags) => this.touch(`+${flags.join(" ")}`, uids, (set) => {
+        for (const flag of flags)
+            set.add(flag);
+    });
+    removeFlags = async (uids, flags) => this.touch(`-${flags.join(" ")}`, uids, (set) => {
+        for (const flag of flags)
+            set.delete(flag);
+    });
+    setFlags = async (uids, flags) => this.touch(flags.join(" "), uids, (set) => {
+        set.clear();
+        for (const flag of flags)
+            set.add(flag);
+    });
+    createMailbox = async (path) => {
+        const resolved = this.server.namespacePrefix + path;
+        this.server.run("CREATE", resolved);
+        return { path: resolved, created: this.server.createFolder(resolved) };
+    };
+    deleteMailbox = async (path) => {
+        this.server.run("DELETE", path);
+        this.server.deleteFolder(path);
+        return { path };
+    };
+    renameMailbox = async (oldPath, requested) => {
+        const newPath = this.server.namespacePrefix + requested;
+        this.server.run("RENAME", `${oldPath} ${newPath}`);
+        this.server.renameFolder(oldPath, newPath);
+        return { path: oldPath, newPath };
+    };
+    subscribeMailbox = async (path) => {
+        this.server.run("SUBSCRIBE", path);
+        this.server.folder(path).subscribed = true;
+    };
+    unsubscribeMailbox = async (path) => {
+        this.server.run("UNSUBSCRIBE", path);
+        this.server.folder(path).subscribed = false;
+    };
+    transfer = (verb, uids, destination) => {
+        this.server.run(verb, `${this.selected} ${this.uidList(uids)} ${destination}`);
+        if (!this.server.hasFolder(destination)) {
+            throw imapError("TRYCREATE", `Mailbox doesn't exist: ${destination}`);
+        }
+        const target = this.server.folder(destination);
+        const uidMap = new Map();
+        if (this.server.ignoreNext.delete(verb)) {
+            return { destination, uidValidity: target.uidValidity, uidMap };
+        }
+        const source = this.open();
+        for (const uid of uids) {
+            const stored = source.messages.get(uid);
+            if (!stored)
+                continue;
+            const next = target.uidNext++;
+            target.messages.set(next, {
+                ...stored,
+                flags: new Set(stored.flags),
+                modseq: this.server.bumpModseq(),
+            });
+            if (verb === "MOVE")
+                source.messages.delete(uid);
+            if (this.server.uidplus)
+                uidMap.set(uid, next);
+        }
+        return { destination, uidValidity: target.uidValidity, uidMap };
+    };
+    moveMessages = async (uids, destination) => this.transfer("MOVE", uids, destination);
+    copyMessages = async (uids, destination) => this.transfer("COPY", uids, destination);
+    deleteMessages = async (uids) => {
+        this.server.run("EXPUNGE", `${this.selected} ${this.uidList(uids)}`);
+        const folder = this.open();
+        let deleted = 0;
+        for (const uid of uids) {
+            if (folder.messages.delete(uid))
+                deleted++;
+        }
+        return deleted;
+    };
+    getMailboxStatus = async (path) => {
+        this.server.run("STATUS", path);
+        const folder = this.server.folder(path);
+        const messages = [...folder.messages.values()];
+        return {
+            messages: messages.length,
+            recent: 0,
+            unseen: messages.filter((message) => !message.flags.has("\\Seen")).length,
+            uidNext: folder.uidNext,
+            uidValidity: folder.uidValidity,
+            highestModseq: this.server.condstore
+                ? this.server.highestModseq().toString()
+                : "0",
+            deletedCount: messages.filter((message) => message.flags.has("\\Deleted"))
+                .length,
+        };
+    };
+    append = async (mailbox, message, flags = []) => {
+        this.server.run("APPEND", mailbox);
+        if (!this.server.hasFolder(mailbox)) {
+            throw imapError("TRYCREATE", `Mailbox doesn't exist: ${mailbox}`);
+        }
+        const uid = this.server.deliver(mailbox, Buffer.isBuffer(message) ? message : Buffer.from(message), { flags });
+        return {
+            destination: mailbox,
+            uidValidity: this.server.folder(mailbox).uidValidity,
+            uid,
+        };
+    };
+}

package/dist/test-helpers/folder-roles.d.ts

@@ -0,0 +1,34 @@
+import type { IMailboxSpecialUseRepository } from "@remit/data-ports";
+import type { JunkRoleMailboxes, RoleResolution } from "@remit/data-ports/folder-role";
+type RoleMailbox = {
+    mailboxId: string;
+    fullPath: string;
+};
+/**
+ * The evidence-carrying answer behind `findTrashMailbox`, so a stub that names
+ * a Trash folder answers both reads consistently. A named folder stands in as
+ * server-flagged: the suites using this are testing something other than how
+ * the role was decided.
+ */
+export declare const trashRole: (trash: RoleMailbox | null) => RoleResolution<RoleMailbox>;
+/**
+ * A folder-role map for an account that has appointed nothing and whose server
+ * flags nothing — every mailbox is an ordinary folder. The stand-in for the
+ * many suites that construct `MessageSyncService` for a reason unrelated to
+ * which folder holds which role.
+ */
+export declare const noFolderRoles: IMailboxSpecialUseRepository;
+/** A folder-role map naming the mailboxes that hold Junk and Trash. */
+export declare const folderRoles: (roles: {
+    junkMailboxId?: string;
+    trashMailboxId?: string;
+}) => IMailboxSpecialUseRepository;
+/** An account whose config resolves no Junk and no Trash anywhere. */
+export declare const NO_JUNK_ROLES: JunkRoleMailboxes;
+/** The same account, as the resolved map `saveMessage` is handed. */
+export declare const NO_FOLDER_ROLES: {
+    junkMailboxId: null;
+    trashMailboxId: null;
+    configJunkRoles: JunkRoleMailboxes;
+};
+export {};

package/dist/test-helpers/folder-roles.js

@@ -0,0 +1,47 @@
+/**
+ * The evidence-carrying answer behind `findTrashMailbox`, so a stub that names
+ * a Trash folder answers both reads consistently. A named folder stands in as
+ * server-flagged: the suites using this are testing something other than how
+ * the role was decided.
+ */
+export const trashRole = (trash) => trash ? { kind: "flagged", mailbox: trash } : { kind: "none" };
+/**
+ * A folder-role map for an account that has appointed nothing and whose server
+ * flags nothing — every mailbox is an ordinary folder. The stand-in for the
+ * many suites that construct `MessageSyncService` for a reason unrelated to
+ * which folder holds which role.
+ */
+export const noFolderRoles = {
+    findJunkMailbox: async () => null,
+    findTrashMailbox: async () => null,
+    resolveTrashRole: async () => trashRole(null),
+    resolveJunkRolesForConfig: async () => NO_JUNK_ROLES,
+};
+/** A folder-role map naming the mailboxes that hold Junk and Trash. */
+export const folderRoles = (roles) => {
+    const trash = roles.trashMailboxId
+        ? { mailboxId: roles.trashMailboxId, fullPath: roles.trashMailboxId }
+        : null;
+    return {
+        findJunkMailbox: async () => roles.junkMailboxId
+            ? { mailboxId: roles.junkMailboxId, fullPath: roles.junkMailboxId }
+            : null,
+        findTrashMailbox: async () => trash,
+        resolveTrashRole: async () => trashRole(trash),
+        resolveJunkRolesForConfig: async () => ({
+            junkMailboxIds: roles.junkMailboxId ? [roles.junkMailboxId] : [],
+            trashMailboxIds: roles.trashMailboxId ? [roles.trashMailboxId] : [],
+        }),
+    };
+};
+/** An account whose config resolves no Junk and no Trash anywhere. */
+export const NO_JUNK_ROLES = {
+    junkMailboxIds: [],
+    trashMailboxIds: [],
+};
+/** The same account, as the resolved map `saveMessage` is handed. */
+export const NO_FOLDER_ROLES = {
+    junkMailboxId: null,
+    trashMailboxId: null,
+    configJunkRoles: NO_JUNK_ROLES,
+};

package/dist/test-helpers/mime-tree-generator.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Deterministic random MIME tree generator for the body-part mapper
+ * property test (issue #395 PR C).
+ *
+ * Three pieces:
+ *
+ *   1. `createRng(seed)` — small xorshift32 PRNG. Same seed → same sequence
+ *      so failing CI runs reproduce locally via `MAPPER_PROPERTY_SEED`.
+ *
+ *   2. `generateMimeTree(rng, opts)` — synthesise a random tree:
+ *        - root is either a leaf or a `multipart/<mixed|alternative|related>`
+ *        - multiparts have N ∈ [1, 5] children
+ *        - each child is leaf or multipart, depth capped at `maxDepth` (4)
+ *        - leaves draw uniformly from a fixed set of media types
+ *        - some leaves get a `dispositionFilename`, some a `contentId`,
+ *          some both, most neither
+ *        - leaves are mostly non-empty; a small fraction get zero bytes to
+ *          exercise the empty-leaf short-circuit in the mapper
+ *
+ *   3. `renderEml(tree)` + `treeToBodyParts(tree)` — produce a paired
+ *      `.eml` string and the `MapperInput[]` rows the mime-walker would
+ *      emit for that tree. Both walk the same tree, so partPath, content
+ *      type, filename and contentId stay aligned by construction.
+ *
+ * No external deps. Built on Node primitives only (`node:buffer`,
+ * `node:string_decoder` via `Buffer.from(..., 'base64')`).
+ */
+import { Buffer } from "node:buffer";
+import type { BodyPartItem } from "@remit/data-ports";
+export type MapperInput = Pick<BodyPartItem, "partPath" | "isMultipart" | "mediaType" | "mediaSubtype" | "contentId" | "dispositionFilename" | "disposition"> & {
+    sizeOctets?: number;
+};
+/** Tiny xorshift32 PRNG. `next()` returns a float in [0, 1). */
+export interface Rng {
+    next(): number;
+    int(maxExclusive: number): number;
+    pick<T>(items: readonly T[]): T;
+    bool(probability: number): boolean;
+}
+export declare const createRng: (seed: number) => Rng;
+export type MultipartSubtypeName = "mixed" | "alternative" | "related";
+export type LeafContentType = "text/plain" | "text/html" | "application/pdf" | "image/png" | "application/octet-stream";
+export interface LeafNode {
+    kind: "leaf";
+    contentType: LeafContentType;
+    /** Decoded body bytes the renderer will encode into the EML. */
+    bytes: Buffer;
+    /** Optional `filename=` attribute on the leaf. */
+    filename?: string;
+    /** Optional `Content-ID:` header value (without angle brackets). */
+    contentId?: string;
+    /** "inline" or "attachment" Content-Disposition. */
+    disposition?: "inline" | "attachment";
+}
+export interface MultipartNode {
+    kind: "multipart";
+    subtype: MultipartSubtypeName;
+    children: MimeTreeNode[];
+}
+export type MimeTreeNode = LeafNode | MultipartNode;
+export interface GenerateOptions {
+    maxDepth?: number;
+    /** Probability the root is a multipart (vs. a single flat leaf). */
+    rootMultipartProb?: number;
+    /** Probability an empty buffer is used for a leaf body. */
+    emptyLeafProb?: number;
+}
+export declare const generateMimeTree: (rng: Rng, opts?: GenerateOptions) => MimeTreeNode;
+/**
+ * Walk the tree the same way `mime-walker.ts` would and emit
+ * `MapperInput[]` in declaration order. Root path is "0"; subsequent
+ * leaves are "1", "2", "1.1", "1.2", ... — matches `walkMimeStructure`.
+ */
+export declare const treeToBodyParts: (tree: MimeTreeNode) => MapperInput[];
+export interface RenderOptions {
+    seed: number;
+    subject?: string;
+    from?: string;
+    to?: string;
+    messageId?: string;
+}
+export declare const renderEml: (tree: MimeTreeNode, opts: RenderOptions) => string;