@wirecat/cli-core 0.471.0 → 0.472.0

package/dist/mail/probe.js

@@ -0,0 +1,81 @@
+import { PRESET_NAMES, presetMatches } from "./presets.js";
+import { registrableOf, scoreGroup } from "./score.js";
+export const SUGGEST_RULE = "suggest is skip when a group has at least 20 emails, at least 80% of them list or bulk mail " +
+    "(List-Id, List-Unsubscribe or Precedence: bulk) and the owner never sent mail to its sender";
+const share = (part, whole) => Math.round((part / whole) * 100) / 100;
+const isSent = (item) => item.labels?.includes("Sent") || /(^|\/)sent\b/i.test(item.folder ?? "");
+/** A list's mail is one group whoever sends it; other mail is grouped by sender. */
+export const groupKey = (headers) => headers.listId === undefined ? `from:${headers.from}` : `list:${headers.listId}`;
+/** Groups mail by List-Id when it has one, else by sender address; largest groups first. */
+export const probeMail = (items, limit, ages = new Map()) => {
+    const sent = items.filter(isSent);
+    const recipients = new Set(sent.flatMap((item) => item.headers?.to ?? []));
+    const groups = new Map();
+    let withoutHeaders = 0;
+    for (const item of items) {
+        if (isSent(item))
+            continue;
+        const headers = item.headers;
+        if (headers === undefined || (headers.from === undefined && headers.listId === undefined)) {
+            withoutHeaders++;
+            continue;
+        }
+        const key = groupKey(headers);
+        const group = groups.get(key);
+        if (group)
+            group.push(item);
+        else
+            groups.set(key, [item]);
+    }
+    const all = [...groups.values()].map((group) => {
+        const senders = new Set(group.flatMap((item) => (item.headers?.from === undefined ? [] : [item.headers.from])));
+        const known = group.filter((item) => item.seen !== undefined);
+        const years = group.map((item) => new Date(item.receivedAt).getUTCFullYear());
+        const bulk = share(group.filter((item) => item.headers?.bulk).length, group.length);
+        const replied = [...senders].some((sender) => recipients.has(sender));
+        return {
+            from: [...senders][0] ?? null,
+            listId: group[0]?.headers?.listId ?? null,
+            emails: group.length,
+            bytes: group.reduce((sum, item) => sum + (item.size ?? 0), 0),
+            unread: known.length ? share(known.filter((item) => !item.seen).length, known.length) : null,
+            bulk,
+            firstYear: years.reduce((a, b) => Math.min(a, b)),
+            lastYear: years.reduce((a, b) => Math.max(a, b)),
+            replied,
+            suggest: group.length >= 20 && bulk >= 0.8 && !replied ? "skip" : null,
+            ...scoreGroup(group, { replied, bulk, ages }),
+        };
+    });
+    const presets = PRESET_NAMES.map((preset) => {
+        const hit = [...groups.values()].filter((group) => {
+            const replied = group.some((item) => item.headers?.from !== undefined && recipients.has(item.headers.from));
+            return presetMatches(preset, { ...group[0], replied });
+        });
+        return {
+            preset,
+            emails: hit.reduce((sum, group) => sum + group.length, 0),
+            groups: hit.length,
+            bytes: hit.reduce((sum, group) => sum + group.reduce((total, item) => total + (item.size ?? 0), 0), 0),
+        };
+    }).filter(({ emails }) => emails > 0);
+    all.sort((a, b) => b.emails - a.emails || b.bytes - a.bytes);
+    return {
+        emails: items.length,
+        bytes: items.reduce((sum, item) => sum + (item.size ?? 0), 0),
+        sent: sent.length,
+        withoutHeaders,
+        groups: all.length,
+        items: all.slice(0, limit),
+        presets,
+    };
+};
+/** The sender domains of the groups worth asking a registry about: not a big mailbox provider, never replied to. */
+export const domainsToAge = (groups, skip) => [
+    ...new Set(groups.flatMap((group) => {
+        if (group.replied || group.from === null)
+            return [];
+        const domain = registrableOf(group.from);
+        return skip.has(domain) ? [] : [domain];
+    })),
+];

package/dist/mail/resume.d.ts

@@ -0,0 +1,61 @@
+import type { MailRule } from "./rules.js";
+/** Inclusive UID stretches, sorted and apart: a mailbox read newest first in batches stays a few stretches. */
+export type Ranges = [number, number][];
+/** Where a folder's listing stopped, kept in the store beside the mail it describes, so a restored backup agrees. */
+export interface ResumePoint {
+    validity: string;
+    done: Ranges;
+    /** The rules the done mail was decided under; other rules decide it again. */
+    rules: string;
+    /**
+     * The widest recent listing of every message, the only kind that proves deletions and refreshes labels and
+     * flags: a later run whose window it covers may list only what is not done.
+     */
+    full: {
+        since: string;
+        at: string;
+    };
+    /** The widest window searched: its messages, and how many of them are done; a narrower run leaves it. */
+    window: {
+        since: string;
+        total: number;
+        done: number;
+    };
+    /**
+     * The widest window ever listed, kept across a rule change, a new UIDVALIDITY or --rescan, which start `window`
+     * over: a timer's 30 days must never stand in for a mailbox read since 2004.
+     */
+    widest?: {
+        since: string;
+        total: number;
+        at: string;
+    };
+    /** What the latest run listed, whatever its window. */
+    last?: {
+        since: string;
+        total: number;
+        done: number;
+        at: string;
+    };
+    updatedAt: string;
+}
+/** A whole listing at least this often, so deletions, labels and read state are never more than a day old. */
+export declare const FULL_PASS_MS = 86400000;
+export declare const resumeKey: (folder: string) => string;
+/** An mbox file has no UIDs: an unchanged file read to the end has nothing new. */
+export declare const MBOX_RESUME = "mail_resume:mbox";
+export interface FileStamp {
+    size: number;
+    mtimeMs: number;
+}
+export interface MboxPoint extends FileStamp {
+    /** Every email of the file was read: a run cut short by --limit reads it again. */
+    complete: boolean;
+    updatedAt: string;
+}
+export declare const rangesOf: (values: Iterable<number>) => Ranges;
+export declare const mergeRanges: (a: Ranges, b: Ranges) => Ranges;
+export declare const within: (ranges: Ranges, value: number) => boolean;
+/** Only what decides mail: a changed reason or date is the same rule. */
+export declare const rulesKey: (rules: readonly MailRule[]) => string;
+export declare const parsePoint: <T>(value: string | undefined) => T | undefined;

package/dist/mail/resume.js

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+/** A whole listing at least this often, so deletions, labels and read state are never more than a day old. */
+export const FULL_PASS_MS = 86_400_000;
+export const resumeKey = (folder) => `mail_resume:${folder}`;
+/** An mbox file has no UIDs: an unchanged file read to the end has nothing new. */
+export const MBOX_RESUME = "mail_resume:mbox";
+export const rangesOf = (values) => {
+    const sorted = [...new Set(values)].sort((a, b) => a - b);
+    const ranges = [];
+    for (const value of sorted) {
+        const last = ranges.at(-1);
+        if (last !== undefined && value === last[1] + 1)
+            last[1] = value;
+        else
+            ranges.push([value, value]);
+    }
+    return ranges;
+};
+export const mergeRanges = (a, b) => {
+    const merged = [];
+    for (const [from, to] of [...a, ...b].sort(([x], [y]) => x - y)) {
+        const last = merged.at(-1);
+        if (last !== undefined && from <= last[1] + 1)
+            last[1] = Math.max(last[1], to);
+        else
+            merged.push([from, to]);
+    }
+    return merged;
+};
+export const within = (ranges, value) => {
+    let low = 0;
+    let high = ranges.length - 1;
+    while (low <= high) {
+        const middle = (low + high) >> 1;
+        const [from, to] = ranges[middle];
+        if (value < from)
+            high = middle - 1;
+        else if (value > to)
+            low = middle + 1;
+        else
+            return true;
+    }
+    return false;
+};
+/** Only what decides mail: a changed reason or date is the same rule. */
+export const rulesKey = (rules) => createHash("sha256")
+    .update(JSON.stringify(rules
+    .map(({ match, action }) => JSON.stringify([action, match.from ?? null, match.domain ?? null, match.list_id ?? null]))
+    .sort()))
+    .digest("hex")
+    .slice(0, 16);
+export const parsePoint = (value) => {
+    if (value === undefined)
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/mail/rule-input.d.ts

@@ -0,0 +1,14 @@
+import type { MailAction, MailRule } from "./rules.js";
+export declare const STORE_ACTION: Record<MailAction, string>;
+export declare const ruleInput: (rule: MailRule, source?: string) => {
+    conditions: Record<string, string | number | boolean>;
+    actions: {
+        store: string;
+        tags?: string[] | undefined;
+        tags_skipped?: Record<string, string> | undefined;
+    };
+    protected: boolean;
+    source: string;
+    reason: string | null;
+    decidedAt: number;
+};

package/dist/mail/rule-input.js

@@ -0,0 +1,32 @@
+import { momentOf } from "../services/moment.js";
+import { conditionKeys } from "./rules.js";
+export const STORE_ACTION = { keep: "full", envelope: "envelope", skip: "skip" };
+const LOWER = ["from", "domain", "list_id", "subject"];
+const conditionsOf = (match) => Object.fromEntries(conditionKeys(match).map((key) => {
+    const value = match[key];
+    return [
+        key,
+        LOWER.includes(key) && typeof value === "string" ? value.toLowerCase() : value,
+    ];
+}));
+/** When the owner decided: a time without a zone is read in the computer's; an unreadable one is when it is saved. */
+const decidedAtOf = (value) => {
+    try {
+        return momentOf(value, "decided_at");
+    }
+    catch {
+        return Date.now();
+    }
+};
+export const ruleInput = (rule, source = rule.source ?? "owner") => ({
+    conditions: conditionsOf(rule.match),
+    actions: {
+        store: STORE_ACTION[rule.action],
+        ...(rule.tags?.length ? { tags: rule.tags } : {}),
+        ...(rule.tags_skipped && Object.keys(rule.tags_skipped).length ? { tags_skipped: rule.tags_skipped } : {}),
+    },
+    protected: rule.protected === true,
+    source,
+    reason: rule.reason ?? null,
+    decidedAt: decidedAtOf(rule.decided_at),
+});

package/dist/mail/rule-tags.d.ts

@@ -0,0 +1,40 @@
+import type { AccountKey, MessageStore } from "../store/index.js";
+import type { MailRule } from "./rules.js";
+type MessageRef = {
+    type: "message";
+    chatId: string;
+    messageId: string;
+};
+export interface TagOutcome {
+    /** A rule's tag the store refused as too close to an existing label, put on mail as that label instead. */
+    reused: {
+        tag: string;
+        as: string;
+    }[];
+    /** A rule's tag the store refused with nothing to reuse: the mail is stored, untagged. */
+    skipped: {
+        tag: string;
+        reason: string;
+        emails: number;
+    }[];
+}
+/**
+ * Tags mail for confirmed rules. A label the store refuses never fails the import: the label it points to is
+ * reused, and a tag with nothing to reuse is skipped and counted.
+ */
+export declare const ruleTagger: (store: MessageStore, key: AccountKey) => {
+    tag: (ref: MessageRef, tags: readonly string[]) => Promise<void>;
+    outcome: () => TagOutcome;
+};
+/** Writes what a run learned back into the rules, so the next run tags with the reused label and skips the rest. */
+export declare const settleRuleTags: (store: MessageStore, accountId: number, rules: readonly MailRule[], outcome: TagOutcome) => Promise<void>;
+/** Proposed tags matched to labels that already exist, before any is created: `reuse` exact, `similar` closest. */
+export declare const mapProposedTags: (store: MessageStore, rules: readonly MailRule[]) => Promise<{
+    rules: MailRule[];
+    mapping: {
+        tag: string;
+        as: string;
+        why: "reuse" | "similar";
+    }[];
+}>;
+export {};

package/dist/mail/rule-tags.js

@@ -0,0 +1,87 @@
+import { ruleInput } from "./rule-input.js";
+const reuseOf = (error) => {
+    const { details } = error;
+    return details?.reason === "tag-review.required" ? details.candidates?.[0]?.name : undefined;
+};
+/**
+ * Tags mail for confirmed rules. A label the store refuses never fails the import: the label it points to is
+ * reused, and a tag with nothing to reuse is skipped and counted.
+ */
+export const ruleTagger = (store, key) => {
+    const resolved = new Map();
+    const reasons = new Map();
+    const skippedEmails = new Map();
+    const add = async (ref, tag) => {
+        const known = resolved.get(tag);
+        if (known === null) {
+            skippedEmails.set(tag, (skippedEmails.get(tag) ?? 0) + 1);
+            return;
+        }
+        const name = known ?? tag;
+        try {
+            await store.tags.addTags(key, ref, [name]);
+            if (known === undefined)
+                resolved.set(tag, name);
+        }
+        catch (error) {
+            const reuse = known === undefined ? reuseOf(error) : undefined;
+            if (reuse !== undefined) {
+                resolved.set(tag, reuse);
+                return add(ref, tag);
+            }
+            resolved.set(tag, null);
+            reasons.set(tag, error.message ?? String(error));
+            skippedEmails.set(tag, (skippedEmails.get(tag) ?? 0) + 1);
+        }
+    };
+    return {
+        tag: async (ref, tags) => {
+            for (const tag of tags)
+                await add(ref, tag);
+        },
+        outcome: () => ({
+            reused: [...resolved].flatMap(([tag, as]) => (as !== null && as !== tag ? [{ tag, as }] : [])),
+            skipped: [...reasons].map(([tag, reason]) => ({ tag, reason, emails: skippedEmails.get(tag) ?? 0 })),
+        }),
+    };
+};
+/** Writes what a run learned back into the rules, so the next run tags with the reused label and skips the rest. */
+export const settleRuleTags = async (store, accountId, rules, outcome) => {
+    if (outcome.reused.length === 0 && outcome.skipped.length === 0)
+        return;
+    const as = new Map(outcome.reused.map(({ tag, as }) => [tag, as]));
+    const skipped = new Map(outcome.skipped.map(({ tag, reason }) => [tag, reason]));
+    for (const rule of rules) {
+        if (rule.id === undefined || !rule.tags?.some((tag) => as.has(tag) || skipped.has(tag)))
+            continue;
+        const tags = [...new Set(rule.tags.filter((tag) => !skipped.has(tag)).map((tag) => as.get(tag) ?? tag))];
+        const tagsSkipped = { ...rule.tags_skipped };
+        for (const tag of rule.tags) {
+            const why = skipped.get(tag);
+            if (why !== undefined)
+                tagsSkipped[tag] = why;
+        }
+        await store.mail.rules.upsert(accountId, ruleInput({ ...rule, tags, tags_skipped: tagsSkipped }), Date.now());
+    }
+};
+/** Proposed tags matched to labels that already exist, before any is created: `reuse` exact, `similar` closest. */
+export const mapProposedTags = async (store, rules) => {
+    const mapping = [];
+    for (const tag of new Set(rules.flatMap(({ tags }) => tags ?? []))) {
+        const plan = await store.knowledge.tagPreflight(tag).catch(() => undefined);
+        const as = plan?.disposition === "reuse"
+            ? plan.existing?.name
+            : plan?.disposition === "review"
+                ? plan.suggestions[0]?.entry.name
+                : undefined;
+        if (as !== undefined && as !== tag)
+            mapping.push({ tag, as, why: plan?.disposition === "reuse" ? "reuse" : "similar" });
+    }
+    if (mapping.length === 0)
+        return { rules: [...rules], mapping };
+    const as = new Map(mapping.map(({ tag, as }) => [tag, as]));
+    return {
+        rules: rules.map((rule) => rule.tags?.length ? { ...rule, tags: [...new Set(rule.tags.map((tag) => as.get(tag) ?? tag))] } : rule),
+        mapping,
+    };
+};

package/dist/mail/rules.d.ts

@@ -0,0 +1,83 @@
+import type { MailHeaders } from "./headers.js";
+import { type PresetName } from "./presets.js";
+/** All given conditions must hold; a rule with none matches nothing. */
+export interface MailRuleMatch {
+    from?: string;
+    /** A word the sender's address or display name contains, any case: Gmail's `from:smith`. */
+    from_contains?: string;
+    domain?: string;
+    /** One recipient address in To or Cc. */
+    to?: string;
+    list_id?: string;
+    /** Words that must all appear in the subject, any case. */
+    subject?: string;
+    older_than_days?: number;
+    larger_than_bytes?: number;
+    /** Sent as `multipart/mixed`, the way mail with attachments is. */
+    has_attachments?: boolean;
+    /** A Gmail label, by its plain name: `Promotions`, `Inbox`, or one the owner made. */
+    label?: string;
+    unread?: boolean;
+    /** List-Id, List-Unsubscribe or `Precedence: bulk`. */
+    bulk?: boolean;
+    /** The sender's score (memo mail inspect) is at least this. */
+    score_at_least?: number;
+    /** A built-in kind of mail, see presets.ts. */
+    preset?: PresetName;
+}
+export type MailAction = "skip" | "envelope" | "keep";
+export interface MailRule {
+    /** The store's id; absent until the rule is saved. */
+    id?: number;
+    match: MailRuleMatch;
+    /** skip: never read or stored · envelope: stored without its text, so it can be counted and cleaned later. */
+    action: MailAction;
+    /** memo tags put on every email the rule matches, with any action. */
+    tags?: string[];
+    /** Tags the store refused with no label to reuse, and why; the mail is stored untagged. */
+    tags_skipped?: Record<string, string>;
+    reason?: string;
+    /** Stored in full, and no cleanup may cut, archive or trash it, whatever other rules or presets say. */
+    protected?: boolean;
+    /** owner, preset:<name>, probe or gmail-filter. */
+    source?: string;
+    decided_at: string;
+}
+/** What is known of one email when a rule decides it: its headers at list time, and what the listing says. */
+export interface MailFacts {
+    headers?: MailHeaders;
+    receivedAt?: string;
+    size?: number;
+    labels?: string[];
+    seen?: boolean;
+    /** The sender group's score, when a rule asks for one. */
+    score?: number;
+    /** The owner wrote to this sender. */
+    replied?: boolean;
+}
+/** Unknown facts never match: a rule about size skips an email whose size the listing did not give. */
+export declare const matches: (match: MailRuleMatch, facts: MailFacts, now?: number) => boolean;
+/**
+ * The rule that decides an email. A protected rule wins over everything and keeps the mail whole; then keep wins
+ * over envelope, envelope over skip, so a keep for one sender overrides a skip of its domain and mail both record
+ * and drop rules match is recorded, since a record can be cleaned later. An explicit rule wins over a preset.
+ */
+export declare const decide: (rules: readonly MailRule[], facts: MailFacts | undefined) => MailRule | undefined;
+/** The tags of every rule that matches, whichever rule decides the action. */
+export declare const tagsOf: (rules: readonly MailRule[], facts: MailFacts) => string[];
+export declare const conditionKeys: (match: MailRuleMatch) => (keyof MailRuleMatch)[];
+/** A short, stable name of a match: `domain shop.example`, or `subject invoice, larger_than_bytes 1000`. */
+export declare const describeMatch: (match: MailRuleMatch) => string;
+/** Where the store keeps the emails one envelope rule recorded: a mailbox of its own, per rule. */
+export declare const envelopeBox: (match: MailRuleMatch) => {
+    externalId: string;
+    name: string;
+    kind: string;
+};
+export declare const ENVELOPE = "envelope";
+export declare const sameMatch: (a: MailRuleMatch, b: MailRuleMatch) => boolean;
+export declare const envelopeBoxOf: (externalId: string) => {
+    externalId: string;
+    name: string;
+    kind: string;
+};

package/dist/mail/rules.js

@@ -0,0 +1,108 @@
+import { presetMatches } from "./presets.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const domainOf = (address) => address.slice(address.lastIndexOf("@") + 1);
+/** A domain also matches its subdomains: bulk mail often comes from `mail.` or `news.` of the same domain. */
+const domainMatches = (wanted, sender) => {
+    if (sender === undefined)
+        return false;
+    const host = domainOf(sender);
+    const domain = wanted.toLowerCase();
+    return host === domain || host.endsWith(`.${domain}`);
+};
+const words = (text) => text.toLowerCase().split(/\s+/).filter(Boolean);
+/** Unknown facts never match: a rule about size skips an email whose size the listing did not give. */
+export const matches = (match, facts, now = Date.now()) => {
+    const conditions = Object.entries(match).filter(([, value]) => value !== undefined);
+    if (conditions.length === 0)
+        return false;
+    const { headers } = facts;
+    return conditions.every(([key, value]) => {
+        switch (key) {
+            case "from":
+                return headers?.from === String(value).toLowerCase();
+            case "from_contains": {
+                const word = String(value).toLowerCase();
+                return [headers?.from, headers?.fromName?.toLowerCase()].some((part) => part?.includes(word) ?? false);
+            }
+            case "domain":
+                return domainMatches(String(value), headers?.from);
+            case "to":
+                return headers?.to.includes(String(value).toLowerCase()) ?? false;
+            case "list_id":
+                return headers?.listId === String(value).toLowerCase();
+            case "subject": {
+                const subject = headers?.subject?.toLowerCase();
+                return subject !== undefined && words(String(value)).every((word) => subject.includes(word));
+            }
+            case "older_than_days":
+                return facts.receivedAt !== undefined && now - Date.parse(facts.receivedAt) > Number(value) * DAY_MS;
+            case "larger_than_bytes":
+                return facts.size !== undefined && facts.size > Number(value);
+            case "has_attachments":
+                return headers !== undefined && (headers.attachments === true) === value;
+            case "label":
+                return facts.labels?.some((label) => label.toLowerCase() === String(value).toLowerCase()) ?? false;
+            case "unread":
+                return facts.seen !== undefined && !facts.seen === value;
+            case "bulk":
+                return headers !== undefined && headers.bulk === value;
+            case "score_at_least":
+                return facts.score !== undefined && facts.score >= Number(value);
+            case "preset":
+                return presetMatches(value, facts);
+            default:
+                return false;
+        }
+    });
+};
+const RANK = { keep: 0, envelope: 1, skip: 2 };
+const strength = (rule) => (rule.protected ? 0 : 10) + RANK[rule.action] + (rule.source?.startsWith("preset:") ? 5 : 0);
+/**
+ * The rule that decides an email. A protected rule wins over everything and keeps the mail whole; then keep wins
+ * over envelope, envelope over skip, so a keep for one sender overrides a skip of its domain and mail both record
+ * and drop rules match is recorded, since a record can be cleaned later. An explicit rule wins over a preset.
+ */
+export const decide = (rules, facts) => {
+    if (facts?.headers === undefined)
+        return undefined;
+    const now = Date.now();
+    const hit = rules.filter((rule) => matches(rule.match, facts, now)).sort((a, b) => strength(a) - strength(b))[0];
+    return hit?.protected ? { ...hit, action: "keep" } : hit;
+};
+/** The tags of every rule that matches, whichever rule decides the action. */
+export const tagsOf = (rules, facts) => {
+    if (facts.headers === undefined)
+        return [];
+    const now = Date.now();
+    return [...new Set(rules.flatMap((rule) => (rule.tags?.length && matches(rule.match, facts, now) ? rule.tags : [])))];
+};
+/** The only conditions an envelope mailbox can be named by: one sender, domain or list. */
+const SINGLE = ["from", "domain", "list_id"];
+export const conditionKeys = (match) => Object.keys(match).filter((key) => match[key] !== undefined).sort();
+/** A short, stable name of a match: `domain shop.example`, or `subject invoice, larger_than_bytes 1000`. */
+export const describeMatch = (match) => conditionKeys(match)
+    .map((key) => `${key === "list_id" ? "list-id" : key.replace(/_/g, "-")} ${String(match[key])}`)
+    .join(", ");
+/** Where the store keeps the emails one envelope rule recorded: a mailbox of its own, per rule. */
+export const envelopeBox = (match) => {
+    const keys = conditionKeys(match);
+    const single = keys.length === 1 && SINGLE.includes(keys[0]);
+    const [kind, value] = single
+        ? [keys[0] === "list_id" ? "list-id" : String(keys[0]), String(match[keys[0]])]
+        : ["rule", describeMatch(match)];
+    return {
+        externalId: `memo:envelope:${kind}:${value.toLowerCase()}`,
+        name: `envelope: ${kind} ${value}`,
+        kind: ENVELOPE,
+    };
+};
+export const ENVELOPE = "envelope";
+const normalized = (match) => JSON.stringify(conditionKeys(match).map((key) => {
+    const value = match[key];
+    return [key, typeof value === "string" ? value.toLowerCase() : value];
+}));
+export const sameMatch = (a, b) => normalized(a) === normalized(b);
+export const envelopeBoxOf = (externalId) => {
+    const [, , kind, ...value] = externalId.split(":");
+    return { externalId, name: `envelope: ${kind} ${value.join(":")}`, kind: ENVELOPE };
+};

package/dist/mail/score.d.ts

@@ -0,0 +1,67 @@
+import type { Listed } from "./source.js";
+/**
+ * How much each sign of spam, a scam or a robot adds to a sender's score. Gmail filters spam before it reaches
+ * All Mail, so these mostly find what got through: spoofed senders, scams and robots no rule covers yet.
+ */
+export declare const WEIGHTS: {
+    readonly spam_folder: 4;
+    readonly dmarc_fail: 3;
+    readonly brand_spoof: 3;
+    readonly young_domain: 5;
+    readonly reply_to_elsewhere: 1;
+    readonly never_opened: 2;
+    readonly dkim_not_passed: 2;
+    readonly disposable_domain: 2;
+    readonly bulk_never_replied: 1;
+    readonly replied: -5;
+};
+export type Signal = keyof typeof WEIGHTS;
+/**
+ * The signs of a forged or fraudulent sender, as opposed to how the owner treats ordinary bulk mail. A failed DMARC
+ * check is one only beside another: alone it marks real senders with a broken setup or a forwarding path.
+ */
+export declare const FRAUD_SIGNALS: readonly Signal[];
+export declare const SCORE_RULE: string;
+/**
+ * DMARC failures before this date are not counted: senders then often published a policy their own mail did not yet
+ * meet.
+ */
+export declare const DMARC_SINCE = "2022-01-01T00:00:00.000Z";
+/** A domain registered too recently to trust: under this many days old when the mail arrived. */
+export declare const YOUNG_DAYS = 180;
+/** What the registry said about a domain; `created` is ISO 8601, `unsupported` when its registry has no RDAP. */
+export interface DomainAge {
+    created?: string;
+    unsupported?: boolean;
+    checkedAt: string;
+}
+/** The part of a host a person registers: `mail.news.example.co.uk` is `example.co.uk`. */
+export declare const registrableOf: (address: string) => string;
+/**
+ * The big mailbox providers. Their domains are years old and say nothing about the sender, so they are never
+ * looked up; a brand display name sent from one of them is the classic scam.
+ */
+export declare const FREE_MAIL: Set<string>;
+/**
+ * The brand a display name claims while the address belongs to someone else, if any. "Google via LinkedIn" from
+ * LinkedIn's own domain is LinkedIn passing a page on; "PayPal via Desk" from anywhere else is still judged whole.
+ */
+export declare const spoofedBrand: (name: string | undefined, address: string | undefined) => string | undefined;
+/**
+ * Under YOUNG_DAYS old at `at`; false when the age is not known, and when the registration came after `at`: the
+ * domain lapsed and someone registered it again later, which says nothing about the mail that came before.
+ */
+export declare const youngAt: (age: DomainAge | undefined, at: string) => boolean;
+export interface Scored {
+    score: number;
+    signals: Signal[];
+}
+/**
+ * A sender group's score from the facts its emails carry. A sign counts when it holds for at least half the group's
+ * emails, so one odd email does not mark a sender; a spoofed brand counts on any one.
+ */
+export declare const scoreGroup: (items: Listed[], context: {
+    replied: boolean;
+    bulk: number;
+    ages: ReadonlyMap<string, DomainAge>;
+}) => Scored;