@wirecat/cli-core 0.593.0 → 0.595.0

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/entities/index.d.ts

@@ -9649,12 +9649,24 @@ export declare const ENTITIES: {
         readonly from: v.StringSchema<undefined>;
         readonly bytes: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
     }, undefined>;
-    readonly store_restore: v.StrictObjectSchema<{
+    readonly store_restore: v.UnionSchema<[v.StrictObjectSchema<{
         readonly path: v.StringSchema<undefined>;
         readonly restored_from: v.StringSchema<undefined>;
         readonly kept_at: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly schema: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
-    }, undefined>;
+    }, undefined>, v.StrictObjectSchema<{
+        readonly path: v.StringSchema<undefined>;
+        readonly restored_from: v.StringSchema<undefined>;
+        readonly rolled_back: v.LiteralSchema<true, undefined>;
+        readonly schema: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly was: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly tables: v.ArraySchema<v.StrictObjectSchema<{
+            readonly table: v.StringSchema<undefined>;
+            readonly rows: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        }, undefined>, undefined>;
+        readonly rebuilt: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+        readonly foreign_key_violations: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>], undefined>;
     readonly store_reset: v.UnionSchema<[v.StrictObjectSchema<{
         readonly path: v.StringSchema<undefined>;
         readonly exists: v.LiteralSchema<false, undefined>;

package/dist/entities/store-maintenance.d.ts

@@ -344,12 +344,24 @@ export declare const storeDecrypt: v.StrictObjectSchema<{
     readonly from: v.StringSchema<undefined>;
     readonly bytes: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
 }, undefined>;
-export declare const storeRestore: v.StrictObjectSchema<{
+export declare const storeRestore: v.UnionSchema<[v.StrictObjectSchema<{
     readonly path: v.StringSchema<undefined>;
     readonly restored_from: v.StringSchema<undefined>;
     readonly kept_at: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly schema: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
-}, undefined>;
+}, undefined>, v.StrictObjectSchema<{
+    readonly path: v.StringSchema<undefined>;
+    readonly restored_from: v.StringSchema<undefined>;
+    readonly rolled_back: v.LiteralSchema<true, undefined>;
+    readonly schema: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly was: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly tables: v.ArraySchema<v.StrictObjectSchema<{
+        readonly table: v.StringSchema<undefined>;
+        readonly rows: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>, undefined>;
+    readonly rebuilt: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly foreign_key_violations: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+}, undefined>], undefined>;
 export declare const storeReset: v.UnionSchema<[v.StrictObjectSchema<{
     readonly path: v.StringSchema<undefined>;
     readonly exists: v.LiteralSchema<false, undefined>;

package/dist/entities/store-maintenance.js

@@ -155,12 +155,25 @@ export const storeBackup = v.strictObject({
     encrypted: v.optional(v.literal(true)),
 });
 export const storeDecrypt = v.strictObject({ path: text, from: text, bytes: count });
-export const storeRestore = v.strictObject({
-    path: text,
-    restored_from: text,
-    kept_at: v.nullable(text),
-    schema: count,
-});
+export const storeRestore = v.union([
+    v.strictObject({
+        path: text,
+        restored_from: text,
+        kept_at: v.nullable(text),
+        schema: count,
+    }),
+    /** From a rollback copy: its tables put back in place, the store returned to `schema` from `was`. */
+    v.strictObject({
+        path: text,
+        restored_from: text,
+        rolled_back: v.literal(true),
+        schema: count,
+        was: count,
+        tables: v.array(v.strictObject({ table: text, rows: count })),
+        rebuilt: v.array(text),
+        foreign_key_violations: count,
+    }),
+]);
 export const storeReset = v.union([
     v.strictObject({ ...absent.entries, reset: v.literal(false) }),
     v.strictObject({

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"> & {

package/dist/store/migrations.d.ts

@@ -1,9 +1,15 @@
 import type { CacheDatabase } from "./driver.js";
+import { type RollbackCopyOptions } from "./sqlite/rollback-copy.js";
 export interface Migration {
     version: number;
     /** The oldest schema version whose statements still work on a file at this version. */
     minCompatible: number;
     statements: string[];
+    /**
+     * The base tables it changes, by their names before it. Required when it raises `minCompatible`: they are copied
+     * aside before it runs, so `store restore` can take the store back to the version older tools still open.
+     */
+    tables?: string[];
     /** Runs before the statements, inside the same transaction. */
     before?: (database: CacheDatabase, now: () => number) => void;
 }
@@ -12,7 +18,8 @@ export interface Migration {
  * schema. **A migration that has reached anyone's file is never edited.** After it: forward-only and additive —
  * no `DROP` and no rebuild of a base table, a new column is nullable or has a default, and every `INSERT` in the
  * store names its columns — so an older `tg` keeps writing to a file a newer `max` has migrated. Only a breaking
- * change raises `minCompatible`, and that is a major version of this package. The search indexes are derived and
+ * change raises `minCompatible`, and that is a major version of this package; it names the base tables it changes
+ * (`tables`), which are copied aside before it runs (`sqlite/rollback-copy.ts`). The search indexes are derived and
  * may be dropped and rebuilt. Every version after the first gets a `version-N.test.ts` that opens a file at N-1.
  *
  * Times are epoch milliseconds: an integer sorts and ranges without a format to agree on.
@@ -24,11 +31,13 @@ export declare const MIGRATIONS: Migration[];
  * that fails names `store reset` when the app has one: without it the owner is stuck until a build that can migrate
  * the file. An app without that command (drive) passes no `command`, and the advice names none.
  */
-export declare const migrate: (database: CacheDatabase, { migrations, now, command, version, ownTable, }?: {
+export declare const migrate: (database: CacheDatabase, { migrations, now, command, version, ownTable, rollback, }?: {
     migrations?: Migration[];
     now?: () => number;
     command?: string;
     /** The CLI's own version: with `command`, it is recorded so a later upgrade can name who it locks out. */
     version?: string;
     ownTable?: string | null;
+    /** A store on disk: before a migration that raises `minCompatible`, a copy of the tables it changes. */
+    rollback?: RollbackCopyOptions;
 }) => string | undefined;