@wirecat/cli-core 0.590.0 → 0.592.0

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[];

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

@@ -0,0 +1,178 @@
+import assert from "node:assert/strict";
+import { runBudget } from "../../background/budget.js";
+import { syncCrm } from "../sync.js";
+import { exampleDeal, exampleLead, exampleOrganization, examplePerson, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+/** Both ways a CRM may report deletions: the engine must handle each. */
+export const CRM_TRAIT_COMBINATIONS = [
+    { removedInChanges: false },
+    { removedInChanges: true },
+];
+const DAY = 86_400_000;
+/** What the sync engine does over any store, whatever the CRM: core runs it, and a CLI may run it over its store. */
+export const crmSyncContract = (make) => CRM_TRAIT_COMBINATIONS.flatMap((traits) => {
+    const label = traits.removedInChanges ? "(deletions in changes)" : "(deletions by id pass)";
+    let now = Date.now();
+    const test = (name, check) => ({
+        name: `${name} ${label}`,
+        async run() {
+            now = Date.now();
+            const fixture = await make();
+            const source = fakeCrmSource({ traits });
+            const sync = (options = {}) => syncCrm(source, fixture.store, fixture.account, { now, ...options });
+            const deals = async () => (await fixture.store.deals.list({ account: fixture.account, kind: "deal" }))
+                .map(({ externalId }) => externalId)
+                .sort();
+            await check({ ...fixture, source, sync, deals });
+        },
+    });
+    const seeded = (source, count = 3) => {
+        for (let at = 1; at <= count; at += 1)
+            source.put("deal", exampleDeal(`d${at}`));
+    };
+    return [
+        test("copies every kind on the first run, and only what changed on the next", async ({ source, sync, deals, store, account, }) => {
+            source.put("organization", exampleOrganization("c1"));
+            source.put("person", examplePerson("p1"));
+            seeded(source);
+            source.put("lead", exampleLead("l1"));
+            const first = await sync();
+            assert.equal(first.state, "complete");
+            assert.deepEqual(await deals(), ["d1", "d2", "d3"]);
+            assert.equal((await store.deals.list({ account, kind: "lead" })).length, 1);
+            assert.ok(first.synced.every(({ round }) => round === "full"));
+            source.put("deal", exampleDeal("d2", { stage: "won", title: "Example deal won" }));
+            const second = await sync();
+            assert.deepEqual(second.synced.map(({ kind, round, saved }) => [kind, round, saved]), [
+                ["organization", "changes", 0],
+                ["person", "changes", 0],
+                ["deal", "changes", 1],
+                ["lead", "changes", 0],
+            ]);
+            const [won] = await store.deals.list({ account, status: "won" });
+            assert.equal(won?.title, "Example deal won");
+        }),
+        test("marks deleted what the CRM deleted, after a complete list at the latest", async ({ source, sync, deals, }) => {
+            seeded(source);
+            await sync();
+            source.delete("deal", "d2");
+            now += DAY;
+            const run = await sync();
+            assert.deepEqual(await deals(), ["d1", "d3"]);
+            const deal = run.synced.find(({ kind }) => kind === "deal");
+            assert.equal((deal?.removed ?? 0) + (deal?.unlisted ?? 0), 1);
+        }),
+        test("a list of ids the budget stops marks nothing, and the next run goes on from it", async ({ source, sync, deals, }) => {
+            if (traits.removedInChanges)
+                return;
+            seeded(source, 5);
+            await sync();
+            source.delete("deal", "d1");
+            now += DAY;
+            const stopped = await sync({ budget: runBudget({ requests: 7 }) });
+            assert.equal(stopped.state, "partial");
+            assert.equal(stopped.hint, "run sync again to continue");
+            assert.deepEqual(await deals(), ["d1", "d2", "d3", "d4", "d5"]);
+            const finished = await sync();
+            assert.equal(finished.state, "complete");
+            assert.deepEqual(await deals(), ["d2", "d3", "d4", "d5"]);
+        }),
+        test("a list that would mark most rows deleted is held as an issue until --rescan", async ({ source, sync, deals, }) => {
+            if (traits.removedInChanges)
+                return;
+            seeded(source, 12);
+            await sync();
+            source.hideAll(true);
+            now += DAY;
+            const held = await sync();
+            assert.equal(held.synced.find(({ kind }) => kind === "deal")?.pass, "held");
+            assert.ok(held.issues.some(({ reason }) => reason === "crm.unlisted-held"));
+            assert.equal((await deals()).length, 12);
+            await sync({ rescan: true });
+            assert.deepEqual(await deals(), []);
+        }),
+        test("a dead cursor starts a full round, marked reset", async ({ source, sync, deals }) => {
+            seeded(source);
+            await sync();
+            source.put("deal", exampleDeal("d4"));
+            source.expireCursors("deal");
+            const run = await sync();
+            const deal = run.synced.find(({ kind }) => kind === "deal");
+            assert.equal(deal?.reset, true);
+            assert.equal(deal?.round, "full");
+            assert.deepEqual(await deals(), ["d1", "d2", "d3", "d4"]);
+        }),
+        test("a run its budget stops saves its pages and the next goes on from the page it stopped at", async ({ source, sync, deals, }) => {
+            seeded(source, 9);
+            const stopped = await sync({ budget: runBudget({ requests: 6 }) });
+            assert.equal(stopped.state, "partial");
+            assert.equal(stopped.stopped, "requests");
+            const kept = (await deals()).length;
+            assert.ok(kept > 0 && kept < 9, `some pages kept, not all: ${kept}`);
+            const finished = await sync();
+            assert.equal(finished.state, "complete");
+            assert.equal((await deals()).length, 9);
+            assert.equal(finished.synced.find(({ kind }) => kind === "deal")?.saved, 9 - kept, "it went on, not from the start");
+        }),
+        test("an item in a stage made after the pipelines were read is kept once they are read again", async ({ source, sync, deals, }) => {
+            const changes = source.changes.bind(source);
+            source.changes = async (kind, cursor, page) => {
+                if (kind === "deal") {
+                    source.setPipelines("deal", [
+                        {
+                            ...SALES_PIPELINE,
+                            stages: [...SALES_PIPELINE.stages, { externalId: "late", name: "Late", position: 5, outcome: "open" }],
+                        },
+                    ]);
+                    source.put("deal", exampleDeal("d1", { stage: "late" }));
+                }
+                return changes(kind, cursor, page);
+            };
+            const run = await sync();
+            assert.deepEqual(await deals(), ["d1"]);
+            assert.deepEqual(run.issues, []);
+        }),
+        test("an item in a stage the CRM never lists is named as an issue, and the round goes on", async ({ source, sync, deals, }) => {
+            source.put("deal", exampleDeal("d1", { stage: "nowhere" }));
+            source.put("deal", exampleDeal("d2"));
+            const run = await sync();
+            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, }) => {
+            source.setPipelines("lead", [{ ...LEAD_PIPELINE, externalId: SALES_PIPELINE.externalId }]);
+            source.put("deal", exampleDeal("d1"));
+            const run = await sync();
+            assert.deepEqual(await deals(), ["d1"]);
+            assert.ok(run.issues.some(({ kind, reason }) => kind === "lead" && reason === "crm.pipeline-clash"));
+        }),
+        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" });
+            source.put("organization", exampleOrganization("c1"));
+            source.put("person", examplePerson("p1", { email: "person@example.com" }));
+            source.put("deal", exampleDeal("d1", { organization: "c1", people: [{ externalId: "p1", role: "contact" }] }));
+            await sync();
+            const [deal] = await store.deals.list({ account });
+            assert.notEqual(deal?.organization?.ref, own.ref);
+            assert.equal(deal?.organization?.name, "Example company c1");
+            const person = await store.people.personOf({ provider: "email", id: "person@example.com" });
+            assert.equal(deal?.people[0]?.ref, `person:${person?.uid}`);
+        }),
+        test("a cancelled run stops and keeps what it saved", async ({ source, sync, deals }) => {
+            seeded(source, 4);
+            const controller = new AbortController();
+            const pipelines = source.pipelines.bind(source);
+            source.pipelines = async (kind) => {
+                if (kind === "lead")
+                    controller.abort();
+                return pipelines(kind);
+            };
+            const run = await sync({ signal: controller.signal });
+            assert.equal(run.stopped, "cancelled");
+            assert.equal(run.state, "partial");
+            assert.deepEqual(await deals(), []);
+            const again = await sync();
+            assert.equal(again.state, "complete");
+            assert.equal((await deals()).length, 4);
+        }),
+    ];
+});

package/dist/domain/crm.d.ts

@@ -0,0 +1,82 @@
+import type { DealKind, DealRole, DealStatus, StageOutcome } from "./deals.js";
+/** What a CRM holds that the store copies: its deals and leads, and the contacts and companies on them. */
+export declare const CRM_KINDS: readonly ["organization", "person", "deal", "lead"];
+export type CrmKind = (typeof CRM_KINDS)[number];
+/** One stage of a CRM pipeline, as the CRM orders and marks it. */
+export interface CrmStage {
+    /** Unique in its pipeline. */
+    externalId: string;
+    name: string;
+    /** Any numbers; the store keeps the order they give. */
+    position: number;
+    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.
+     */
+    externalId: string;
+    name: string;
+    stages: CrmStage[];
+}
+/** A deal or a lead as the CRM has it. Every reference is the CRM's own id; the store resolves them. */
+export interface CrmItem {
+    externalId: string;
+    title: string;
+    pipeline: string;
+    stage: string;
+    /**
+     * Whether it is still open, won or lost, where the CRM keeps that on the item (Pipedrive's `status`); left out, the
+     * stage's outcome says it.
+     */
+    status?: DealStatus | null;
+    /** A decimal string in `currency`; both or neither. */
+    amount?: string | null;
+    /** ISO 4217. */
+    currency?: string | null;
+    /** `YYYY-MM-DD`: when it is expected to close. */
+    closeDate?: string | null;
+    /** `YYYY-MM-DD`: when it was won or lost. */
+    closedDate?: string | null;
+    /** A company's id. */
+    organization?: string | null;
+    /** Contacts on it, by their id, and the part each plays. */
+    people?: {
+        externalId: string;
+        role: DealRole;
+    }[];
+    /** A lead's: the deal it became. */
+    deal?: string | null;
+    /** Epoch milliseconds, as the CRM gives them; the stage history counts from these. */
+    createdAt?: number | null;
+    updatedAt?: number | null;
+    /** The CRM's own page for it, http or https. */
+    url?: string | null;
+    /** What the CRM sends that has no column, such as custom fields with their labels; never a secret. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A CRM contact: it becomes an identity of the CRM's provider, `<account>/contact/<id>`, joined to a person by exact
+ * email only. A CRM user, such as a deal's owner, is not a contact: its ids are another sequence (`<account>/user/<id>`).
+ */
+export interface CrmPerson {
+    externalId: string;
+    name: string | null;
+    email?: string | null;
+    phone?: string | null;
+}
+/** A CRM company: it becomes an organization of its own, never one matched by name. */
+export interface CrmOrganization {
+    externalId: string;
+    name: string;
+    url?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface CrmRecords {
+    deal: CrmItem;
+    lead: CrmItem;
+    person: CrmPerson;
+    organization: CrmOrganization;
+}
+export declare const isItemKind: (kind: CrmKind) => kind is DealKind;

package/dist/domain/crm.js

@@ -0,0 +1,3 @@
+/** What a CRM holds that the store copies: its deals and leads, and the contacts and companies on them. */
+export const CRM_KINDS = ["organization", "person", "deal", "lead"];
+export const isItemKind = (kind) => kind === "deal" || kind === "lead";

package/dist/entities/deal.d.ts

@@ -0,0 +1,159 @@
+import * as v from "valibot";
+/**
+ * A deal (`deal:<id>`), the owner's own or a CRM's copy: one shape for memo and every CRM CLI. Money is a decimal
+ * string in its currency, both `null` when no amount is expected.
+ */
+export declare const deal: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly kind: v.PicklistSchema<["deal", "lead"], undefined>;
+    readonly title: v.StringSchema<undefined>;
+    /** One line with the stage, amount and status. */
+    readonly summary: v.StringSchema<undefined>;
+    readonly pipeline: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly pipeline_name: v.StringSchema<undefined>;
+    readonly stage: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["open", "won", "lost"], undefined>;
+    readonly organization: v.NullableSchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+        readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly owner: v.BooleanSchema<undefined>;
+    }, undefined>, undefined>;
+    readonly currency: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly amount: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly close_date: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+    readonly closed_date: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+    readonly closed_reason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly rank: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** A lead's deal, once it became one. */
+    readonly deal: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+    /** The CRM account it is a copy from; `null` for the owner's own. */
+    readonly account: v.NullableSchema<v.StrictObjectSchema<{
+        readonly provider: v.StringSchema<undefined>;
+        readonly account: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+    readonly external_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly people: v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+        readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly owner: v.BooleanSchema<undefined>;
+        readonly role: v.PicklistSchema<["owner", "contact", "decision-maker"], undefined>;
+    }, undefined>, undefined>;
+    readonly author: v.StrictObjectSchema<{
+        readonly type: v.PicklistSchema<["person", "bot"], undefined>;
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly kind: v.NullableSchema<v.PicklistSchema<["agent", "rule"], undefined>, undefined>;
+    }, undefined>;
+    readonly model: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly source: v.StringSchema<undefined>;
+    readonly reason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly evidence: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+    readonly project: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+    readonly project_name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly updated_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+/** A lead (`lead:<id>`): a deal's shape, in a lead pipeline. */
+export declare const lead: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly kind: v.PicklistSchema<["deal", "lead"], undefined>;
+    readonly title: v.StringSchema<undefined>;
+    /** One line with the stage, amount and status. */
+    readonly summary: v.StringSchema<undefined>;
+    readonly pipeline: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly pipeline_name: v.StringSchema<undefined>;
+    readonly stage: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["open", "won", "lost"], undefined>;
+    readonly organization: v.NullableSchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+        readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly owner: v.BooleanSchema<undefined>;
+    }, undefined>, undefined>;
+    readonly currency: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly amount: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly close_date: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+    readonly closed_date: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+    readonly closed_reason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly rank: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** A lead's deal, once it became one. */
+    readonly deal: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+    /** The CRM account it is a copy from; `null` for the owner's own. */
+    readonly account: v.NullableSchema<v.StrictObjectSchema<{
+        readonly provider: v.StringSchema<undefined>;
+        readonly account: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+    readonly external_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly people: v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+        readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly owner: v.BooleanSchema<undefined>;
+        readonly role: v.PicklistSchema<["owner", "contact", "decision-maker"], undefined>;
+    }, undefined>, undefined>;
+    readonly author: v.StrictObjectSchema<{
+        readonly type: v.PicklistSchema<["person", "bot"], undefined>;
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly kind: v.NullableSchema<v.PicklistSchema<["agent", "rule"], undefined>, undefined>;
+    }, undefined>;
+    readonly model: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly source: v.StringSchema<undefined>;
+    readonly reason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly evidence: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+    readonly project: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+    readonly project_name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly updated_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+/** A pipeline (`pipeline:<id>`) with its stages in order; `pipelines show` adds the funnel. */
+export declare const pipeline: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly name: v.StringSchema<undefined>;
+    readonly kind: v.PicklistSchema<["deal", "lead"], undefined>;
+    readonly account: v.NullableSchema<v.StrictObjectSchema<{
+        readonly provider: v.StringSchema<undefined>;
+        readonly account: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+    readonly external_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly stages: v.ArraySchema<v.StrictObjectSchema<{
+        readonly name: v.StringSchema<undefined>;
+        readonly position: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly outcome: v.PicklistSchema<["open", "won", "lost"], undefined>;
+        readonly external_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Open deals or leads in it now. */
+        readonly open: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        /** With a funnel: rows that got this far, and the share of them that reached the next stage. */
+        readonly reached: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly conversion: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly totals: v.OptionalSchema<v.StrictObjectSchema<{
+        readonly items: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly open: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly won: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly lost: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly win_rate: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly since: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>, undefined>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+/** One stage of a pipeline, with the pipeline it is in: what `stages list` answers. */
+export declare const stage: v.StrictObjectSchema<{
+    readonly name: v.StringSchema<undefined>;
+    readonly position: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly outcome: v.PicklistSchema<["open", "won", "lost"], undefined>;
+    readonly external_id: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Open deals or leads in it now. */
+    readonly open: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    /** With a funnel: rows that got this far, and the share of them that reached the next stage. */
+    readonly reached: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly conversion: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+    readonly pipeline: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+    readonly pipeline_name: v.StringSchema<undefined>;
+    readonly kind: v.PicklistSchema<["deal", "lead"], undefined>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;

package/dist/entities/deal.js

@@ -0,0 +1,86 @@
+import * as v from "valibot";
+import { count, id, reference, text, time, untrusted } from "./fields.js";
+const nullableText = v.nullable(text);
+const party = v.strictObject({ ref: reference, name: nullableText, owner: v.boolean() });
+const outcome = v.picklist(["open", "won", "lost"]);
+const crmAccount = v.nullable(v.strictObject({ provider: text, account: text }));
+const day = v.nullable(v.pipe(v.string(), v.regex(/^\d{4}-\d{2}-\d{2}$/)));
+/**
+ * A deal (`deal:<id>`), the owner's own or a CRM's copy: one shape for memo and every CRM CLI. Money is a decimal
+ * string in its currency, both `null` when no amount is expected.
+ */
+export const deal = v.strictObject({
+    id,
+    ref: reference,
+    kind: v.picklist(["deal", "lead"]),
+    title: text,
+    /** One line with the stage, amount and status. */
+    summary: text,
+    pipeline: reference,
+    pipeline_name: text,
+    stage: text,
+    status: outcome,
+    organization: v.nullable(party),
+    currency: nullableText,
+    amount: nullableText,
+    close_date: day,
+    closed_date: day,
+    closed_reason: nullableText,
+    rank: v.nullable(v.number()),
+    /** A lead's deal, once it became one. */
+    deal: v.nullable(reference),
+    /** The CRM account it is a copy from; `null` for the owner's own. */
+    account: crmAccount,
+    external_id: nullableText,
+    people: v.array(v.strictObject({ ...party.entries, role: v.picklist(["owner", "contact", "decision-maker"]) })),
+    author: v.strictObject({
+        type: v.picklist(["person", "bot"]),
+        id,
+        name: nullableText,
+        kind: v.nullable(v.picklist(["agent", "rule"])),
+    }),
+    model: nullableText,
+    source: text,
+    reason: nullableText,
+    evidence: v.array(reference),
+    project: v.nullable(reference),
+    project_name: nullableText,
+    created_at: time,
+    updated_at: time,
+    untrusted,
+});
+/** A lead (`lead:<id>`): a deal's shape, in a lead pipeline. */
+export const lead = deal;
+const pipelineStage = v.strictObject({
+    name: text,
+    position: count,
+    outcome,
+    external_id: nullableText,
+    /** Open deals or leads in it now. */
+    open: count,
+    /** With a funnel: rows that got this far, and the share of them that reached the next stage. */
+    reached: v.optional(count),
+    conversion: v.optional(v.nullable(v.number())),
+});
+/** A pipeline (`pipeline:<id>`) with its stages in order; `pipelines show` adds the funnel. */
+export const pipeline = v.strictObject({
+    id,
+    ref: reference,
+    name: text,
+    kind: v.picklist(["deal", "lead"]),
+    account: crmAccount,
+    external_id: nullableText,
+    stages: v.array(pipelineStage),
+    created_at: time,
+    totals: v.optional(v.strictObject({ items: count, open: count, won: count, lost: count, win_rate: v.nullable(v.number()) })),
+    since: v.optional(day),
+    untrusted,
+});
+/** One stage of a pipeline, with the pipeline it is in: what `stages list` answers. */
+export const stage = v.strictObject({
+    ...pipelineStage.entries,
+    pipeline: reference,
+    pipeline_name: text,
+    kind: v.picklist(["deal", "lead"]),
+    untrusted,
+});