@wirecat/cli-core 0.471.0 → 0.472.0

package/dist/mail/testing/contract.js

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import { GMAIL_ALL_MAIL } from "../folders.js";
+import { parseMail } from "../parse.js";
+import { syncMail } from "../sync.js";
+const SINCE = new Date("2026-09-01T00:00:00Z");
+/** The fixtures every adapter is seeded with: its harness makes a mailbox that holds exactly these. */
+export const CONTRACT_MAIL = [1, 2, 3].map((n) => ({
+    uid: String(100 + n),
+    messageId: String(9000 + n),
+    threadId: String(n === 3 ? 9001 : 9000 + n),
+    receivedAt: `2026-09-${String(10 + n).padStart(2, "0")}T08:00:00Z`,
+    subject: `Contract subject ${n}`,
+    from: ["Rin Example", "rin@example.test"],
+    to: [[null, "owner@example.test"]],
+    text: `Contract body ${n}`,
+}));
+/** What every adapter must answer; the optional members are checked only where the source has them. */
+export const mailSourceContract = (make) => {
+    const test = (name, check) => ({
+        name,
+        run: async () => check(await make()),
+    });
+    const folder = GMAIL_ALL_MAIL;
+    return [
+        test("lists each message once with a stable id, a thread id and a time inside the window", async (source) => {
+            const listed = await source.list(SINCE, folder);
+            assert.equal(listed.length, CONTRACT_MAIL.length);
+            assert.equal(new Set(listed.map(({ messageId }) => messageId)).size, listed.length);
+            for (const item of listed) {
+                assert.ok(item.uid && item.messageId && item.threadId, "ids");
+                assert.ok(Date.parse(item.receivedAt) >= SINCE.getTime(), "inside the window");
+            }
+        }),
+        test("lists a stable id for the same message on every listing", async (source) => {
+            const ids = async () => (await source.list(SINCE, folder)).map(({ messageId }) => messageId).sort();
+            assert.deepEqual(await ids(), await ids());
+        }),
+        test("reads the sender and recipients with `headers`", async (source) => {
+            const listed = await source.list(SINCE, folder, { headers: true });
+            for (const item of listed) {
+                assert.equal(item.headers?.from, "rin@example.test");
+                assert.deepEqual(item.headers?.to, ["owner@example.test"]);
+            }
+        }),
+        test("lists only a search's UIDs, and names the UIDVALIDITY", async (source) => {
+            if (source.search === undefined)
+                return;
+            const searched = await source.search(SINCE, folder);
+            assert.equal(searched.uids.length, CONTRACT_MAIL.length);
+            const [first] = searched.uids;
+            const listed = await source.list(SINCE, folder, {
+                searched: { ...searched, uids: first === undefined ? [] : [first] },
+            });
+            assert.deepEqual(listed.map(({ uid }) => uid), first === undefined ? [] : [first]);
+        }),
+        test("returns each message's bytes in order, and one that cannot be read as an Error, not a failed call", async (source) => {
+            const listed = await source.list(SINCE, folder);
+            const raws = await source.fetchRaw(listed);
+            assert.equal(raws.length, listed.length);
+            for (const [index, raw] of raws.entries()) {
+                assert.ok(raw instanceof Uint8Array, "bytes");
+                const parsed = await parseMail(raw, 10_000);
+                assert.match(parsed.subject ?? "", /^Contract subject \d$/);
+                assert.equal(parsed.subject, CONTRACT_MAIL.find(({ messageId }) => messageId === listed[index]?.messageId)?.subject);
+            }
+            const [first] = listed;
+            if (first !== undefined) {
+                const [unknown] = await source.fetchRaw([{ ...first, uid: "999999" }]);
+                assert.ok(unknown instanceof Error);
+            }
+        }),
+        test("finds messages by id, leaving out one that is gone", async (source) => {
+            if (source.find === undefined)
+                return;
+            const found = await source.find(["9001", "no-such-id"], folder);
+            assert.deepEqual(found.map(({ messageId }) => messageId), ["9001"]);
+        }),
+        test("says which UIDs a folder still holds", async (source) => {
+            if (source.present === undefined)
+                return;
+            assert.deepEqual(await source.present(["101", "999999"], folder), ["101"]);
+        }),
+    ];
+};
+/** What `syncMail` must do with any adapter: store each message once under the address's account, and only once. */
+export const mailSyncContract = (make) => {
+    const address = "owner@example.test";
+    const account = { address };
+    return [
+        {
+            name: "stores each message as an email of its thread under the address's account, and a rerun adds nothing",
+            run: async () => {
+                const { source, store } = await make();
+                const first = await syncMail(source, store, { account, since: SINCE });
+                assert.equal(first.saved, CONTRACT_MAIL.length);
+                assert.equal(first.complete, true);
+                const stored = await store.accounts.storedAccount({ provider: "email", account: address });
+                const emails = await store.mail.emails({ accountId: stored.id });
+                assert.deepEqual(emails.map(({ externalId }) => externalId).sort(), CONTRACT_MAIL.map(({ messageId }) => messageId));
+                const again = await syncMail(source, store, { account, since: SINCE });
+                assert.equal(again.saved, 0);
+                assert.equal(again.deleted, 0);
+            },
+        },
+    ];
+};

package/dist/mail/testing/fake.d.ts

@@ -0,0 +1,61 @@
+import type { FileStamp } from "../resume.js";
+import type { MailSource } from "../source.js";
+export type FakePerson = [name: string | null, address: string];
+/** One message of a fake Gmail-like mailbox: its ids, envelope and the parts `rawOf` writes as RFC 5322. */
+export interface FakeMail {
+    uid: string;
+    messageId: string;
+    threadId: string;
+    receivedAt: string;
+    subject: string;
+    from: FakePerson;
+    to: FakePerson[];
+    cc?: FakePerson[];
+    text?: string;
+    html?: string;
+    listId?: string;
+    attachment?: {
+        name: string;
+        mime: string;
+        content: string;
+    };
+    extraHeaders?: string[];
+    /** Plain label names, as a listing gives them; `flagged` adds Starred. */
+    labels?: string[];
+    seen?: boolean;
+    flagged?: boolean;
+    /** `trash` puts it in the trash folder; otherwise it is in All Mail, which INBOX also shows. */
+    folder?: "trash";
+}
+/** The mailbox a fake source reads live, so a test changes it between syncs; the switches make the source fail. */
+export interface FakeMailbox {
+    messages: FakeMail[];
+    /** All Mail under the account's language, as Gmail names it. */
+    allMail?: string;
+    trash?: string;
+    validity?: number;
+    /** Each answer of `search` and `list` ends in this failure. */
+    searchFails?: string;
+    /** A refused header fetch fails the whole listing. */
+    headersFail?: boolean;
+    moveFails?: boolean;
+    /** UIDs whose raw bytes cannot be read: `fetchRaw` answers an Error for each of them, and only for them. */
+    unreadable?: string[];
+    /** What the source was asked: the UIDs of each listing, and `msgid:<id>` for each `find`. */
+    asked?: string[];
+}
+/** The RFC 5322 bytes of a fake message, CRLF line ends, the body and attachment in base64. */
+export declare const rawOf: (m: FakeMail) => Uint8Array;
+/**
+ * An in-memory mail source with Gmail's shape: ids and threads that outlive a folder, labels and flags, UIDVALIDITY,
+ * a trash a move reaches, and All Mail under the account's language. The sync tests and the adapter contract run on it.
+ */
+export declare const fakeMailSource: (mailbox: FakeMailbox) => MailSource;
+/**
+ * A snapshot source, as an mbox file is: every message since a date with no UIDs, one stamp that changes when the
+ * file does, and no search, find or folders. `archive.mails` and `archive.stamp` are read live.
+ */
+export declare const fakeArchiveSource: (archive: {
+    mails: FakeMail[];
+    stamp: FileStamp;
+}) => MailSource;

package/dist/mail/testing/fake.js

@@ -0,0 +1,136 @@
+import { CliError } from "@wirecat/cli-base";
+import { GMAIL_ALL_MAIL } from "../folders.js";
+import { headersOf } from "../headers.js";
+const TRASH = "[Gmail]/Bin";
+const person = ([name, address]) => (name ? `"${name}" <${address}>` : address);
+/** The RFC 5322 bytes of a fake message, CRLF line ends, the body and attachment in base64. */
+export const rawOf = (m) => {
+    const type = m.html ? "text/html" : "text/plain";
+    const headers = [
+        `From: ${person(m.from)}`,
+        `To: ${m.to.map(person).join(", ")}`,
+        ...(m.cc ? [`Cc: ${m.cc.map(person).join(", ")}`] : []),
+        ...(m.listId ? [`List-Id: News <${m.listId}>`, `List-Unsubscribe: <mailto:leave@${m.listId}>`] : []),
+        `Subject: ${m.subject}`,
+        `Message-ID: <${m.messageId}@example.test>`,
+        `Date: ${new Date(m.receivedAt).toUTCString()}`,
+        "MIME-Version: 1.0",
+        ...(m.extraHeaders ?? []),
+    ];
+    const body = Buffer.from(m.html ?? m.text ?? "").toString("base64");
+    if (!m.attachment)
+        return Buffer.from(`${[...headers, `Content-Type: ${type}; charset=utf-8`, "Content-Transfer-Encoding: base64"].join("\r\n")}\r\n\r\n${body}\r\n`);
+    const parts = [
+        `--b1\r\nContent-Type: ${type}; charset=utf-8\r\nContent-Transfer-Encoding: base64\r\n\r\n${body}`,
+        `--b1\r\nContent-Type: ${m.attachment.mime}\r\nContent-Disposition: attachment; filename="${m.attachment.name}"\r\n` +
+            `Content-Transfer-Encoding: base64\r\n\r\n${Buffer.from(m.attachment.content).toString("base64")}`,
+    ];
+    return Buffer.from(`${[...headers, 'Content-Type: multipart/mixed; boundary="b1"'].join("\r\n")}\r\n\r\n${parts.join("\r\n")}\r\n--b1--\r\n`);
+};
+const failure = (message) => new CliError("provider_error", message, { reason: "mail.source-failed" });
+const labelsOf = (m) => [...new Set([...(m.labels ?? []), ...(m.flagged ? ["Starred"] : [])])].sort();
+const listingOf = (m, headers, folder) => ({
+    uid: m.uid,
+    messageId: m.messageId,
+    threadId: m.threadId,
+    receivedAt: new Date(m.receivedAt).toISOString(),
+    size: rawOf(m).length,
+    labels: labelsOf(m),
+    seen: m.seen ?? false,
+    flagged: m.flagged ?? false,
+    ...(headers ? { headers: headersOf(Buffer.from(rawOf(m)).toString().split("\r\n\r\n")[0] ?? "") } : {}),
+    folder,
+});
+/**
+ * An in-memory mail source with Gmail's shape: ids and threads that outlive a folder, labels and flags, UIDVALIDITY,
+ * a trash a move reaches, and All Mail under the account's language. The sync tests and the adapter contract run on it.
+ */
+export const fakeMailSource = (mailbox) => {
+    const all = () => mailbox.allMail ?? GMAIL_ALL_MAIL;
+    const trash = () => mailbox.trash ?? TRASH;
+    const inFolder = (folder) => {
+        if (![all(), trash(), "INBOX"].includes(folder))
+            throw failure(`Gmail has no such mailbox: ${folder}`);
+        return mailbox.messages.filter((m) => (folder === trash() ? m.folder === "trash" : m.folder !== "trash"));
+    };
+    const search = async (since, folder) => {
+        if (mailbox.searchFails)
+            throw failure(mailbox.searchFails);
+        const from = Date.UTC(since.getUTCFullYear(), since.getUTCMonth(), since.getUTCDate());
+        return {
+            validity: String(mailbox.validity ?? 12),
+            uids: inFolder(folder)
+                .filter((m) => Date.parse(m.receivedAt) >= from)
+                .map((m) => m.uid),
+        };
+    };
+    return {
+        search,
+        list: async (since, folder, options) => {
+            const { uids } = options?.searched ?? (await search(since, folder));
+            if (uids.length > 0)
+                mailbox.asked?.push(uids.join(","));
+            if (options?.headers && mailbox.headersFail)
+                throw failure("the header fetch was refused");
+            const wanted = new Set(uids);
+            return inFolder(folder)
+                .filter((m) => wanted.has(m.uid))
+                .map((m) => listingOf(m, options?.headers ?? false, folder));
+        },
+        find: async (messageIds, folder, options) => {
+            for (const id of messageIds)
+                mailbox.asked?.push(`msgid:${id}`);
+            const found = inFolder(folder).filter((m) => messageIds.includes(m.messageId));
+            if (found.length > 0)
+                mailbox.asked?.push(found.map((m) => m.uid).join(","));
+            return found.map((m) => listingOf(m, options?.headers ?? false, folder));
+        },
+        move: async (messageIds, from, to) => {
+            if (mailbox.moveFails)
+                throw failure("UID MOVE did not complete");
+            const here = inFolder(from).filter((m) => messageIds.includes(m.messageId));
+            if (here.length === 0)
+                return { moved: [], missing: [...messageIds] };
+            for (const m of here) {
+                if (to === trash()) {
+                    m.folder = "trash";
+                    m.labels = (m.labels ?? []).filter((label) => label !== "Inbox");
+                }
+                else {
+                    delete m.folder;
+                    if (to === "INBOX" && !(m.labels ?? []).includes("Inbox"))
+                        m.labels = ["Inbox", ...(m.labels ?? [])];
+                }
+            }
+            const moved = here.map((m) => m.messageId);
+            return { moved, missing: messageIds.filter((id) => !moved.includes(id)) };
+        },
+        folders: async () => ({ all: all(), trash: trash() }),
+        present: async (uids, folder) => inFolder(folder).flatMap((m) => (uids.includes(m.uid) ? [m.uid] : [])),
+        label: async (messageIds, folder, labels) => {
+            for (const m of inFolder(folder))
+                if (messageIds.includes(m.messageId))
+                    m.labels = [...new Set([...(m.labels ?? []), ...labels])];
+        },
+        fetchRaw: async (items) => items.map((item) => {
+            const m = mailbox.messages.find((each) => each.uid === item.uid);
+            if (m === undefined || mailbox.unreadable?.includes(item.uid))
+                return failure(`email ${item.uid} was not read`);
+            return rawOf(m);
+        }),
+    };
+};
+/**
+ * A snapshot source, as an mbox file is: every message since a date with no UIDs, one stamp that changes when the
+ * file does, and no search, find or folders. `archive.mails` and `archive.stamp` are read live.
+ */
+export const fakeArchiveSource = (archive) => ({
+    list: async (since, folder) => archive.mails
+        .filter((m) => Date.parse(m.receivedAt) >= since.getTime())
+        .map((m) => ({ ...listingOf(m, true, folder), uid: "" })),
+    stamp: async () => ({ ...archive.stamp }),
+    fetchRaw: async (items) => items.map((item) => {
+        const m = archive.mails.find((each) => each.messageId === item.messageId);
+        return m === undefined ? failure(`email ${item.messageId} was not found`) : rawOf(m);
+    }),
+});

package/dist/mail/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { CONTRACT_MAIL, type MailSourceFixture, type MailSyncFixture, mailSourceContract, mailSyncContract, } from "./contract.js";
+export { type FakeMail, type FakeMailbox, type FakePerson, fakeArchiveSource, fakeMailSource, rawOf } from "./fake.js";

package/dist/mail/testing/index.js

@@ -0,0 +1,2 @@
+export { CONTRACT_MAIL, mailSourceContract, mailSyncContract, } from "./contract.js";
+export { fakeArchiveSource, fakeMailSource, rawOf } from "./fake.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.471.0",
+  "version": "0.472.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -125,6 +125,14 @@
       "types": "./dist/calendar/testing/index.d.ts",
       "default": "./dist/calendar/testing/index.js"
     },
+    "./mail": {
+      "types": "./dist/mail/index.d.ts",
+      "default": "./dist/mail/index.js"
+    },
+    "./mail/testing": {
+      "types": "./dist/mail/testing/index.d.ts",
+      "default": "./dist/mail/testing/index.js"
+    },
     "./models": {
       "types": "./dist/models/index.d.ts",
       "default": "./dist/models/index.js"
@@ -200,6 +208,7 @@
     "dictionary-en": "4.0.0",
     "dictionary-es": "4.0.0",
     "dictionary-ru": "3.0.0",
+    "disposable-email-domains-js": "1.26.0",
     "echarts": "6.1.0",
     "fflate": "0.8.3",
     "iconv-lite": "0.7.3",
@@ -212,10 +221,12 @@
     "mdast-util-gfm": "3.1.0",
     "micromark-extension-gfm": "3.0.0",
     "ogg-opus-decoder": "1.7.5",
+    "postal-mime": "4.1.4",
     "psl": "1.15.0",
     "qrcode-generator": "2.0.4",
     "sherpa-onnx": "2.0.0",
     "string-width": "8.3.0",
+    "tldts": "7.4.19",
     "unpdf": "1.9.1",
     "valibot": "1.5.0",
     "word-extractor": "1.0.4",