@wirecat/cli-core 0.593.0 → 0.594.0

package/dist/crm/writer.d.ts

@@ -0,0 +1,76 @@
+import type { CrmItem } from "../domain/crm.js";
+import type { DealKind, DealRole } from "../domain/deals.js";
+import type { Level, PermissionKey } from "../sends/permissions.js";
+export declare const CRM_VERBS: readonly ["create", "update", "move", "close", "remove"];
+export type CrmVerb = (typeof CRM_VERBS)[number];
+export interface CrmWriteCapabilities {
+    /** The kinds the CRM takes writes for. */
+    kinds: readonly DealKind[];
+    verbs: readonly CrmVerb[];
+    /**
+     * The CRM answers a repeat of an `operationId` from its record instead of doing the write again (Bitrix24 REST
+     * 3.0's `Idempotency-Key`). Only then may the owner repeat a write whose answer was lost with the same id.
+     */
+    idempotent: boolean;
+}
+/**
+ * A deal's or lead's fields in `CrmItem`'s names, each the CRM's own id; `null` clears one. `custom` holds the CRM's
+ * own fields by their code. A custom code that is one of the named fields under another name (a stage, a pipeline, an
+ * owner or a status) is refused by the adapter: through it a write would get round the keys those fields check.
+ */
+export interface CrmFields {
+    title?: string;
+    pipeline?: string;
+    stage?: string;
+    /** A decimal string in `currency`; both or neither. */
+    amount?: string | null;
+    currency?: string | null;
+    /** `YYYY-MM-DD`. */
+    closeDate?: string | null;
+    organization?: string | null;
+    /** Replaces the whole list. */
+    people?: {
+        externalId: string;
+        role: DealRole;
+    }[];
+    /** The CRM user it is assigned to: a user's id, never a contact's. */
+    owner?: string | null;
+    custom?: Record<string, string | null>;
+}
+export type CrmDraft = CrmFields & {
+    title: string;
+};
+export interface CrmWriteOptions {
+    /** Journaled before the call; an idempotent CRM gets it as its idempotency key. */
+    operationId: string;
+}
+/**
+ * Writes to one CRM account. Each answers the whole item as the CRM holds it after the write, every field and not
+ * only the changed ones: the store replaces its copy with it. None of them retries: a write whose answer was lost
+ * throws `outcome_unknown`.
+ */
+export interface CrmWriter {
+    readonly provider: string;
+    readonly capabilities: CrmWriteCapabilities;
+    create(kind: DealKind, draft: CrmDraft, options: CrmWriteOptions): Promise<CrmItem>;
+    update(kind: DealKind, externalId: string, patch: CrmFields, options: CrmWriteOptions): Promise<CrmItem>;
+    /** To `stage`, a stage of the item's own pipeline. */
+    move(kind: DealKind, externalId: string, stage: string, options: CrmWriteOptions): Promise<CrmItem>;
+    /**
+     * Won or lost, the CRM's own way: Pipedrive sets a status, Kommo and Bitrix24 move it to the pipeline's closing
+     * stage, HubSpot to a closed stage.
+     */
+    close(kind: DealKind, externalId: string, outcome: "won" | "lost", options: CrmWriteOptions & {
+        reason?: string;
+    }): Promise<CrmItem>;
+    remove(kind: DealKind, externalId: string, options: CrmWriteOptions): Promise<void>;
+}
+/** Giving a record to a CRM user other than the one the sign-in acts as. */
+export declare const CRM_ASSIGN_OTHERS_KEY: PermissionKey;
+/** The keys the CRM writes check beyond their command paths, for a CLI's `commandPermissions({ extra })`. */
+export declare const CRM_WRITE_KEYS: readonly PermissionKey[];
+/**
+ * Built in, and only ever tightening (WC-PERM-7): an ordinary change goes ahead, a deletion asks, and a record is not
+ * given to somebody else until the owner allows it.
+ */
+export declare const CRM_WRITE_DEFAULTS: Readonly<Record<PermissionKey, Level>>;

package/dist/crm/writer.js

@@ -0,0 +1,14 @@
+export const CRM_VERBS = ["create", "update", "move", "close", "remove"];
+/** Giving a record to a CRM user other than the one the sign-in acts as. */
+export const CRM_ASSIGN_OTHERS_KEY = "crm.assign-others";
+/** The keys the CRM writes check beyond their command paths, for a CLI's `commandPermissions({ extra })`. */
+export const CRM_WRITE_KEYS = [CRM_ASSIGN_OTHERS_KEY];
+/**
+ * Built in, and only ever tightening (WC-PERM-7): an ordinary change goes ahead, a deletion asks, and a record is not
+ * given to somebody else until the owner allows it.
+ */
+export const CRM_WRITE_DEFAULTS = {
+    "deals.delete": "ask",
+    "leads.delete": "ask",
+    [CRM_ASSIGN_OTHERS_KEY]: "deny",
+};

package/dist/crm/writes.d.ts

@@ -0,0 +1,68 @@
+import type { DealKind } from "../domain/deals.js";
+import type { AppIdentity } from "../ports/app.js";
+import type { Warn } from "../runs/events.js";
+import { type Asker, type GuardSettings } from "../sends/guard.js";
+import type { Deal } from "../store/sqlite/deals.js";
+import type { MessageStore } from "../store/store.js";
+import type { AccountKey } from "../store/types.js";
+import type { CrmSource } from "./source.js";
+import { type CrmWriter } from "./writer.js";
+/** What a CLI hands the CRM writes for one profile. */
+export interface CrmWrites {
+    writer: CrmWriter;
+    app: AppIdentity;
+    /** The profile's levels, read on every write so a config change applies at once. */
+    settings: () => GuardSettings;
+    /** The CRM user the sign-in acts as. An owner other than it checks `crm.assign-others`; left out, every owner does. */
+    self?: string;
+    env?: NodeJS.ProcessEnv;
+    warn?: Warn;
+}
+export interface CrmWriteContext {
+    store: MessageStore;
+    account: AccountKey;
+    writes: CrmWrites;
+    /** A terminal's question, or an agent's go-ahead. */
+    ask: Asker;
+    /** Reads the kind's pipelines again when the CRM answers an item in a stage the store does not hold yet. */
+    source?: () => CrmSource;
+    /** How the caller spells the operation id in a hint: `--operation-id`, or `operation_id` over MCP. */
+    names?: {
+        id: string;
+    };
+}
+/** The fields as typed: a pipeline and a stage by reference or name, money as a decimal. */
+export interface CrmFieldsInput {
+    title?: string;
+    pipeline?: string;
+    stage?: string;
+    amount?: string;
+    currency?: string;
+    closeDate?: string;
+    owner?: string;
+    custom?: Record<string, string | null>;
+}
+export interface CrmWritten {
+    operationId: string;
+    item: Deal;
+}
+export declare const createCrmItem: (context: CrmWriteContext, kind: DealKind, input: CrmFieldsInput, options?: {
+    operationId?: string;
+}) => Promise<CrmWritten>;
+export declare const updateCrmItem: (context: CrmWriteContext, kind: DealKind, reference: string, input: CrmFieldsInput, options?: {
+    operationId?: string;
+}) => Promise<CrmWritten>;
+export declare const moveCrmItem: (context: CrmWriteContext, kind: DealKind, reference: string, stageName: string, options?: {
+    operationId?: string;
+}) => Promise<CrmWritten>;
+export declare const closeCrmItem: (context: CrmWriteContext, kind: DealKind, reference: string, outcome: "won" | "lost", options?: {
+    reason?: string;
+    operationId?: string;
+}) => Promise<CrmWritten>;
+export declare const removeCrmItem: (context: CrmWriteContext, kind: DealKind, reference: string, options?: {
+    operationId?: string;
+}) => Promise<{
+    operationId: string;
+    ref: string;
+    removed: number;
+}>;

package/dist/crm/writes.js

@@ -0,0 +1,245 @@
+import { CliError, isCliError } from "@wirecat/cli-base";
+import { guardFor } from "../sends/guard.js";
+import { guardedWrite } from "../sends/guarded.js";
+import { keyedGuard } from "../sends/keyed-guard.js";
+import { DEFAULT_PERMISSIONS, levelFor } from "../sends/permissions.js";
+import { newOperationId } from "../sends/send-id.js";
+import { CRM_ASSIGN_OTHERS_KEY, CRM_WRITE_DEFAULTS, } from "./writer.js";
+const PLURAL = { deal: "deals", lead: "leads" };
+const COMMAND = {
+    create: "create",
+    update: "update",
+    move: "move",
+    close: "close",
+    remove: "delete",
+};
+const keyOf = (kind, verb) => `${PLURAL[kind]}.${COMMAND[verb]}`;
+/** Bitrix24 REST 3.0's `Idempotency-Key` takes 1 to 255 printable ASCII characters; so does every id here. */
+const OPERATION_ID = /^[\x21-\x7e]{1,255}$/u;
+const DECIMAL = /^\d{1,16}(\.\d{1,6})?$/u;
+const CURRENCY = /^[A-Z]{3}$/u;
+const DAY = /^\d{4}-\d{2}-\d{2}$/u;
+const FIELD_CODE = /^[A-Za-z][\w.-]{0,99}$/u;
+const invalid = (message, param) => new CliError("validation_error", message, { reason: "deal.field", ...(param ? { param } : {}) });
+const supported = (writer, kind, verb) => {
+    const { kinds, verbs } = writer.capabilities;
+    if (!kinds.includes(kind) || !verbs.includes(verb))
+        throw new CliError("validation_error", `this CRM does not take a ${COMMAND[verb]} of ${PLURAL[kind]}`, {
+            reason: "crm.write-unsupported",
+            sent: false,
+        });
+};
+const operationOf = (context, given) => {
+    if (given === undefined)
+        return newOperationId();
+    const name = context.names?.id ?? "--operation-id";
+    if (!context.writes.writer.capabilities.idempotent)
+        throw new CliError("validation_error", `this CRM does not recognise a repeated write, so ${name} would do it a second time; sync and look before ` +
+            "writing again", { reason: "crm.write-unsupported", param: name, sent: false });
+    if (!OPERATION_ID.test(given))
+        throw new CliError("validation_error", `${name} takes 1 to 255 printable characters with no spaces`, {
+            param: name,
+        });
+    return given;
+};
+/** A copy of this profile's account: another account's, or the owner's own, is not written here. */
+const copyOf = async (context, kind, reference) => {
+    if (!reference.startsWith(`${kind}:`))
+        throw new CliError("validation_error", `name the ${kind} as ${kind}:<id>, as a list shows it`, {
+            reason: "ref.malformed",
+        });
+    const found = await context.store.deals.get(reference);
+    const { provider, account } = context.account;
+    if (found.account?.provider !== provider || found.account.account !== account || found.externalId === null)
+        throw new CliError("not_found", `${reference} is not a copy from this profile's CRM account`);
+    return found;
+};
+const pipelineOf = async (context, kind, reference) => {
+    if (reference !== undefined) {
+        const found = await context.store.deals.pipeline(reference, { kind, account: context.account });
+        if (found.externalId === null)
+            throw new CliError("not_found", `${reference} is not a pipeline of this CRM account`);
+        return found;
+    }
+    const all = await context.store.deals.pipelines({ kind, account: context.account });
+    if (all.length === 1)
+        return all[0];
+    throw new CliError("validation_error", all.length === 0
+        ? `no ${kind} pipeline of this CRM is stored; run sync first`
+        : `this CRM has ${all.length} ${kind} pipelines; name one with --pipeline: ${all.map(({ name }) => name).join(", ")}`, { reason: "crm.pipeline-required", param: "--pipeline" });
+};
+/** A stage of `pipeline`, by the CRM's id or by a name only one of its stages has, in any letter case. */
+const stageOf = (pipeline, given) => {
+    const byId = pipeline.stages.find((stage) => stage.externalId === given);
+    if (byId)
+        return byId;
+    const folded = given.trim().toLocaleLowerCase();
+    const named = pipeline.stages.filter((stage) => stage.name.toLocaleLowerCase() === folded);
+    if (named.length === 1)
+        return named[0];
+    throw new CliError("validation_error", `${pipeline.name} has ${named.length ? "more than one" : "no"} stage ${given}: ` +
+        pipeline.stages.map(({ name }) => name).join(", "), { reason: "deal.stage", param: "--stage" });
+};
+const validDay = (text) => {
+    const date = new Date(`${text}T00:00:00Z`);
+    return DAY.test(text) && !Number.isNaN(date.getTime()) && date.toISOString().startsWith(text);
+};
+/** Typed fields into the port's, resolving the stage in `pipeline`; `currency` is the copy's when a patch keeps it. */
+const fieldsOf = (input, pipeline, currency) => {
+    const fields = {};
+    if (input.title !== undefined) {
+        if (!input.title.trim())
+            throw invalid("a title is never empty", "--title");
+        fields.title = input.title.trim();
+    }
+    if (pipeline && input.pipeline !== undefined)
+        fields.pipeline = pipeline.externalId;
+    const stage = pipeline && input.stage !== undefined ? stageOf(pipeline, input.stage) : undefined;
+    if (stage)
+        fields.stage = stage.externalId;
+    if (input.amount !== undefined || input.currency !== undefined) {
+        const code = (input.currency ?? currency ?? "").toUpperCase();
+        if (input.amount === undefined)
+            throw invalid("--currency goes with --amount", "--amount");
+        if (!DECIMAL.test(input.amount))
+            throw invalid("--amount is a decimal such as 1500.50", "--amount");
+        if (!CURRENCY.test(code))
+            throw invalid("--amount needs --currency, an ISO 4217 code such as EUR", "--currency");
+        fields.amount = input.amount;
+        fields.currency = code;
+    }
+    if (input.closeDate !== undefined) {
+        if (!validDay(input.closeDate))
+            throw invalid("--close-date is a day, YYYY-MM-DD", "--close-date");
+        fields.closeDate = input.closeDate;
+    }
+    if (input.owner !== undefined) {
+        if (!input.owner.trim())
+            throw invalid("--owner is the CRM user's id", "--owner");
+        fields.owner = input.owner.trim();
+    }
+    if (input.custom !== undefined && Object.keys(input.custom).length) {
+        for (const code of Object.keys(input.custom))
+            if (!FIELD_CODE.test(code))
+                throw invalid(`${code} is not a field code`, "--field");
+        fields.custom = input.custom;
+    }
+    return { fields, stage };
+};
+/** Every key the write checks: its own, and each action its fields also take (WC-PERM-22). */
+const keysOf = (context, kind, verb, { stage, owner }) => {
+    const extra = [];
+    if (stage && verb !== "move")
+        extra.push(keyOf(kind, "move"));
+    if (stage && stage.outcome !== "open")
+        extra.push(keyOf(kind, "close"));
+    if (owner != null && owner !== context.writes.self)
+        extra.push(CRM_ASSIGN_OTHERS_KEY);
+    return { key: keyOf(kind, verb), extra };
+};
+/** The profile's guard over the write's own key and the keys its fields imply (`keyedGuard`). */
+const guardOf = (context, extra) => {
+    const settings = context.writes.settings();
+    const defaults = { ...DEFAULT_PERMISSIONS, ...CRM_WRITE_DEFAULTS, ...settings.permissionDefaults };
+    return keyedGuard((ask) => guardFor(context.writes.app, { ...settings, permissionDefaults: defaults }, context.writes.warn ?? (() => { }), context.writes.env, ask), context.ask, (key) => levelFor(settings.permissions, key, defaults).level, extra);
+};
+/** Sends the write once, never again: a lost answer is `outcome_unknown`, with what the owner may do about it. */
+const written = async (context, { key, extra }, operationId, act) => {
+    try {
+        return await guardedWrite(guardOf(context, extra), { chatId: null, kind: "edit", key, operationId }, act);
+    }
+    catch (error) {
+        if (!isCliError(error) || error.code !== "outcome_unknown")
+            throw error;
+        const name = context.names?.id ?? "--operation-id";
+        throw new CliError("outcome_unknown", context.writes.writer.capabilities.idempotent
+            ? `${error.message} — repeat it with ${name} ${operationId}: the CRM answers a repeat from its record ` +
+                "instead of doing it again"
+            : `${error.message} — sync and look at the CRM before writing again: this CRM would do it a second time`, { ...error.details, operation_id: operationId });
+    }
+};
+/**
+ * The CRM's answer into the store, as a sync would save it. A failure here names the item: the CRM has made the
+ * change, and a repeat would make it again.
+ */
+const kept = async (context, kind, item, operationId) => {
+    const fail = (why, details = {}) => new CliError("invalid_response", `the CRM wrote ${kind} ${item.externalId}, but the local store did not keep it (${why}); sync to store it — ` +
+        "do not write it again", { ...details, operation_id: operationId, external_id: item.externalId, sent: true });
+    try {
+        let saved = await context.store.crm.saveItems(context.account, kind, [item]);
+        if (saved.skipped[0]?.reason === "crm.stage-unknown" && context.source) {
+            await context.store.crm.savePipelines(context.account, kind, await context.source().pipelines(kind));
+            saved = await context.store.crm.saveItems(context.account, kind, [item]);
+        }
+        const [skipped] = saved.skipped;
+        if (skipped)
+            throw fail(skipped.message, { reason: skipped.reason });
+        const reference = await context.store.crm.refOf(context.account, kind, item.externalId);
+        if (reference === null)
+            throw fail("it is not found after the save");
+        return await context.store.deals.get(reference);
+    }
+    catch (error) {
+        if (isCliError(error) && error.code === "invalid_response" && error.details.sent === true)
+            throw error;
+        throw fail(error instanceof Error ? error.message : String(error), isCliError(error) ? error.details : {});
+    }
+};
+export const createCrmItem = async (context, kind, input, options = {}) => {
+    const { writer } = context.writes;
+    supported(writer, kind, "create");
+    if (input.title === undefined)
+        throw invalid(`a new ${kind} needs --title`, "--title");
+    const pipeline = await pipelineOf(context, kind, input.pipeline);
+    const { fields, stage } = fieldsOf({ ...input, pipeline: pipeline.ref }, pipeline, null);
+    const operationId = operationOf(context, options.operationId);
+    const item = await written(context, keysOf(context, kind, "create", { stage, owner: fields.owner }), operationId, () => writer.create(kind, fields, { operationId }));
+    return { operationId, item: await kept(context, kind, item, operationId) };
+};
+export const updateCrmItem = async (context, kind, reference, input, options = {}) => {
+    const { writer } = context.writes;
+    supported(writer, kind, "update");
+    const copy = await copyOf(context, kind, reference);
+    if (input.pipeline !== undefined && input.stage === undefined)
+        throw invalid("a new --pipeline needs the --stage it goes to there", "--stage");
+    const pipeline = input.stage === undefined
+        ? undefined
+        : await pipelineOf(context, kind, input.pipeline === undefined ? copy.pipeline : input.pipeline);
+    const { fields, stage } = fieldsOf(input, pipeline, copy.currency);
+    if (Object.keys(fields).length === 0)
+        throw invalid("nothing to change: name a field");
+    const operationId = operationOf(context, options.operationId);
+    const item = await written(context, keysOf(context, kind, "update", { stage, owner: fields.owner }), operationId, () => writer.update(kind, copy.externalId, fields, { operationId }));
+    return { operationId, item: await kept(context, kind, item, operationId) };
+};
+export const moveCrmItem = async (context, kind, reference, stageName, options = {}) => {
+    const { writer } = context.writes;
+    supported(writer, kind, "move");
+    const copy = await copyOf(context, kind, reference);
+    const stage = stageOf(await pipelineOf(context, kind, copy.pipeline), stageName);
+    const operationId = operationOf(context, options.operationId);
+    const item = await written(context, keysOf(context, kind, "move", { stage }), operationId, () => writer.move(kind, copy.externalId, stage.externalId, { operationId }));
+    return { operationId, item: await kept(context, kind, item, operationId) };
+};
+export const closeCrmItem = async (context, kind, reference, outcome, options = {}) => {
+    const { writer } = context.writes;
+    supported(writer, kind, "close");
+    if (outcome !== "won" && outcome !== "lost")
+        throw invalid("a close is won or lost");
+    const copy = await copyOf(context, kind, reference);
+    const reason = options.reason?.trim();
+    if (reason !== undefined && (reason === "" || reason.length > 2000))
+        throw invalid("--reason is 1 to 2000 characters", "--reason");
+    const operationId = operationOf(context, options.operationId);
+    const item = await written(context, keysOf(context, kind, "close", {}), operationId, () => writer.close(kind, copy.externalId, outcome, { operationId, ...(reason ? { reason } : {}) }));
+    return { operationId, item: await kept(context, kind, item, operationId) };
+};
+export const removeCrmItem = async (context, kind, reference, options = {}) => {
+    const { writer } = context.writes;
+    supported(writer, kind, "remove");
+    const copy = await copyOf(context, kind, reference);
+    const operationId = operationOf(context, options.operationId);
+    await written(context, keysOf(context, kind, "remove", {}), operationId, () => writer.remove(kind, copy.externalId, { operationId }));
+    const removed = await context.store.crm.remove(context.account, kind, [copy.externalId]);
+    return { operationId, ref: copy.ref, removed };
+};

package/dist/domain/crm.d.ts

@@ -12,10 +12,7 @@ export interface CrmStage {
     outcome: StageOutcome;
 }
 export interface CrmPipeline {
-    /**
-     * Unique among the account's pipelines of its kind. Until the store's key is widened, one with the id of a stored
-     * pipeline of the other kind is skipped and named.
-     */
+    /** Unique among the account's pipelines of its kind; a deal pipeline and a lead pipeline may share one. */
     externalId: string;
     name: string;
     stages: CrmStage[];
@@ -39,6 +36,8 @@ export interface CrmItem {
     closeDate?: string | null;
     /** `YYYY-MM-DD`: when it was won or lost. */
     closedDate?: string | null;
+    /** Why it was won or lost, as the CRM keeps it. */
+    closedReason?: string | null;
     /** A company's id. */
     organization?: string | null;
     /** Contacts on it, by their id, and the part each plays. */

package/dist/errors/reasons.js

@@ -213,8 +213,9 @@ const OTHERS = [
     validation("pipeline.field", "a pipeline needs a name and at least one stage, each named once"),
     ["pipeline.not-found", "not_found", "no stored pipeline has that name or reference"],
     validation("crm.stage-unknown", "a CRM item stands in a stage the store does not hold; it was not kept"),
-    validation("crm.pipeline-clash", "a CRM pipeline has the id of a stored pipeline of the other kind; it was not kept"),
     validation("crm.item-invalid", "a CRM item has a field the store refuses, such as a currency it does not keep"),
+    validation("crm.pipeline-required", "the CRM has more than one pipeline of the kind; the write names one"),
+    validation("crm.write-unsupported", "the CRM does not take this write, or does not recognise a repeated one"),
     validation("crm.unlisted-held", "a list of every id would mark most of a kind deleted; nothing was, until --rescan"),
     validation("order.duplicate", "the shop's order with this number is already stored; change its status instead"),
     validation("order.proposed", "the shop's order with this number already waits for the owner in a findings batch"),

package/dist/mail/cli/review.js

@@ -87,10 +87,11 @@ const waitingHours = (value) => value === true ? AGENDA_DEFAULTS.waiting / 3_600
 const quoted = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
 /** A file name for the mailbox's points: they describe the mailbox, whichever profile reads it. */
 const pointsName = (mailbox) => encodeURIComponent(mailbox.account);
-const markText = (marks, excerptOnly = false) => {
+const markText = (marks, excerptOnly = false, partial = false) => {
     const said = [
         marks?.bulk || excerptOnly ? "bulk" : "",
         excerptOnly ? "excerpt only" : "",
+        partial ? "partial: not fully downloaded" : "",
         marks?.listId ? `list ${marks.listId}` : "",
         marks?.ruleId ? `rule ${marks.ruleId}` : "",
     ];
@@ -144,6 +145,7 @@ const reviewAnswer = (found, mailbox, fresh, step) => {
                 ...messageItem(message, mailbox).email,
                 bulk: (message.marks?.bulk ?? false) || message.excerptOnly === true,
                 ...(message.excerptOnly ? { excerpt_only: true } : {}),
+                ...(message.partialExcerpt ? { partial: true } : {}),
                 list_id: message.marks?.listId ?? null,
                 rule_id: message.marks?.ruleId ?? null,
                 ...(message.marks
@@ -178,9 +180,14 @@ const holderReview = async (command, mail, holder, query) => {
     // An agent reads this: earlier mail and signatures stay out of its text; the fingerprint is over the stored body.
     const emails = [
         ...read.emails.map((email) => ({ ...email, text: mailOwnText(email.text) })),
-        ...read.excerpts.map(({ email, excerpt }) => {
+        ...read.excerpts.map(({ email, excerpt, partial }) => {
             const subject = email.email?.subject;
-            return { ...email, text: subject ? `${subject}\n\n${excerpt}` : excerpt, excerptOnly: true };
+            return {
+                ...email,
+                text: subject ? `${subject}\n\n${excerpt}` : excerpt,
+                excerptOnly: true,
+                ...(partial ? { partialExcerpt: true } : {}),
+            };
         }),
     ];
     const chats = new Map();
@@ -237,7 +244,7 @@ const holderReview = async (command, mail, holder, query) => {
             ? `${holder}: past ${read.mark.throughId}${emails.length ? `; findings key ${read.findingsKey}` : ""}; acknowledge with --cursor ${read.cursor}${read.more ? "; more after these" : ""}`
             : `${holder} has no mark yet: it starts from now — acknowledge with --cursor ${read.cursor}`);
         return emails
-            .map((hit) => `${hitText(hit, undefined, local)}${markText(marks.get(hit.id), hit.excerptOnly)}\n`)
+            .map((hit) => `${hitText(hit, undefined, local)}${markText(marks.get(hit.id), hit.excerptOnly, hit.partialExcerpt === true)}\n`)
             .join("");
     });
 };

package/dist/mail/marks.d.ts

@@ -45,6 +45,8 @@ export interface BulkExcerpt {
     excerpt: string;
     /** What kept it, or the newsletter signs too few to leave it out. */
     cues: string[];
+    /** Stored from its first bytes, not whole: the excerpt may be all of it that there is. */
+    partial: boolean;
 }
 export interface MarkRead {
     /** The emails for the holder, oldest first; bulk, envelopes, drafts, suspicious senders and partial mail left out. */

package/dist/mail/marks.js

@@ -1,7 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { mailOwnText } from "../conversations/mail-text.js";
 import { isBusy } from "../store/sqlite/transaction.js";
-import { BULK_TRIAGE_DEFAULTS, newsletterSorter } from "./newsletter.js";
+import { BULK_TRIAGE_DEFAULTS, newsletterSorter, transactionalCue, } from "./newsletter.js";
 /** A holder's name: what `--holder` takes and the mark's key ends with. */
 export const HOLDER = /^[a-z0-9][a-z0-9-]{0,39}$/;
 /** At most this many emails are read past the mark in one go; the rest come with the next read. */
@@ -65,13 +65,15 @@ export const marksOf = async (store, mailbox) => {
         .flatMap(({ key, value, at }) => parsed(key.slice(PREFIX.length), value, at) ?? [])
         .sort((a, b) => a.holder.localeCompare(b.holder));
 };
+/** Sent to many and not an order, an invoice or a shipment: those carry List-Unsubscribe too, and are for the holder. */
+const isBulk = (email) => email.bulk && (email.listed || transactionalCue({ subject: email.subject, from: email.from }) === null);
 /** Why an email is not for the holder, or `held` while it is partial and young, or `read`. */
 const verdict = (email, now) => {
     if (email.draft)
         return "draft";
     if (email.envelope)
         return "envelope";
-    if (email.bulk)
+    if (isBulk(email))
         return "bulk";
     if (email.demoted)
         return "suspicious";
@@ -102,14 +104,14 @@ export const readPastMark = async (store, mailbox, holder, options = {}) => {
     const { wanted, sorted, oldestStoredAt: _, ...read } = await examine(store, mailbox, holder, options);
     const excerpts = wanted.flatMap((id) => {
         const one = sorted.get(id);
-        return one ? [{ email: one.email, excerpt: one.excerpt, cues: one.cues }] : [];
+        return one ? [{ email: one.email, excerpt: one.excerpt, cues: one.cues, partial: one.partial }] : [];
     });
     const emails = await store.mail.emailHits(wanted.filter((id) => !sorted.has(id)));
     return { emails, excerpts, ...read };
 };
 /**
  * The batch's bulk emails a holder might read, sorted by `newsletterSorter`, and where the batch ends so it holds at
- * most `perRead` excerpts. Drafts, envelopes, suspicious senders and partial mail keep their own verdicts.
+ * most `perRead` excerpts. Drafts, envelopes and suspicious senders keep their own verdicts; partial bulk mail is sorted too, and flagged.
  */
 const sortBulk = async (store, batch, triage) => {
     const sorted = new Map();
@@ -118,7 +120,7 @@ const sortBulk = async (store, batch, triage) => {
     const sort = newsletterSorter(triage.cues);
     let excerpts = 0;
     for (const [index, marked] of batch.entries()) {
-        if (!marked.bulk || marked.draft || marked.envelope || marked.demoted || marked.partial)
+        if (!isBulk(marked) || marked.draft || marked.envelope || marked.demoted)
             continue;
         const [email] = await store.mail.emailHits([marked.id]);
         if (!email)
@@ -130,7 +132,7 @@ const sortBulk = async (store, batch, triage) => {
             return { sorted, end: index };
         if (one.verdict === "excerpt")
             excerpts += 1;
-        sorted.set(marked.id, { ...one, email });
+        sorted.set(marked.id, { ...one, email, partial: marked.partial });
     }
     return { sorted, end: batch.length };
 };

package/dist/mail/newsletter.d.ts

@@ -27,6 +27,16 @@ export interface BulkSorted {
     cues: string[];
     excerpt: string;
 }
+/**
+ * What makes a bulk email transactional (an order, an invoice, a receipt, a shipment), or `null`. List-Unsubscribe
+ * sits on those too, so it proves nothing alone. Subject and sender only, so the store can ask it of every email.
+ * An order's number settles it; an amount with its currency or a word of the lists below does not, when the subject
+ * also advertises or the sender is a newsletter's ("Order now, save 20%").
+ */
+export declare const transactionalCue: ({ subject, from }: {
+    subject: string | null;
+    from: string | null;
+}) => string | null;
 /** The first lines of an email's own text, at most `chars`, cut at a word. */
 export declare const excerptOf: (text: string, chars: number) => string;
 /**

package/dist/mail/newsletter.js

@@ -130,6 +130,76 @@ const matcherOf = (words) => {
     const pattern = new RegExp(`(?<![\\p{L}\\p{N}])(?:${list.map(escaped).join("|")})`, "giu");
     return (text) => [...new Set([...text.toLowerCase().matchAll(pattern)].map(([found]) => found))];
 };
+/** Words that, in a subject, say "a record of something of yours": a purchase, a payment, a shipment. */
+const TRANSACTIONAL_WORDS = [
+    "заказ",
+    "счёт",
+    "счет",
+    "чек",
+    "квитанци",
+    "оплат",
+    "доставк",
+    "посылк",
+    "отправлен",
+    "order",
+    "invoice",
+    "receipt",
+    "payment",
+    "shipped",
+    "shipping",
+    "delivered",
+    "delivery",
+    "tracking",
+    "refund",
+    "pedido",
+    "factura",
+    "recibo",
+    "pago",
+    "envío",
+    "reembolso",
+];
+/** An amount with its currency, either side: `1 250 ₽`, `49,90 EUR`, `$12.50`. */
+const AMOUNT = /\d[\d\s.,]*\s?(?:₽|€|\$|£|руб|р\.|rub|eur|usd|gbp)(?![\p{L}])|(?:₽|€|\$|£|rub|eur|usd|gbp)\s?\d/iu;
+/** An order number as shops print it, such as Amazon's `406-3547475-4115561`. */
+const ORDER_ID = /(?<!\d)\d{3}-\d{7}-\d{7}(?!\d)/;
+/** Parts of a sender's address that say "orders, billing or shipping". */
+const TRANSACTIONAL_SENDERS = new Set([
+    "order",
+    "orders",
+    "billing",
+    "invoice",
+    "invoices",
+    "receipt",
+    "receipts",
+    "payment",
+    "payments",
+    "shipping",
+    "tracking",
+]);
+const transactionalWords = matcherOf(TRANSACTIONAL_WORDS);
+const advertisingWords = matcherOf(NEWSLETTER_WORDS);
+const NEWSLETTER_SENDER_PARTS = new Set(NEWSLETTER_SENDERS.filter((one) => !one.includes(".")));
+/**
+ * What makes a bulk email transactional (an order, an invoice, a receipt, a shipment), or `null`. List-Unsubscribe
+ * sits on those too, so it proves nothing alone. Subject and sender only, so the store can ask it of every email.
+ * An order's number settles it; an amount with its currency or a word of the lists below does not, when the subject
+ * also advertises or the sender is a newsletter's ("Order now, save 20%").
+ */
+export const transactionalCue = ({ subject, from }) => {
+    const title = subject ?? "";
+    const number = REFERENCE_NUMBER.exec(title) ?? ORDER_ID.exec(title);
+    if (number)
+        return number[0];
+    const parts = (from ?? "").toLowerCase().split(/[.@_+-]/);
+    if (advertisingWords(title).length > 0 || parts.some((part) => NEWSLETTER_SENDER_PARTS.has(part)))
+        return null;
+    const [word] = transactionalWords(title);
+    if (word)
+        return word;
+    if (AMOUNT.test(title))
+        return "an amount";
+    return parts.find((part) => TRANSACTIONAL_SENDERS.has(part)) ?? null;
+};
 /** The first lines of an email's own text, at most `chars`, cut at a word. */
 export const excerptOf = (text, chars) => {
     const flat = text

package/dist/mail/review.d.ts

@@ -22,6 +22,7 @@ export interface MailReviewOptions {
 export type MailHit = StoredHit & {
     marks?: EmailMarks;
     excerptOnly?: true;
+    partialExcerpt?: true;
 };
 export interface MailReview extends Review {
     chats: (Omit<ReviewChat, "messages"> & {