@wirecat/cli-core 0.593.0 → 0.595.0

package/dist/crm/testing/source.js

@@ -1,3 +1,7 @@
+import { CliError } from "@wirecat/cli-base";
+import { CRM_VERBS } from "../writer.js";
+/** Custom codes the fake refuses: each is a neutral field under another name. */
+export const FAKE_CRM_ALIASES = ["stage", "pipeline", "owner", "status"];
 /** When the fake CRM's changes happened: well before any `now` a contract syncs at. */
 const STAMPED_FROM = Date.UTC(2026, 0, 1);
 export const SALES_PIPELINE = {
@@ -32,6 +36,16 @@ export const fakeCrmSource = (options = {}) => {
     const expired = new Map();
     let hidden = false;
     const calls = { pipelines: 0, changes: 0, ids: 0 };
+    const capabilities = {
+        kinds: ["deal", "lead"],
+        verbs: CRM_VERBS,
+        idempotent: false,
+        ...options.capabilities,
+    };
+    const writes = [];
+    const answered = new Map();
+    let made = 0;
+    let lose = false;
     const of = (kind) => {
         const held = rows.get(kind) ?? new Map();
         rows.set(kind, held);
@@ -42,10 +56,111 @@ export const fakeCrmSource = (options = {}) => {
         const next = at + size;
         return { slice: list.slice(at, next), nextPage: next < list.length ? String(next) : undefined };
     };
-    return {
+    const held = (kind, externalId) => {
+        const found = of(kind).get(externalId);
+        if (!found || found.deleted)
+            throw new CliError("not_found", `the CRM has no ${kind} ${externalId}`);
+        return found.record;
+    };
+    const placed = (kind, pipelineId, stageId) => {
+        const pipeline = pipelineId === undefined ? pipelines[kind][0] : pipelines[kind].find((one) => one.externalId === pipelineId);
+        const stage = stageId === undefined ? pipeline?.stages[0] : pipeline?.stages.find((one) => one.externalId === stageId);
+        if (!pipeline || !stage)
+            throw new CliError("validation_error", `the CRM has no stage ${stageId} there`);
+        return { pipeline: pipeline.externalId, stage: stage.externalId, outcome: stage.outcome };
+    };
+    const applied = (item, fields) => {
+        const { custom, owner, pipeline, stage, ...named } = fields;
+        const metadata = {
+            ...item.metadata,
+            ...(owner === undefined ? {} : { owner }),
+            ...(custom ? { custom: { ...item.metadata?.custom, ...custom } } : {}),
+        };
+        return {
+            ...item,
+            ...Object.fromEntries(Object.entries(named).filter(([, value]) => value !== undefined)),
+            ...(pipeline === undefined ? {} : { pipeline }),
+            ...(stage === undefined ? {} : { stage }),
+            metadata,
+            updatedAt: null,
+        };
+    };
+    const refuseAliases = (fields) => {
+        const refused = Object.keys(fields.custom ?? {}).find((code) => FAKE_CRM_ALIASES.includes(code));
+        if (refused)
+            throw new CliError("validation_error", `${refused} is not a custom field`);
+    };
+    /** Each write once: a repeated idempotent id answers its first outcome; a lost answer still made the change. */
+    const write = (verb, kind, externalId, operationId, act) => {
+        writes.push({ verb, kind, externalId, operationId });
+        if (capabilities.idempotent && answered.has(operationId))
+            return answered.get(operationId);
+        const done = act();
+        if (capabilities.idempotent)
+            answered.set(operationId, done);
+        if (lose) {
+            lose = false;
+            throw new CliError("outcome_unknown", "the CRM did not answer");
+        }
+        return done;
+    };
+    const saved = (kind, item) => {
+        fake.put(kind, item);
+        return held(kind, item.externalId);
+    };
+    const fake = {
         provider: "example-crm",
         traits,
         calls,
+        capabilities,
+        writes,
+        loseNextAnswer() {
+            lose = true;
+        },
+        async create(kind, draft, { operationId }) {
+            refuseAliases(draft);
+            return write("create", kind, null, operationId, () => {
+                const { pipeline, stage } = placed(kind, draft.pipeline, draft.stage);
+                made += 1;
+                const blank = { externalId: `${kind}-new-${made}`, title: draft.title, pipeline, stage };
+                return saved(kind, applied(blank, { ...draft, pipeline, stage }));
+            });
+        },
+        async update(kind, externalId, patch, { operationId }) {
+            refuseAliases(patch);
+            return write("update", kind, externalId, operationId, () => {
+                const item = held(kind, externalId);
+                const at = patch.stage === undefined ? {} : placed(kind, patch.pipeline ?? item.pipeline, patch.stage);
+                return saved(kind, applied(item, { ...patch, ...at }));
+            });
+        },
+        async move(kind, externalId, stage, { operationId }) {
+            return write("move", kind, externalId, operationId, () => {
+                const item = held(kind, externalId);
+                return saved(kind, { ...item, stage: placed(kind, item.pipeline, stage).stage, status: null, updatedAt: null });
+            });
+        },
+        async close(kind, externalId, outcome, { operationId, reason }) {
+            return write("close", kind, externalId, operationId, () => {
+                const item = held(kind, externalId);
+                const pipeline = pipelines[kind].find((one) => one.externalId === item.pipeline);
+                const closing = pipeline?.stages.find((one) => one.outcome === outcome);
+                return saved(kind, {
+                    ...item,
+                    ...(closing ? { stage: closing.externalId } : {}),
+                    status: outcome,
+                    closedReason: reason ?? null,
+                    updatedAt: null,
+                });
+            });
+        },
+        async remove(kind, externalId, { operationId }) {
+            write("remove", kind, externalId, operationId, () => {
+                held(kind, externalId);
+                fake.delete(kind, externalId);
+                return undefined;
+            });
+        },
         put(kind, record) {
             version += 1;
             // A CRM stamps each change; without one here the store would take its own clock, which an id pass skips.
@@ -99,6 +214,7 @@ export const fakeCrmSource = (options = {}) => {
             return { ids: slice, ...(nextPage === undefined ? {} : { nextPage }) };
         },
     };
+    return fake;
 };
 export const exampleDeal = (externalId, extra = {}) => ({
     externalId,

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

@@ -138,12 +138,13 @@ export const crmSyncContract = (make) => CRM_TRAIT_COMBINATIONS.flatMap((traits)
             assert.deepEqual(await deals(), ["d2"]);
             assert.deepEqual(run.issues.map(({ kind, reason, externalId }) => [kind, reason, externalId]), [["deal", "crm.stage-unknown", "d1"]]);
         }),
-        test("a pipeline sharing the other kind's pipeline id is named as an issue, and the rest syncs", async ({ source, sync, deals, }) => {
+        test("a lead pipeline may share a deal pipeline's id", async ({ source, sync, deals }) => {
             source.setPipelines("lead", [{ ...LEAD_PIPELINE, externalId: SALES_PIPELINE.externalId }]);
             source.put("deal", exampleDeal("d1"));
+            source.put("lead", exampleLead("l1", { pipeline: SALES_PIPELINE.externalId }));
             const run = await sync();
             assert.deepEqual(await deals(), ["d1"]);
-            assert.ok(run.issues.some(({ kind, reason }) => kind === "lead" && reason === "crm.pipeline-clash"));
+            assert.deepEqual(run.issues, []);
         }),
         test("a contact joins a person by exact email, and a company never joins an organization by name", async ({ source, sync, store, account, }) => {
             const own = await store.knowledge.addOrganization({ kind: "company", name: "Example company c1" });

package/dist/crm/testing/write-contract.d.ts

@@ -0,0 +1,21 @@
+import type { CrmPipeline } from "../../domain/crm.js";
+import { type DealKind } from "../../domain/deals.js";
+import type { ContractCase } from "../../meetings/index.js";
+import { type CrmWriter } from "../writer.js";
+/**
+ * One adapter over recorded or faked responses, fresh for each case, that takes writes of `kind`. `pipeline` is one
+ * of the kind's pipelines with at least two open stages and a won one.
+ */
+export interface CrmWriteFixture {
+    writer: CrmWriter;
+    kind?: DealKind;
+    pipeline: CrmPipeline;
+    /** Custom field codes that are a neutral field under the CRM's own name (Bitrix24's `stageId`, `ASSIGNED_BY_ID`). */
+    aliases: readonly string[];
+    /** Makes the next write's answer lost after the CRM got it, as a dropped connection does. */
+    loseNextAnswer: () => void;
+    /** How many write requests reached the CRM so far. */
+    requests: () => number;
+}
+/** What every CRM adapter's write side does, whatever the CRM: run each case in the adapter's tests. */
+export declare const crmWriteContract: (make: () => CrmWriteFixture | Promise<CrmWriteFixture>) => ContractCase[];

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;
+}>;