@wirecat/cli-core 0.592.0 → 0.594.0

package/dist/crm/testing/write-contract.js

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import { isCliError } from "@wirecat/cli-base";
+import { DEAL_KINDS } from "../../domain/deals.js";
+import { CRM_VERBS } from "../writer.js";
+let operations = 0;
+const operation = () => {
+    operations += 1;
+    return { operationId: `contract-${Date.now()}-${operations}` };
+};
+const refusedWith = async (code, act) => {
+    try {
+        await act();
+    }
+    catch (error) {
+        assert.ok(isCliError(error), `a CliError, not ${String(error)}`);
+        assert.equal(error.code, code);
+        return;
+    }
+    assert.fail(`expected ${code}`);
+};
+const outcomeOf = (pipeline, item) => item.status ?? pipeline.stages.find((stage) => stage.externalId === item.stage)?.outcome;
+/** What every CRM adapter's write side does, whatever the CRM: run each case in the adapter's tests. */
+export const crmWriteContract = (make) => {
+    const openStages = async () => {
+        const fixture = await make();
+        const open = fixture.pipeline.stages.filter((stage) => stage.outcome === "open");
+        assert.ok(open.length >= 2, "the fixture's pipeline has two open stages");
+        const kind = fixture.kind ?? "deal";
+        const made = await fixture.writer.create(kind, {
+            title: "Example contract deal",
+            pipeline: fixture.pipeline.externalId,
+            stage: open[0]?.externalId,
+            amount: "1500.50",
+            currency: "EUR",
+        }, operation());
+        return { ...fixture, kind, open, made };
+    };
+    return [
+        {
+            name: "capabilities: known verbs and kinds, and a yes or no for repeated writes",
+            async run() {
+                const { writer } = await make();
+                const { kinds, verbs, idempotent } = writer.capabilities;
+                assert.ok(kinds.length > 0 && kinds.every((kind) => DEAL_KINDS.includes(kind)));
+                assert.ok(verbs.length > 0 && verbs.every((verb) => CRM_VERBS.includes(verb)));
+                assert.equal(typeof idempotent, "boolean");
+            },
+        },
+        {
+            name: "create answers the whole item in the stage it was given, with its new id",
+            async run() {
+                const { made, pipeline, open } = await openStages();
+                assert.ok(made.externalId, "an id");
+                assert.equal(made.title, "Example contract deal");
+                assert.equal(made.pipeline, pipeline.externalId);
+                assert.equal(made.stage, open[0]?.externalId);
+                assert.equal(made.currency, "EUR");
+                assert.equal(Number(made.amount), 1500.5);
+            },
+        },
+        {
+            name: "update of one field answers the whole item, every other field as it was",
+            async run() {
+                const { writer, kind, made } = await openStages();
+                const changed = await writer.update(kind, made.externalId, { title: "Example renamed" }, operation());
+                assert.equal(changed.externalId, made.externalId);
+                assert.equal(changed.title, "Example renamed");
+                for (const field of ["pipeline", "stage", "amount", "currency", "organization"])
+                    assert.deepEqual(changed[field] ?? null, made[field] ?? null, `${field} kept`);
+                assert.deepEqual(changed.people ?? [], made.people ?? [], "people kept");
+            },
+        },
+        {
+            name: "move goes to the stage given; close marks it won",
+            async run() {
+                const { writer, kind, made, open, pipeline } = await openStages();
+                const moved = await writer.move(kind, made.externalId, open[1]?.externalId, operation());
+                assert.equal(moved.stage, open[1]?.externalId);
+                assert.equal(outcomeOf(pipeline, moved), "open");
+                const closed = await writer.close(kind, made.externalId, "won", operation());
+                assert.equal(outcomeOf(pipeline, closed), "won");
+            },
+        },
+        {
+            name: "remove answers once the CRM deleted it",
+            async run() {
+                const { writer, kind, made } = await openStages();
+                await writer.remove(kind, made.externalId, operation());
+            },
+        },
+        {
+            name: "a custom code that is a neutral field under another name is refused, and nothing is sent",
+            async run() {
+                const { writer, kind, made, aliases, requests, open } = await openStages();
+                assert.ok(aliases.length > 0, "the fixture names the CRM's own names for stage and owner");
+                for (const code of aliases) {
+                    const before = requests();
+                    await refusedWith("validation_error", () => writer.update(kind, made.externalId, { custom: { [code]: open[1]?.externalId } }, operation()));
+                    assert.equal(requests(), before, `${code}: nothing sent`);
+                }
+            },
+        },
+        {
+            name: "a lost answer is outcome_unknown after one request, never retried",
+            async run() {
+                const fixture = await openStages();
+                const before = fixture.requests();
+                fixture.loseNextAnswer();
+                await refusedWith("outcome_unknown", () => fixture.writer.update(fixture.kind, fixture.made.externalId, { title: "Example lost" }, operation()));
+                assert.equal(fixture.requests(), before + 1, "one request");
+            },
+        },
+        {
+            name: "an idempotent CRM answers a repeated operation id from its record",
+            async run() {
+                const { writer, kind, pipeline } = await make();
+                if (!writer.capabilities.idempotent)
+                    return;
+                const once = operation();
+                const draft = { title: "Example repeated", pipeline: pipeline.externalId };
+                const first = await writer.create(kind ?? "deal", draft, once);
+                const again = await writer.create(kind ?? "deal", draft, once);
+                assert.equal(again.externalId, first.externalId);
+            },
+        },
+    ];
+};

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. */