@wirecat/cli-core 0.596.0 → 0.598.0

package/dist/cli/preview.d.ts

@@ -13,6 +13,7 @@ export declare const preview: (command: Command, settings: Pick<Settings, "permi
         also?: {
             key: PermissionKey;
             level: string;
+            when?: string;
         }[];
     } | undefined;
     validation: {
@@ -49,6 +50,7 @@ export declare const previewBody: (command: Command, permission: {
     also?: {
         key: PermissionKey;
         level: string;
+        when?: string;
     }[];
 } | undefined, messenger: boolean) => {
     preview: boolean;
@@ -59,6 +61,7 @@ export declare const previewBody: (command: Command, permission: {
         also?: {
             key: PermissionKey;
             level: string;
+            when?: string;
         }[];
     } | undefined;
     validation: {

package/dist/cli/preview.js

@@ -23,11 +23,15 @@ export const preview = (command, settings, tool, keys, messenger = true) => {
         (!declared && key !== null && key !== undefined && WRITE_KEYS.includes(key));
     if (level === "deny" || (writes && level === "readonly"))
         throw new CliError("permission_error", `this profile does not permit ${path.join(" ")}`, { permission: key });
-    const also = (declared?.alsoChecks?.(path) ?? []).map((one) => ({
-        key: one,
-        level: levelFor(permissions, one, declared?.defaults).level,
-    }));
-    const stopped = also.find((one) => one.level === "deny" || (writes && one.level === "readonly"));
+    const also = (declared?.alsoChecks?.(path) ?? []).map((one) => {
+        const key = typeof one === "string" ? one : one.key;
+        return {
+            key,
+            level: levelFor(permissions, key, declared?.defaults).level,
+            ...(typeof one === "string" ? {} : { when: one.when }),
+        };
+    });
+    const stopped = also.find((one) => one.when === undefined && (one.level === "deny" || (writes && one.level === "readonly")));
     if (stopped)
         throw new CliError("permission_error", `this profile does not permit ${stopped.key}`, { permission: stopped.key });
     return previewBody(command, { key: key ?? null, level, ...(also.length ? { also } : {}) }, messenger);

package/dist/cli/program.js

@@ -228,6 +228,9 @@ const runOnce = async (argv, definition, options) => {
         commandSignal: control.signal,
         trackCloseable: control.trackCloseable,
         app: definition.app,
+        // `settingsFor`'s, which every CLI passes; the definition's type is looser only so a test can stub it.
+        resolveSettings: (definition.configuration ?? settingsFor(definition.app))
+            .resolveSettings,
         ...(definition.rows ? { rows: definition.rows } : {}),
         platform: options.platform ?? process.platform,
         exit,

package/dist/crm/cli/index.js

@@ -3,11 +3,11 @@ import { annotate, metaOf, sharedCommand } from "@wirecat/cli-base/commands";
 import { Argument, InvalidArgumentError } from "commander";
 import * as v from "valibot";
 import { answerEntity } from "../../cli/answer-entity.js";
-import { environmentOf, outputFor, runBudgetOf } from "../../cli/context.js";
+import { environmentOf, inCommandRun, outputFor, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
 import { FETCH, LOCAL_READ, NO_EFFECTS, REMOTE_WRITE } from "../../cli/effects.js";
-import { itemOf, listOf, renderAnswer, snakeKeys } from "../../cli/envelope.js";
-import { queryTerms, termField, withQuery } from "../../cli/list-query.js";
+import { itemOf, listOf, renderAnswer, snakeKeys, snakeKeysKeeping } from "../../cli/envelope.js";
+import { queryTerms, termField, unfilteredQuery, withQuery } from "../../cli/list-query.js";
 import { terminalAsker } from "../../cli/messenger/ask.js";
 import { lineOf } from "../../cli/steps.js";
 import { CRM_KINDS } from "../../domain/crm.js";
@@ -41,7 +41,15 @@ export const STAGES_QUERY = {
     ],
 };
 /** A CRM's users typed these; a list item names its own, as `events list` does. */
-const DEAL_UNTRUSTED = ["title", "summary", "stage", "pipeline_name", "organization.name", "people.name"];
+const DEAL_UNTRUSTED = [
+    "title",
+    "summary",
+    "stage",
+    "pipeline_name",
+    "organization.name",
+    "people.name",
+    "provider_metadata",
+];
 const PIPELINE_UNTRUSTED = ["name", "stages.name"];
 const STAGE_UNTRUSTED = ["name", "pipeline_name"];
 const crmSync = v.strictObject({
@@ -92,18 +100,36 @@ const crmWrite = v.strictObject({
     lead: v.optional(dealEntity),
     untrusted: v.array(text),
 });
+/** b24's `fields list` answer, so a CRM CLI's own command can go; `untrusted` names what the CRM's users typed. */
+const crmField = v.strictObject({
+    code: v.string(),
+    label: v.nullable(v.string()),
+    type: v.string(),
+    multiple: v.boolean(),
+    filterable: v.boolean(),
+    options: v.optional(v.array(v.strictObject({ id: v.string(), label: v.string() }))),
+    untrusted: v.array(text),
+});
+const FIELDS_QUERY = unfilteredQuery("crm_field", crmField);
+const FIELD_UNTRUSTED = ["label", "options.label"];
+/** The words `fields list` takes: its sibling commands' nouns. */
+const FIELD_KINDS = {
+    deals: "deal",
+    leads: "lead",
+    people: "person",
+    organizations: "organization",
+};
 const crmRemoval = v.strictObject({ operation_id: text, ref: text, removed: count });
 const collect = (value, previous = []) => {
     if (value.indexOf("=") < 1)
-        throw new InvalidArgumentError("expected code=value");
+        throw new InvalidArgumentError("expected key=value");
     return [...previous, value];
 };
-/** `--field code=value` pairs; an empty value clears the field. */
-const customOf = (pairs) => Object.fromEntries(pairs.map((pair) => {
+/** `--field` as typed, split at the first `=`. */
+const pairsOf = (typed) => typed.map((pair) => {
     const at = pair.indexOf("=");
-    const given = pair.slice(at + 1);
-    return [pair.slice(0, at), given === "" ? null : given];
-}));
+    return [pair.slice(0, at), pair.slice(at + 1)];
+});
 const integer = (most) => (value) => {
     if (!/^[1-9]\d*$/.test(value) || Number(value) > most)
         throw new InvalidArgumentError(`expected 1 to ${most}`);
@@ -111,10 +137,12 @@ const integer = (most) => (value) => {
 };
 /** The words below the program, as `page.next` and `sync`'s next step run it again. */
 const pathOf = (command) => command.parent?.parent ? [...pathOf(command.parent), command.name()] : [command.name()];
-const marked = (items, untrusted) => items.map((item) => ({ ...snakeKeys(item), untrusted }));
+/** A CRM's own field codes are its keys, never ours to rename. */
+const dealKeys = snakeKeysKeeping(["providerMetadata"]);
+const marked = (items, untrusted) => items.map((item) => ({ ...dealKeys(item), untrusted }));
 const addCrmCommandsDefinition = (program, options) => {
     const now = () => options.now?.() ?? Date.now();
-    const within = async (command, work) => {
+    const within = (command, work) => inCommandRun(command, async () => {
         const run = await options.open(command, { readOnly: metaOf(command).effects?.local !== "write" });
         let body;
         try {
@@ -124,7 +152,7 @@ const addCrmCommandsDefinition = (program, options) => {
             await run.close?.();
         }
         renderAnswer(command, outputFor(command), body);
-    };
+    });
     const example = (command, ...lines) => annotate(command, { examples: lines.map((line) => `${options.app.command} work ${line}`) });
     example(answerEntity(annotate(program.command("sync"), { effects: FETCH, offline: false, cooperative: true, partial: true }), "crm_sync", crmSync).description("bring the CRM's copy in the local store up to date: pipelines, companies, contacts, deals and leads that " +
         "changed since the last sync, or everything with --rescan; a run stops before its deadline or --max-pages " +
@@ -237,7 +265,7 @@ const addCrmCommandsDefinition = (program, options) => {
             .argument("<ref>", `${kind}:<id>, as a list shows it`), `${plural} show ${kind}:12`).action(async (reference, _opts, command) => {
             await within(command, async (run) => {
                 const found = await ownCopy(run, kind, reference);
-                return itemOf({ ...snakeKeys(found), untrusted: DEAL_UNTRUSTED });
+                return itemOf({ ...dealKeys(found), untrusted: DEAL_UNTRUSTED });
             });
         });
         addWrites(group, kind);
@@ -272,7 +300,7 @@ const addCrmCommandsDefinition = (program, options) => {
         };
         const answered = (operationId, item) => itemOf({
             operation_id: operationId,
-            [kind]: { ...snakeKeys(item), untrusted: DEAL_UNTRUSTED },
+            [kind]: { ...dealKeys(item), untrusted: DEAL_UNTRUSTED },
             untrusted: DEAL_UNTRUSTED.map((field) => `${kind}.${field}`),
         });
         const write = (name, verb, description) => {
@@ -292,12 +320,14 @@ const addCrmCommandsDefinition = (program, options) => {
             .option("--currency <code>", "an ISO 4217 code, such as EUR")
             .option("--close-date <date>", "the day it is expected to close, YYYY-MM-DD")
             .option("--owner <user>", "the CRM user it is assigned to; anyone but the sign-in's own user checks crm.assign-others")
-            .option("--field <key=value>", "one of the CRM's own fields, by its code; repeat for more, empty clears it", collect, 
+            .option("--field <key=value>", "one of the CRM's own fields, by its code or label as `fields list` prints them, and its value; a list " +
+            "field takes its option's label or id; repeat it for more fields, or for each value of a multiple field; " +
+            "an empty value clears it", collect, 
         // The empty default marks the flag as repeatable, so an agent's tool takes a list.
         []);
         const inputOf = ({ field, operationId: _id, ...rest }) => ({
             ...Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined)),
-            ...(field?.length ? { custom: customOf(field) } : {}),
+            ...(field?.length ? { custom: pairsOf(field) } : {}),
         });
         const idOf = (opts) => opts.operationId === undefined ? {} : { operationId: opts.operationId };
         const run = (command, work) => within(command, (opened) => work(contextOf(opened, command)));
@@ -408,6 +438,35 @@ const addCrmCommandsDefinition = (program, options) => {
             });
         });
     });
+    const fieldKinds = Object.keys(FIELD_KINDS).filter((word) => word !== "leads" || options.leads !== false);
+    const fields = annotate(program.command("fields"), { effects: NO_EFFECTS }).description("the CRM's own fields on deals, leads, people and organizations, as last synced");
+    example(withQuery(answerEntity(annotate(fields.command("list"), { effects: LOCAL_READ }), "crm_field", crmField)
+        .description("the CRM's custom fields of one kind, in its order, with a list field's options")
+        .argument("<kind>", fieldKinds.join(", "))
+        .option("--limit <n>", `fields per page, 1–${MOST}`, integer(MOST), 50)
+        // No default: the run's settings refuse --all beside a --page, given or defaulted.
+        .option("--page <n>", "which page, starting at 1", integer(1_000_000))
+        .option("--all", "every field, no paging"), FIELDS_QUERY), "fields list deals", "fields list people --json").action(async (kind, words, opts, command) => {
+        if (!fieldKinds.includes(kind))
+            throw new CliError("validation_error", `fields are listed for ${fieldKinds.join(", ")}; got ${kind}`, {
+                reason: "field.unknown-kind",
+                allowed: fieldKinds,
+            });
+        queryTerms(words, FIELDS_QUERY, "fields list");
+        await within(command, async (run) => {
+            const found = await run.store.crm.fields(run.account, FIELD_KINDS[kind]);
+            const page = opts.page ?? 1;
+            const offset = opts.all ? 0 : (page - 1) * opts.limit;
+            const end = opts.all ? found.length : offset + opts.limit;
+            return listOf(pathOf(command).join(" "), {
+                items: found.slice(offset, end).map((field) => ({ ...field, untrusted: FIELD_UNTRUSTED })),
+                limit: opts.all ? Math.max(1, found.length) : opts.limit,
+                page,
+                has_more: found.length > end,
+                ...(words.length ? { args: { query: words } } : {}),
+            });
+        });
+    });
     const search = program.commands.find((one) => one.name() === "search") ??
         annotate(program.command("search"), { effects: NO_EFFECTS }).description("search what the local store holds");
     addCrmSearchAll(search, { within, app: options.app, example });

package/dist/crm/index.d.ts

@@ -1,4 +1,4 @@
 export type { CrmChanges, CrmIdPage, CrmPage, CrmSource, CrmSourceTraits } from "./source.js";
 export { type CrmCursor, type CrmSyncIssue, type CrmSyncOptions, type CrmSyncReport, type CrmSyncResult, crmStatus, cursorName, parseCrmCursor, syncCrm, } from "./sync.js";
-export { CRM_ASSIGN_OTHERS_KEY, CRM_VERBS, CRM_WRITE_DEFAULTS, CRM_WRITE_KEYS, type CrmDraft, type CrmFields, type CrmVerb, type CrmWriteCapabilities, type CrmWriteOptions, type CrmWriter, } from "./writer.js";
+export { CRM_ASSIGN_OTHERS_KEY, CRM_VERBS, CRM_WRITE_DEFAULTS, CRM_WRITE_KEYS, type CrmDraft, type CrmFields, type CrmVerb, type CrmWriteCapabilities, type CrmWriteOptions, type CrmWriter, crmAlsoChecks, } from "./writer.js";
 export { type CrmFieldsInput, type CrmWriteContext, type CrmWrites, type CrmWritten, closeCrmItem, createCrmItem, moveCrmItem, removeCrmItem, updateCrmItem, } from "./writes.js";

package/dist/crm/index.js

@@ -1,3 +1,3 @@
 export { crmStatus, cursorName, parseCrmCursor, syncCrm, } from "./sync.js";
-export { CRM_ASSIGN_OTHERS_KEY, CRM_VERBS, CRM_WRITE_DEFAULTS, CRM_WRITE_KEYS, } from "./writer.js";
+export { CRM_ASSIGN_OTHERS_KEY, CRM_VERBS, CRM_WRITE_DEFAULTS, CRM_WRITE_KEYS, crmAlsoChecks, } from "./writer.js";
 export { closeCrmItem, createCrmItem, moveCrmItem, removeCrmItem, updateCrmItem, } from "./writes.js";

package/dist/crm/source.d.ts

@@ -1,4 +1,4 @@
-import type { CrmKind, CrmPipeline, CrmRecords } from "../domain/crm.js";
+import type { CrmField, CrmKind, CrmPipeline, CrmRecords } from "../domain/crm.js";
 import type { DealKind } from "../domain/deals.js";
 export interface CrmSourceTraits {
     /** What this CRM has: one without leads leaves `lead` out. Contacts and companies come before the items on them. */
@@ -38,6 +38,11 @@ export interface CrmSource {
      * reads by its own modified time, with an overlap, and gives that time back as the cursor.
      */
     changes<K extends CrmKind>(kind: K, cursor: string | null, page?: string): Promise<CrmChanges<CrmRecords[K]>>;
+    /**
+     * The CRM's own fields on one kind, in its order: what the codes in a row's `metadata` mean. Read every sync; a CRM
+     * without custom fields leaves it out, and one that has none on a kind answers `[]`.
+     */
+    fields?(kind: CrmKind): Promise<CrmField[]>;
     /** Every id the CRM holds of the kind, a page at a time: how deletions are found when `removedInChanges` is false. */
     ids?(kind: CrmKind, page?: string): Promise<CrmIdPage>;
 }

package/dist/crm/sync.d.ts

@@ -87,10 +87,11 @@ export interface CrmSyncReport {
     hint?: string;
 }
 /**
- * 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`.
+ * Brings one CRM account's copy up to date: both kinds' pipelines and each kind's fields, 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 declare const syncCrm: (source: CrmSource, store: MessageStore, account: AccountKey, options?: CrmSyncOptions) => Promise<CrmSyncReport>;
 /** Each kind's sync in the WC-LIFE-14 shape: `cursor_age_ms` growing on a `partial` one means nothing moves it. */

package/dist/crm/sync.js

@@ -57,6 +57,16 @@ const readPipelines = async (run, kind) => {
         run.report.issues.push({ kind, ...one });
     return null;
 };
+const readFields = async (run, kind) => {
+    const why = run.budget.take();
+    if (why)
+        return why;
+    const fields = await run.source.fields.call(run.source, kind);
+    const { skipped } = await run.store.crm.saveFields(run.account, kind, fields);
+    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;
@@ -185,10 +195,11 @@ const syncKind = async (run, kind, options, result) => {
     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`.
+ * Brings one CRM account's copy up to date: both kinds' pipelines and each kind's fields, 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();
@@ -225,6 +236,13 @@ export const syncCrm = async (source, store, account, options = {}) => {
             if (options.signal?.aborted)
                 stopped = "cancelled";
         }
+    if (run.source.fields)
+        for (const kind of kinds)
+            if (!stopped) {
+                stopped = await readFields(run, kind);
+                if (options.signal?.aborted)
+                    stopped = "cancelled";
+            }
     for (const kind of kinds) {
         const result = {
             kind,

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

@@ -1,4 +1,4 @@
-export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, type FakeCrmSource, type FakeCrmSourceOptions, type FakeCrmWrite, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, type FakeCrmSource, type FakeCrmSourceOptions, type FakeCrmWrite, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, SOURCE_FIELD, } from "./source.js";
 export { type CrmSourceFixture, crmSourceContract } from "./source-contract.js";
 export { CRM_TRAIT_COMBINATIONS, type CrmSyncFixture, crmSyncContract } from "./sync-contract.js";
 export { type CrmWriteFixture, crmWriteContract } from "./write-contract.js";

package/dist/crm/testing/index.js

@@ -1,4 +1,4 @@
-export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, SOURCE_FIELD, } from "./source.js";
 export { crmSourceContract } from "./source-contract.js";
 export { CRM_TRAIT_COMBINATIONS, crmSyncContract } from "./sync-contract.js";
 export { crmWriteContract } from "./write-contract.js";

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

@@ -51,6 +51,34 @@ export const crmSourceContract = (make) => {
                 }
             },
         },
+        {
+            name: "fields: unique codes in each kind, a type, yes-or-no flags, and a list field's options with unique ids",
+            async run() {
+                const { source } = await make();
+                if (!source.fields)
+                    return;
+                for (const kind of source.traits.kinds) {
+                    const fields = await source.fields(kind);
+                    assert.ok(Array.isArray(fields), `${kind}: fields() answers a list`);
+                    const codes = new Set();
+                    for (const field of fields) {
+                        assert.ok(typeof field.code === "string" && field.code.trim(), `${kind}: a field has a code`);
+                        assert.ok(!codes.has(field.code), `${kind} field ${field.code} is listed twice`);
+                        codes.add(field.code);
+                        assert.ok(field.label === null || typeof field.label === "string", `${field.code}: a label or null`);
+                        assert.ok(typeof field.type === "string" && field.type.trim(), `${field.code} has a type`);
+                        assert.equal(typeof field.multiple, "boolean", `${field.code}: multiple is true or false`);
+                        assert.equal(typeof field.filterable, "boolean", `${field.code}: filterable is true or false`);
+                        if (field.options === undefined)
+                            continue;
+                        const ids = new Set(field.options.map(({ id }) => id));
+                        assert.equal(ids.size, field.options.length, `${field.code}: option ids are unique`);
+                        for (const option of field.options)
+                            assert.ok(typeof option.id === "string" && typeof option.label === "string", `${field.code}'s options`);
+                    }
+                }
+            },
+        },
         {
             name: "changes: a full list pages to its end, every item stands in a listed stage, fields in the neutral shape",
             async run() {

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

@@ -1,4 +1,4 @@
-import type { CrmItem, CrmKind, CrmOrganization, CrmPerson, CrmPipeline, CrmRecords } from "../../domain/crm.js";
+import type { CrmField, CrmItem, CrmKind, CrmOrganization, CrmPerson, CrmPipeline, CrmRecords } from "../../domain/crm.js";
 import type { DealKind } from "../../domain/deals.js";
 import type { CrmSource, CrmSourceTraits } from "../source.js";
 import { type CrmVerb, type CrmWriteCapabilities, type CrmWriter } from "../writer.js";
@@ -27,15 +27,20 @@ export interface FakeCrmSource extends CrmSource, CrmWriter {
     /** 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 own fields from the next `fields()` on: deals have `SOURCE_FIELD` and the rest none until set. */
+    setFields(kind: CrmKind, fields: CrmField[]): 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;
     /** The next write is carried out and its answer lost: it throws `outcome_unknown`. */
     loseNextAnswer(): void;
+    /** The next write is carried out and its item cannot be read back: it throws with `sent: true`. */
+    failNextReadBack(): void;
     /** Requests made, by method. */
     readonly calls: {
         pipelines: number;
+        fields: number;
         changes: number;
         ids: number;
     };
@@ -45,6 +50,8 @@ export interface FakeCrmSource extends CrmSource, CrmWriter {
 /** Custom codes the fake refuses: each is a neutral field under another name. */
 export declare const FAKE_CRM_ALIASES: string[];
 export declare const SALES_PIPELINE: CrmPipeline;
+/** A deal's list field, as a CRM lists one: what the fake's deals have. */
+export declare const SOURCE_FIELD: CrmField;
 export declare const LEAD_PIPELINE: CrmPipeline;
 export declare const fakeCrmSource: (options?: FakeCrmSourceOptions) => FakeCrmSource;
 export declare const exampleDeal: (externalId: string, extra?: Partial<CrmItem>) => CrmItem;

package/dist/crm/testing/source.js

@@ -14,6 +14,18 @@ export const SALES_PIPELINE = {
         { externalId: "lost", name: "Lost", position: 4, outcome: "lost" },
     ],
 };
+/** A deal's list field, as a CRM lists one: what the fake's deals have. */
+export const SOURCE_FIELD = {
+    code: "UF_SOURCE",
+    label: "Source",
+    type: "enumeration",
+    multiple: false,
+    filterable: true,
+    options: [
+        { id: "1", label: "Website" },
+        { id: "2", label: "Fair" },
+    ],
+};
 export const LEAD_PIPELINE = {
     externalId: "lead-1",
     name: "Example leads",
@@ -32,10 +44,11 @@ export const fakeCrmSource = (options = {}) => {
     const size = options.pageSize ?? 2;
     const rows = new Map();
     const pipelines = { deal: [SALES_PIPELINE], lead: [LEAD_PIPELINE] };
+    const fields = { deal: [SOURCE_FIELD], lead: [], person: [], organization: [] };
     let version = 0;
     const expired = new Map();
     let hidden = false;
-    const calls = { pipelines: 0, changes: 0, ids: 0 };
+    const calls = { pipelines: 0, fields: 0, changes: 0, ids: 0 };
     const capabilities = {
         kinds: ["deal", "lead"],
         verbs: CRM_VERBS,
@@ -46,6 +59,7 @@ export const fakeCrmSource = (options = {}) => {
     const answered = new Map();
     let made = 0;
     let lose = false;
+    let unread = false;
     const of = (kind) => {
         const held = rows.get(kind) ?? new Map();
         rows.set(kind, held);
@@ -69,18 +83,32 @@ export const fakeCrmSource = (options = {}) => {
             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 } } : {}),
+    /** A custom value as a CRM answers it: by code, with the field's label and a list option's label. */
+    const customValue = (kind, code, value) => {
+        const field = fields[kind].find((one) => one.code === code);
+        const label = (id) => field?.options?.find((option) => option.id === id)?.label ?? id;
+        if (!field?.options)
+            return { label: field?.label ?? null, value };
+        return {
+            label: field.label,
+            value: Array.isArray(value) ? value.map(label) : label(value),
+            option_id: value,
         };
+    };
+    const applied = (kind, item, given) => {
+        const { custom, owner, pipeline, stage, ...named } = given;
+        const metadata = { ...item.metadata };
+        for (const [code, value] of Object.entries(custom ?? {}))
+            if (value === null)
+                delete metadata[code];
+            else
+                metadata[code] = customValue(kind, code, value);
         return {
             ...item,
             ...Object.fromEntries(Object.entries(named).filter(([, value]) => value !== undefined)),
             ...(pipeline === undefined ? {} : { pipeline }),
             ...(stage === undefined ? {} : { stage }),
+            ...(owner === undefined ? {} : { assignee: owner }),
             metadata,
             updatedAt: null,
         };
@@ -102,6 +130,12 @@ export const fakeCrmSource = (options = {}) => {
             lose = false;
             throw new CliError("outcome_unknown", "the CRM did not answer");
         }
+        if (unread) {
+            unread = false;
+            throw new CliError("provider_error", `the CRM made the ${verb} but its ${kind} could not be read back`, {
+                sent: true,
+            });
+        }
         return done;
     };
     const saved = (kind, item) => {
@@ -117,13 +151,16 @@ export const fakeCrmSource = (options = {}) => {
         loseNextAnswer() {
             lose = true;
         },
+        failNextReadBack() {
+            unread = 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 }));
+                return saved(kind, applied(kind, blank, { ...draft, pipeline, stage }));
             });
         },
         async update(kind, externalId, patch, { operationId }) {
@@ -131,7 +168,7 @@ export const fakeCrmSource = (options = {}) => {
             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 }));
+                return saved(kind, applied(kind, item, { ...patch, ...at }));
             });
         },
         async move(kind, externalId, stage, { operationId }) {
@@ -179,6 +216,13 @@ export const fakeCrmSource = (options = {}) => {
         setPipelines(kind, list) {
             pipelines[kind] = list;
         },
+        setFields(kind, list) {
+            fields[kind] = list;
+        },
+        async fields(kind) {
+            calls.fields += 1;
+            return fields[kind];
+        },
         expireCursors(kind) {
             expired.set(kind, version);
         },

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

@@ -1,7 +1,7 @@
 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";
+import { exampleDeal, exampleLead, exampleOrganization, examplePerson, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, SOURCE_FIELD, } from "./source.js";
 /** Both ways a CRM may report deletions: the engine must handle each. */
 export const CRM_TRAIT_COMBINATIONS = [
     { removedInChanges: false },
@@ -68,7 +68,7 @@ export const crmSyncContract = (make) => CRM_TRAIT_COMBINATIONS.flatMap((traits)
             await sync();
             source.delete("deal", "d1");
             now += DAY;
-            const stopped = await sync({ budget: runBudget({ requests: 7 }) });
+            const stopped = await sync({ budget: runBudget({ requests: 11 }) });
             assert.equal(stopped.state, "partial");
             assert.equal(stopped.hint, "run sync again to continue");
             assert.deepEqual(await deals(), ["d1", "d2", "d3", "d4", "d5"]);
@@ -90,6 +90,17 @@ export const crmSyncContract = (make) => CRM_TRAIT_COMBINATIONS.flatMap((traits)
             await sync({ rescan: true });
             assert.deepEqual(await deals(), []);
         }),
+        test("stores each kind's own fields, and marks deleted one the CRM no longer lists", async ({ source, sync, store, account, }) => {
+            const note = { code: "UF_NOTE", label: "Note", type: "string", multiple: true, filterable: false };
+            source.setFields("person", [note]);
+            await sync();
+            assert.deepEqual(await store.crm.fields(account, "deal"), [SOURCE_FIELD]);
+            assert.deepEqual(await store.crm.fields(account, "person"), [note]);
+            source.setFields("deal", []);
+            await sync();
+            assert.deepEqual(await store.crm.fields(account, "deal"), []);
+            assert.deepEqual(await store.crm.fields(account, "person"), [note]);
+        }),
         test("a dead cursor starts a full round, marked reset", async ({ source, sync, deals }) => {
             seeded(source);
             await sync();
@@ -103,7 +114,7 @@ export const crmSyncContract = (make) => CRM_TRAIT_COMBINATIONS.flatMap((traits)
         }),
         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 }) });
+            const stopped = await sync({ budget: runBudget({ requests: 10 }) });
             assert.equal(stopped.state, "partial");
             assert.equal(stopped.stopped, "requests");
             const kept = (await deals()).length;

package/dist/crm/writer.d.ts

@@ -1,3 +1,4 @@
+import type { ConditionalKey } from "../cli/permission-keys.js";
 import type { CrmItem } from "../domain/crm.js";
 import type { DealKind, DealRole } from "../domain/deals.js";
 import type { Level, PermissionKey } from "../sends/permissions.js";
@@ -35,7 +36,8 @@ export interface CrmFields {
     }[];
     /** The CRM user it is assigned to: a user's id, never a contact's. */
     owner?: string | null;
-    custom?: Record<string, string | null>;
+    /** A list field's option by its id; a multiple field's values as a list; `null` clears it. */
+    custom?: Record<string, string | string[] | null>;
 }
 export type CrmDraft = CrmFields & {
     title: string;
@@ -47,7 +49,8 @@ export interface CrmWriteOptions {
 /**
  * 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`.
+ * throws `outcome_unknown`. A write the CRM made whose item could then not be read back throws with `sent: true` in
+ * its details: it is journaled as sent, and the read's failure is answered on its own.
  */
 export interface CrmWriter {
     readonly provider: string;
@@ -69,6 +72,12 @@ export interface CrmWriter {
 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[];
+/**
+ * Every key a CRM write command may check beyond its own path, for `commandPermissions({ alsoChecks })`, so its
+ * `--dry-run` names each: a stage implies the move key and a won or lost one the close key, an owner other than the
+ * sign-in's `crm.assign-others`, and `also` the CLI's own (the same `CrmWrites.alsoChecks` the real run checks).
+ */
+export declare const crmAlsoChecks: (also?: (kind: DealKind, verb: CrmVerb) => readonly PermissionKey[]) => (path: readonly string[]) => readonly (PermissionKey | ConditionalKey)[];
 /**
  * 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.