@wirecat/cli-core 0.589.0 → 0.591.0

package/dist/crm/sync.js

@@ -0,0 +1,291 @@
+import { CliError } from "@wirecat/cli-base";
+import { runBudget } from "../background/budget.js";
+import { progressLine, progressOf } from "../background/checkpoints.js";
+import { CRM_KINDS, isItemKind } from "../domain/crm.js";
+import { DEAL_KINDS } from "../domain/deals.js";
+import { isCliFailure } from "../errors/failures.js";
+const DAY = 86_400_000;
+/** A row the CRM changed this close to the id pass's start may be newer than the list, by the two clocks' skew. */
+const CLOCK_MARGIN = 60 * 60_000;
+/** An id pass that would mark more than this share of a kind deleted is held: a CRM that lost its rights lists none. */
+const MOST_UNLISTED = 0.5;
+/** Below this many stored rows a pass may empty a kind: a small CRM really may lose half its deals. */
+const GUARDED_FROM = 10;
+const isToken = (value) => value === null || typeof value === "string";
+export const parseCrmCursor = (value) => {
+    if (value == null)
+        return null;
+    try {
+        const cursor = JSON.parse(value);
+        if (cursor?.v !== 1 || !isToken(cursor.token) || typeof cursor.done !== "number")
+            return null;
+        const round = cursor.round;
+        const pass = cursor.pass;
+        if (round != null && (!isToken(round.from) || !isToken(round.page) || typeof round.reset !== "boolean"))
+            return null;
+        if (pass != null &&
+            (!isToken(pass.page) ||
+                typeof pass.startedAt !== "number" ||
+                !Array.isArray(pass.seen) ||
+                pass.seen.some((id) => typeof id !== "string")))
+            return null;
+        return {
+            v: 1,
+            token: cursor.token,
+            round: round ?? null,
+            done: cursor.done,
+            updatedAt: typeof cursor.updatedAt === "number" ? cursor.updatedAt : null,
+            pass: pass ?? null,
+            passAt: typeof cursor.passAt === "number" ? cursor.passAt : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+};
+export const cursorName = (kind) => `crm:${kind}`;
+const CONTINUE = "run sync again to continue";
+const fresh = () => ({ v: 1, token: null, round: null, done: 0, updatedAt: null, pass: null, passAt: 0 });
+const readPipelines = async (run, kind) => {
+    const why = run.budget.take();
+    if (why)
+        return why;
+    const pipelines = await run.source.pipelines(kind);
+    const { saved, skipped } = await run.store.crm.savePipelines(run.account, kind, pipelines);
+    run.report.pipelines += saved;
+    for (const one of skipped)
+        run.report.issues.push({ kind, ...one });
+    return null;
+};
+/** One page saved; an item whose stage is unknown gets one more chance after the kind's pipelines are read again. */
+const savePage = async (run, kind, page) => {
+    const { store, account } = run;
+    if (!isItemKind(kind)) {
+        const saved = kind === "person"
+            ? await store.crm.savePeople(account, page.items)
+            : await store.crm.saveOrganizations(account, page.items);
+        return { saved: saved.saved, stop: null };
+    }
+    const items = page.items;
+    let { saved, skipped } = await store.crm.saveItems(account, kind, items);
+    let stop = null;
+    if (skipped.some(({ reason }) => reason === "crm.stage-unknown") && !run.pipelinesReread.has(kind)) {
+        run.pipelinesReread.add(kind);
+        stop = await readPipelines(run, kind);
+        if (!stop) {
+            const again = new Set(skipped.filter(({ reason }) => reason === "crm.stage-unknown").map(({ externalId }) => externalId));
+            const retried = await store.crm.saveItems(account, kind, items.filter(({ externalId }) => again.has(externalId)));
+            saved += retried.saved;
+            skipped = [...skipped.filter(({ reason }) => reason !== "crm.stage-unknown"), ...retried.skipped];
+        }
+    }
+    // An item not kept is named, and the round goes on: one bad row must not stop the CRM's copy for good.
+    for (const one of skipped)
+        run.report.issues.push({ kind, ...one });
+    return { saved, stop };
+};
+const syncKind = async (run, kind, options, result) => {
+    const { source, store, account, now, budget, signal } = run;
+    const name = cursorName(kind);
+    let cursor = parseCrmCursor((await store.sync.syncState(account, name))?.value) ?? fresh();
+    if (options.rescan)
+        cursor = { ...cursor, round: { from: null, page: null, reset: false }, done: 0, pass: null, passAt: 0 };
+    let round = cursor.round ?? { from: cursor.token, page: null, reset: false };
+    if (cursor.round === null)
+        cursor = { ...cursor, done: 0 };
+    let listed = false;
+    const show = () => Object.assign(result, { round: round.from === null ? "full" : "changes", reset: round.reset });
+    show();
+    const save = async (patch = {}) => {
+        cursor = { ...cursor, round: listed ? null : round, updatedAt: now, ...patch };
+        await store.sync.setSyncState(account, name, JSON.stringify(cursor));
+    };
+    let restarted = false;
+    const pages = new Set();
+    for (;;) {
+        const why = budget.take();
+        if (why)
+            return why;
+        const page = await source.changes(kind, round.from, round.page ?? undefined);
+        if (signal?.aborted)
+            return "cancelled";
+        if ("reset" in page) {
+            if (round.page !== null && !restarted) {
+                restarted = true;
+                round = { ...round, page: null };
+            }
+            else if (round.from === null)
+                throw new CliError("invalid_response", `${source.provider} refused a full list as a dead cursor`);
+            else
+                round = { from: null, page: null, reset: true };
+            cursor = { ...cursor, done: 0 };
+            show();
+            await save();
+            continue;
+        }
+        const { saved, stop } = await savePage(run, kind, page);
+        result.saved += saved;
+        cursor = { ...cursor, done: cursor.done + saved };
+        if (page.removed?.length)
+            result.removed += await store.crm.remove(account, kind, page.removed);
+        run.moved();
+        if (page.nextPage === undefined) {
+            listed = true;
+            await save({ token: page.cursor ?? null });
+            break;
+        }
+        if (pages.has(page.nextPage))
+            throw new CliError("invalid_response", `${source.provider} returned the same page twice`);
+        pages.add(page.nextPage);
+        round = { ...round, page: page.nextPage };
+        await save();
+        if (stop)
+            return stop;
+    }
+    const passes = source.ids && !source.traits.removedInChanges && kind !== "person";
+    const due = cursor.pass !== null || now - cursor.passAt >= (options.passEvery ?? DAY);
+    if (passes && due) {
+        const ids = source.ids;
+        let pass = cursor.pass ?? { page: null, startedAt: now, seen: [] };
+        for (;;) {
+            const why = budget.take();
+            if (why) {
+                result.pass = "partial";
+                await save({ pass });
+                return why;
+            }
+            const page = await ids.call(source, kind, pass.page ?? undefined);
+            if (signal?.aborted)
+                return "cancelled";
+            pass = { ...pass, seen: [...pass.seen, ...page.ids], page: page.nextPage ?? null };
+            run.moved();
+            if (page.nextPage === undefined)
+                break;
+            await save({ pass });
+        }
+        const before = pass.startedAt - CLOCK_MARGIN;
+        const stored = await store.crm.count(account, kind);
+        const unlisted = await store.crm.removeUnlisted(account, kind, pass.seen, before, { dryRun: true });
+        if (!options.rescan && stored >= GUARDED_FROM && unlisted > stored * MOST_UNLISTED) {
+            result.pass = "held";
+            run.report.issues.push({
+                kind,
+                reason: "crm.unlisted-held",
+                message: `${source.provider} listed ${pass.seen.length} ${kind} ids, so ${unlisted} of the ${stored} stored would be ` +
+                    "marked deleted; nothing was — check the sign-in's rights, then run sync --rescan to let it through",
+            });
+        }
+        else {
+            result.unlisted = await store.crm.removeUnlisted(account, kind, pass.seen, before);
+            result.pass = "complete";
+        }
+        await save({ pass: null, passAt: pass.startedAt });
+    }
+    result.state = "complete";
+    return null;
+};
+/**
+ * Brings one CRM account's copy up to date: both kinds' pipelines, then contacts, companies, deals and leads, each
+ * from its cursor or listed in full, a page at a time, each page saved with the round's place in the cursor, so a
+ * run the budget stops, or one that fails, goes on from there. Deletions come from `changes()`, or from a list of
+ * every id that marks only after its last page arrived, and never more than half of a kind without `--rescan`.
+ */
+export const syncCrm = async (source, store, account, options = {}) => {
+    const now = options.now ?? Date.now();
+    const budget = options.budget ?? runBudget();
+    const report = {
+        provider: source.provider,
+        account: account.account,
+        pipelines: 0,
+        synced: [],
+        issues: [],
+        complete: true,
+        state: "complete",
+        progress: { requests: 0, saved: 0, steps: 0 },
+    };
+    let steps = 0;
+    const run = {
+        source,
+        store,
+        account,
+        now,
+        budget,
+        signal: options.signal,
+        report,
+        pipelinesReread: new Set(),
+        moved: () => {
+            steps += 1;
+        },
+    };
+    const kinds = CRM_KINDS.filter((kind) => source.traits.kinds.includes(kind));
+    let stopped = null;
+    for (const kind of DEAL_KINDS)
+        if (!stopped && kinds.includes(kind)) {
+            stopped = await readPipelines(run, kind);
+            if (options.signal?.aborted)
+                stopped = "cancelled";
+        }
+    for (const kind of kinds) {
+        const result = {
+            kind,
+            round: "changes",
+            reset: false,
+            state: "partial",
+            saved: 0,
+            removed: 0,
+            unlisted: 0,
+        };
+        report.synced.push(result);
+        if (stopped)
+            continue;
+        try {
+            stopped = await syncKind(run, kind, options, result);
+        }
+        catch (error) {
+            if (options.signal?.aborted) {
+                stopped = "cancelled";
+                continue;
+            }
+            // An adapter's own failure says what went wrong; anything else may carry a request URL with a secret in it.
+            result.error = isCliFailure(error) ? error.message : `the ${kind} copy could not be synced`;
+        }
+    }
+    report.progress = {
+        requests: budget.used,
+        saved: report.synced.reduce((sum, one) => sum + one.saved, 0),
+        steps,
+    };
+    report.complete = report.synced.every((one) => one.state === "complete" && one.error === undefined);
+    report.state = report.complete && stopped === null ? "complete" : "partial";
+    if (stopped)
+        report.stopped = stopped;
+    if (report.state === "partial") {
+        report.complete = false;
+        report.hint = CONTINUE;
+    }
+    return report;
+};
+/** Each kind's sync in the WC-LIFE-14 shape: `cursor_age_ms` growing on a `partial` one means nothing moves it. */
+export const crmStatus = async (store, account, { profile, now, kinds = CRM_KINDS }) => {
+    const items = [];
+    for (const kind of kinds) {
+        const cursor = parseCrmCursor((await store.sync.syncState(account, cursorName(kind)))?.value);
+        const progress = progressOf({
+            job: `crm ${kind}`,
+            profile,
+            done: cursor?.done ?? 0,
+            complete: cursor !== null && cursor.round === null && cursor.pass === null,
+            ...(cursor?.updatedAt == null ? {} : { updatedAt: new Date(cursor.updatedAt).toISOString() }),
+            now: new Date(now),
+        });
+        items.push({
+            kind,
+            round: cursor?.round ? (cursor.round.from === null ? "full" : "changes") : null,
+            id_pass: cursor?.pass ? "partial" : cursor?.passAt ? new Date(cursor.passAt).toISOString() : null,
+            stored: await store.crm.count(account, kind),
+            ...progress,
+            line: progressLine(progress),
+        });
+    }
+    return { items, page: 1, limit: Math.max(1, items.length), hasMore: false };
+};

package/dist/crm/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { exampleDeal, exampleLead, exampleOrganization, examplePerson, type FakeCrmSource, type FakeCrmSourceOptions, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+export { type CrmSourceFixture, crmSourceContract } from "./source-contract.js";
+export { CRM_TRAIT_COMBINATIONS, type CrmSyncFixture, crmSyncContract } from "./sync-contract.js";

package/dist/crm/testing/index.js

@@ -0,0 +1,3 @@
+export { exampleDeal, exampleLead, exampleOrganization, examplePerson, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+export { crmSourceContract } from "./source-contract.js";
+export { CRM_TRAIT_COMBINATIONS, crmSyncContract } from "./sync-contract.js";

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

@@ -0,0 +1,17 @@
+import { type CrmKind } from "../../domain/crm.js";
+import type { ContractCase } from "../../meetings/index.js";
+import type { CrmSource } from "../source.js";
+/**
+ * One adapter over recorded or faked responses, fresh for each case. Every kind its traits name must list at least
+ * one row, so the checks have something to look at.
+ */
+export interface CrmSourceFixture {
+    source: CrmSource;
+    /** A cursor the CRM refuses; absent skips that case. */
+    deadCursor?: {
+        kind: CrmKind;
+        cursor: string;
+    };
+}
+/** What every CRM adapter answers, whatever the CRM: run each case in the adapter's tests. */
+export declare const crmSourceContract: (make: () => CrmSourceFixture | Promise<CrmSourceFixture>) => ContractCase[];

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

@@ -0,0 +1,137 @@
+import assert from "node:assert/strict";
+import { isItemKind } from "../../domain/crm.js";
+import { DEAL_KINDS, STAGE_OUTCOMES } from "../../domain/deals.js";
+const MAX_PAGES = 1_000;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const DECIMAL = /^\d{1,16}(\.\d{1,6})?$/;
+/** Every page of one kind from `cursor`, checking each page is new and the last one gives a cursor. */
+const listAll = async (source, kind, cursor) => {
+    const items = [];
+    const pages = new Set();
+    let page;
+    for (let read = 0; read < MAX_PAGES; read += 1) {
+        const answer = await source.changes(kind, cursor, page);
+        assert.ok(!("reset" in answer), `${kind}: a full list is never a dead cursor`);
+        const listed = answer;
+        assert.ok(Array.isArray(listed.items), `${kind}: a page has items`);
+        items.push(...listed.items);
+        if (listed.nextPage === undefined) {
+            assert.ok(listed.cursor === null || typeof listed.cursor === "string", `${kind}: the last page gives a cursor`);
+            return { items, cursor: listed.cursor ?? null };
+        }
+        assert.ok(!pages.has(listed.nextPage), `${kind}: the same page twice`);
+        pages.add(listed.nextPage);
+        page = listed.nextPage;
+    }
+    throw new assert.AssertionError({ message: `${kind}: more than ${MAX_PAGES} pages` });
+};
+/** What every CRM adapter answers, whatever the CRM: run each case in the adapter's tests. */
+export const crmSourceContract = (make) => {
+    const cases = [
+        {
+            name: "pipelines: unique ids across both kinds, stages with a known outcome and unique ids",
+            async run() {
+                const { source } = await make();
+                const seen = new Set();
+                for (const kind of DEAL_KINDS.filter((one) => source.traits.kinds.includes(one))) {
+                    const pipelines = await source.pipelines(kind);
+                    assert.ok(pipelines.length > 0, `${kind}: at least one pipeline`);
+                    for (const pipeline of pipelines) {
+                        assert.ok(!seen.has(pipeline.externalId), `pipeline ${pipeline.externalId} is listed twice`);
+                        seen.add(pipeline.externalId);
+                        assert.ok(pipeline.name.trim(), `pipeline ${pipeline.externalId} has a name`);
+                        assert.ok(pipeline.stages.length > 0, `pipeline ${pipeline.externalId} has stages`);
+                        const stages = new Set(pipeline.stages.map(({ externalId }) => externalId));
+                        assert.equal(stages.size, pipeline.stages.length, `pipeline ${pipeline.externalId}: stage ids are unique`);
+                        for (const stage of pipeline.stages) {
+                            assert.ok(STAGE_OUTCOMES.includes(stage.outcome), `stage ${stage.externalId}'s outcome`);
+                            assert.ok(Number.isFinite(stage.position), `stage ${stage.externalId}'s position is a number`);
+                        }
+                    }
+                }
+            },
+        },
+        {
+            name: "changes: a full list pages to its end, every item stands in a listed stage, fields in the neutral shape",
+            async run() {
+                const { source } = await make();
+                const stages = new Map();
+                for (const kind of DEAL_KINDS.filter((one) => source.traits.kinds.includes(one)))
+                    stages.set(kind, new Set((await source.pipelines(kind)).flatMap((pipeline) => pipeline.stages.map((stage) => `${pipeline.externalId}\u0000${stage.externalId}`))));
+                for (const kind of source.traits.kinds) {
+                    const { items } = await listAll(source, kind, null);
+                    assert.ok(items.length > 0, `${kind}: the fixture lists at least one`);
+                    const ids = new Set();
+                    for (const raw of items) {
+                        const item = raw;
+                        assert.equal(typeof item.externalId, "string", `${kind}: externalId is a string`);
+                        assert.ok(!ids.has(item.externalId), `${kind} ${item.externalId} is listed twice`);
+                        ids.add(item.externalId);
+                        if (!isItemKind(kind))
+                            continue;
+                        const one = raw;
+                        assert.ok(typeof one.title === "string", `${kind} ${one.externalId} has a title`);
+                        assert.ok(stages.get(kind)?.has(`${one.pipeline}\u0000${one.stage}`), `${kind} ${one.externalId} stands in stage ${one.stage} of pipeline ${one.pipeline}, which is listed`);
+                        assert.equal(one.amount == null, one.currency == null, `${kind} ${one.externalId}: an amount with its currency`);
+                        if (one.amount != null)
+                            assert.match(String(one.amount), DECIMAL, `${kind} ${one.externalId}: a decimal string`);
+                        for (const day of [one.closeDate, one.closedDate])
+                            if (day != null)
+                                assert.match(day, DAY, `${kind} ${one.externalId}: days are YYYY-MM-DD`);
+                        for (const at of [one.createdAt, one.updatedAt])
+                            if (at != null)
+                                assert.ok(Number.isFinite(at) && at > 0, `${kind} ${one.externalId}: times are epoch ms`);
+                    }
+                }
+            },
+        },
+        {
+            name: "changes: the cursor a full list gave reads again without failing",
+            async run() {
+                const { source } = await make();
+                for (const kind of source.traits.kinds) {
+                    const { cursor } = await listAll(source, kind, null);
+                    if (cursor !== null)
+                        await listAll(source, kind, cursor);
+                }
+            },
+        },
+        {
+            name: "ids: a list of every id holds every row a full list gave",
+            async run() {
+                const { source } = await make();
+                if (source.traits.removedInChanges && !source.ids)
+                    return;
+                assert.ok(source.ids, "a CRM that does not name deletions in changes() lists every id");
+                const ids = source.ids;
+                for (const kind of source.traits.kinds.filter((one) => one !== "person")) {
+                    const { items } = await listAll(source, kind, null);
+                    const listed = new Set();
+                    let page;
+                    for (let read = 0; read < MAX_PAGES; read += 1) {
+                        const answer = await ids.call(source, kind, page);
+                        for (const id of answer.ids)
+                            listed.add(id);
+                        if (answer.nextPage === undefined)
+                            break;
+                        page = answer.nextPage;
+                    }
+                    for (const item of items)
+                        assert.ok(listed.has(item.externalId), `${kind} ${item.externalId} is missing from ids()`);
+                }
+            },
+        },
+    ];
+    return [
+        ...cases,
+        {
+            name: "changes: a dead cursor answers reset",
+            async run() {
+                const { source, deadCursor } = await make();
+                if (!deadCursor)
+                    return;
+                assert.deepEqual(await source.changes(deadCursor.kind, deadCursor.cursor), { reset: true });
+            },
+        },
+    ];
+};

package/dist/crm/testing/source.d.ts

@@ -0,0 +1,33 @@
+import type { CrmItem, CrmKind, CrmOrganization, CrmPerson, CrmPipeline, CrmRecords } from "../../domain/crm.js";
+import type { DealKind } from "../../domain/deals.js";
+import type { CrmSource, CrmSourceTraits } from "../source.js";
+export interface FakeCrmSourceOptions {
+    traits?: Partial<CrmSourceTraits>;
+    /** Rows per page of `changes()` and `ids()`; 2 when absent, so every list has several pages. */
+    pageSize?: number;
+}
+/** A CRM held in memory, with a change feed: what the contracts sync against, and what a CLI's tests may use. */
+export interface FakeCrmSource extends CrmSource {
+    /** Adds or changes a row; it is in the next `changes()`. */
+    put<K extends CrmKind>(kind: K, record: CrmRecords[K]): void;
+    /** Deletes a row: named in `removed` when `removedInChanges`, otherwise only missing from `ids()`. */
+    delete(kind: CrmKind, externalId: string): void;
+    setPipelines(kind: DealKind, pipelines: CrmPipeline[]): void;
+    /** The kind's cursors older than its latest change are refused, once, with `{ reset: true }`. */
+    expireCursors(kind: CrmKind): void;
+    /** Lists no id at all, as a CRM does for a sign-in that lost its rights. */
+    hideAll(hidden: boolean): void;
+    /** Requests made, by method. */
+    readonly calls: {
+        pipelines: number;
+        changes: number;
+        ids: number;
+    };
+}
+export declare const SALES_PIPELINE: CrmPipeline;
+export declare const LEAD_PIPELINE: CrmPipeline;
+export declare const fakeCrmSource: (options?: FakeCrmSourceOptions) => FakeCrmSource;
+export declare const exampleDeal: (externalId: string, extra?: Partial<CrmItem>) => CrmItem;
+export declare const exampleLead: (externalId: string, extra?: Partial<CrmItem>) => CrmItem;
+export declare const examplePerson: (externalId: string, extra?: Partial<CrmPerson>) => CrmPerson;
+export declare const exampleOrganization: (externalId: string, extra?: Partial<CrmOrganization>) => CrmOrganization;

package/dist/crm/testing/source.js

@@ -0,0 +1,126 @@
+/** 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 = {
+    externalId: "deal-1",
+    name: "Example sales",
+    stages: [
+        { externalId: "new", name: "New", position: 1, outcome: "open" },
+        { externalId: "quote", name: "Quote sent", position: 2, outcome: "open" },
+        { externalId: "won", name: "Won", position: 3, outcome: "won" },
+        { externalId: "lost", name: "Lost", position: 4, outcome: "lost" },
+    ],
+};
+export const LEAD_PIPELINE = {
+    externalId: "lead-1",
+    name: "Example leads",
+    stages: [
+        { externalId: "lead-new", name: "New", position: 1, outcome: "open" },
+        { externalId: "lead-good", name: "Converted", position: 2, outcome: "won" },
+        { externalId: "lead-junk", name: "Junk", position: 3, outcome: "lost" },
+    ],
+};
+export const fakeCrmSource = (options = {}) => {
+    const traits = {
+        kinds: ["organization", "person", "deal", "lead"],
+        removedInChanges: false,
+        ...options.traits,
+    };
+    const size = options.pageSize ?? 2;
+    const rows = new Map();
+    const pipelines = { deal: [SALES_PIPELINE], lead: [LEAD_PIPELINE] };
+    let version = 0;
+    const expired = new Map();
+    let hidden = false;
+    const calls = { pipelines: 0, changes: 0, ids: 0 };
+    const of = (kind) => {
+        const held = rows.get(kind) ?? new Map();
+        rows.set(kind, held);
+        return held;
+    };
+    const window = (list, page) => {
+        const at = page === undefined ? 0 : Number(page);
+        const next = at + size;
+        return { slice: list.slice(at, next), nextPage: next < list.length ? String(next) : undefined };
+    };
+    return {
+        provider: "example-crm",
+        traits,
+        calls,
+        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.
+            const stamped = (kind === "deal" || kind === "lead") && record.updatedAt == null
+                ? { ...record, updatedAt: STAMPED_FROM + version * 1000 }
+                : record;
+            of(kind).set(record.externalId, { record: stamped, version, deleted: false });
+        },
+        delete(kind, externalId) {
+            const held = of(kind).get(externalId);
+            if (!held)
+                return;
+            version += 1;
+            of(kind).set(externalId, { ...held, version, deleted: true });
+        },
+        setPipelines(kind, list) {
+            pipelines[kind] = list;
+        },
+        expireCursors(kind) {
+            expired.set(kind, version);
+        },
+        hideAll(value) {
+            hidden = value;
+        },
+        async pipelines(kind) {
+            calls.pipelines += 1;
+            return pipelines[kind];
+        },
+        async changes(kind, cursor, page) {
+            calls.changes += 1;
+            const since = cursor === null ? null : Number(cursor);
+            if (since !== null && since < (expired.get(kind) ?? 0)) {
+                expired.delete(kind);
+                return { reset: true };
+            }
+            const changed = [...of(kind).entries()]
+                .filter(([, held]) => (since === null ? !held.deleted : held.version > since))
+                .filter(([, held]) => !held.deleted || traits.removedInChanges)
+                .sort(([, a], [, b]) => a.version - b.version);
+            const { slice, nextPage } = window(changed, page);
+            return {
+                items: slice.filter(([, held]) => !held.deleted).map(([, held]) => held.record),
+                ...(traits.removedInChanges ? { removed: slice.filter(([, held]) => held.deleted).map(([id]) => id) } : {}),
+                ...(nextPage === undefined ? { cursor: String(version) } : { nextPage }),
+            };
+        },
+        async ids(kind, page) {
+            calls.ids += 1;
+            const listed = hidden ? [] : [...of(kind).entries()].filter(([, held]) => !held.deleted).map(([id]) => id);
+            const { slice, nextPage } = window(listed, page);
+            return { ids: slice, ...(nextPage === undefined ? {} : { nextPage }) };
+        },
+    };
+};
+export const exampleDeal = (externalId, extra = {}) => ({
+    externalId,
+    title: `Example deal ${externalId}`,
+    pipeline: SALES_PIPELINE.externalId,
+    stage: "new",
+    ...extra,
+});
+export const exampleLead = (externalId, extra = {}) => ({
+    externalId,
+    title: `Example lead ${externalId}`,
+    pipeline: LEAD_PIPELINE.externalId,
+    stage: "lead-new",
+    ...extra,
+});
+export const examplePerson = (externalId, extra = {}) => ({
+    externalId,
+    name: `Example person ${externalId}`,
+    ...extra,
+});
+export const exampleOrganization = (externalId, extra = {}) => ({
+    externalId,
+    name: `Example company ${externalId}`,
+    ...extra,
+});

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

@@ -0,0 +1,13 @@
+import type { ContractCase } from "../../meetings/index.js";
+import type { MessageStore } from "../../store/store.js";
+import type { AccountKey } from "../../store/types.js";
+import type { CrmSourceTraits } from "../source.js";
+/** A fresh, empty store and the CRM account to sync into it. */
+export interface CrmSyncFixture {
+    store: MessageStore;
+    account: AccountKey;
+}
+/** Both ways a CRM may report deletions: the engine must handle each. */
+export declare const CRM_TRAIT_COMBINATIONS: readonly Pick<CrmSourceTraits, "removedInChanges">[];
+/** What the sync engine does over any store, whatever the CRM: core runs it, and a CLI may run it over its store. */
+export declare const crmSyncContract: (make: () => CrmSyncFixture | Promise<CrmSyncFixture>) => ContractCase[];