conduyt 1.60.0 → 1.61.0

package/README.md

@@ -34,8 +34,13 @@ conduyt whoami                          # show the authenticated user
 conduyt contacts list --limit 25        # list contacts (supports --cursor, --query)
 conduyt contacts get <id>               # fetch one contact
 conduyt deals list --pipeline <id>      # list deals
+conduyt deals list --health-summary --pipeline <id>   # Pipeline health strip for the filtered set (totalOpenDeals, atRiskValue, checks[]); add --health-check stale --health-limit 20 for one check's deals, --health-cursor <nextCursor> to page, --health-rows-only for just the page
+conduyt deals health --pipeline <id> --check needs_action   # GET /deals/inspection: the six checks over open deals; --check adds its deals, --cursor/--offset pages
+conduyt deals card-fields set value,contact,custom:next_contact_at   # the kanban card fields (1-8, built-ins or custom:<fieldKey>); `card-fields get` reads them
+conduyt pipelines stage-rules set <pipelineId> <stageId> --required-fields contactId,custom:loan_amount --required-documents 2   # what a deal needs to enter the stage; other stages untouched; `stage-rules get [pipelineId] [stageId]` reads
 conduyt deals bulk-update --file updates.json   # update up to 100 deals at once ([{id, stageId, value, ...}]); per-item results, exit 1 if any failed
 conduyt pipelines                       # list pipelines and stages
+conduyt pipelines update <id> --automation-only true   # only automations, API keys and owners / admins move or edit its cards (owner / admin key)
 conduyt search "acme corp"              # search across the CRM
 conduyt insights summary                # run an AI insight query
 conduyt insights saved_report --report "Lead Activity" --period last_7_days   # run any saved report as a tool

package/dist/board-settings.js

@@ -0,0 +1,88 @@
+/**
+ * Deal board settings (app 10-08, BDA board): per-stage rules (settings.pipelineStageRules[pipelineId][stageId]) and the
+ * kanban card fields (settings.dealCardFields). The validators mirror the API's settingsPatchSchema entries, the source
+ * of truth: the built-in names are the app's lists, `custom:<fieldKey>` names one of the account's DEAL custom fields
+ * (the API checks it exists at save), and the stage rule object is strict (no other keys).
+ */
+export const DEAL_STAGE_REQUIRED_FIELDS = ["value", "expectedCloseDate", "contactId", "assignedTo", "lostReason"];
+export const DEAL_CARD_FIELDS = ["value", "contact", "phones", "company", "owner", "priority", "expectedCloseDate", "daysInStage", "nextAction", "tags", "stageHealth", "source"];
+export const MAX_DEAL_CARD_FIELDS = 8;
+export const MAX_STAGE_REQUIRED_FIELDS = 25;
+export const MAX_STAGE_REQUIRED_DOCUMENTS = 20;
+export const MAX_LOST_REASON_OPTIONS = 50;
+const CUSTOM_FIELD_RE = /^custom:[a-zA-Z_][a-zA-Z0-9_]*$/;
+export const RULE_KEYS = ["requiredFields", "requiredDocuments", "lostReasonLabel", "lostReasonOptions"];
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** "a,b,custom:x" → ["a","b","custom:x"]; blank items are dropped, an all-blank value is an empty list */
+export function splitList(raw) {
+    return raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
+}
+export function validateRequiredFields(v, flag = "requiredFields") {
+    if (!Array.isArray(v))
+        throw new Error(`${flag} must be a list.`);
+    if (v.length > MAX_STAGE_REQUIRED_FIELDS)
+        throw new Error(`${flag} takes at most ${MAX_STAGE_REQUIRED_FIELDS} entries (got ${v.length}).`);
+    for (const f of v) {
+        if (typeof f !== "string" || !(DEAL_STAGE_REQUIRED_FIELDS.includes(f) || CUSTOM_FIELD_RE.test(f))) {
+            throw new Error(`${flag}: "${String(f)}" is not allowed. Use ${DEAL_STAGE_REQUIRED_FIELDS.join(", ")} or custom:<deal custom field key>.`);
+        }
+    }
+    return v;
+}
+export function validateCardFields(v, flag = "fields") {
+    if (!Array.isArray(v))
+        throw new Error(`${flag} must be a list.`);
+    if (v.length < 1)
+        throw new Error(`${flag} needs at least one field.`);
+    if (v.length > MAX_DEAL_CARD_FIELDS)
+        throw new Error(`${flag} takes at most ${MAX_DEAL_CARD_FIELDS} fields (got ${v.length}).`);
+    for (const f of v) {
+        if (typeof f !== "string" || !(DEAL_CARD_FIELDS.includes(f) || CUSTOM_FIELD_RE.test(f))) {
+            throw new Error(`${flag}: "${String(f)}" is not allowed. Use ${DEAL_CARD_FIELDS.join(", ")} or custom:<deal custom field key>.`);
+        }
+    }
+    return v;
+}
+/** The fields of one stage rule the caller gave, each validated like the API does. Unknown keys are refused (the rule is strict). */
+export function validateRuleChange(raw) {
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (!RULE_KEYS.includes(k))
+            throw new Error(`Unknown stage rule field "${k}". A stage rule takes ${RULE_KEYS.join(", ")}.`);
+        if (v === undefined)
+            continue;
+        if (k === "requiredFields")
+            out[k] = validateRequiredFields(v);
+        else if (k === "requiredDocuments") {
+            if (typeof v !== "number" || !Number.isInteger(v) || v < 0 || v > MAX_STAGE_REQUIRED_DOCUMENTS)
+                throw new Error(`requiredDocuments must be an integer 0-${MAX_STAGE_REQUIRED_DOCUMENTS}.`);
+            out[k] = v;
+        }
+        else if (k === "lostReasonLabel") {
+            const t = typeof v === "string" ? v.trim() : "";
+            if (t.length < 1 || t.length > 60)
+                throw new Error("lostReasonLabel must be 1-60 characters.");
+            out[k] = t;
+        }
+        else {
+            if (!Array.isArray(v) || v.some((o) => typeof o !== "string"))
+                throw new Error("lostReasonOptions must be a list of strings.");
+            if (v.length > MAX_LOST_REASON_OPTIONS)
+                throw new Error(`lostReasonOptions takes at most ${MAX_LOST_REASON_OPTIONS} entries.`);
+            out[k] = v;
+        }
+    }
+    return out;
+}
+/**
+ * The PATCH body that sets ONE stage's rule. The API merges settings.pipelineStageRules per pipeline and replaces that
+ * pipeline's stage map, so the body carries the pipeline's whole stage map with only this stage's rule changed (the given
+ * fields over the stored ones); every other pipeline is left out and therefore untouched.
+ */
+export function stageRulePatch(settings, pipelineId, stageId, change) {
+    const rules = isObj(settings.pipelineStageRules) ? settings.pipelineStageRules : {};
+    const stages = isObj(rules[pipelineId]) ? rules[pipelineId] : {};
+    const current = isObj(stages[stageId]) ? stages[stageId] : {};
+    const kept = Object.fromEntries(RULE_KEYS.filter((k) => current[k] !== undefined).map((k) => [k, current[k]]));
+    return { pipelineStageRules: { [pipelineId]: { ...stages, [stageId]: { ...kept, ...change } } } };
+}

package/dist/index.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { Command } from "commander";
 import { ConduytClient, buildQuery } from "./client.js";
+import { splitList, stageRulePatch, validateCardFields, validateRuleChange } from "./board-settings.js";
 import { saveConfig, resolveConfig, configPath } from "./config.js";
 import { print, fail, unwrap } from "./output.js";
 // Exit cleanly when a downstream pipe closes early (e.g. `conduyt deals list |
@@ -299,6 +300,18 @@ contacts
     };
 }));
 const deals = program.command("deals").description("Manage deals");
+/** A flag that was given but is blank (an empty shell variable) is a mistake, never "no filter": widening the read to every
+ *  pipeline or dropping the check silently would answer a different question. --cursor / --health-cursor are the exception:
+ *  a blank cursor is forwarded so the API answers health_cursor_blank. */
+function rejectBlankFlags(flags) {
+    for (const [flag, val] of flags) {
+        if (val !== undefined && val.trim() === "") {
+            throw new Error(`${flag} was provided but is blank. Omit it, or pass a real value.`);
+        }
+    }
+}
+/** The six Pipeline health checks (GET /deals health_check, GET /deals/inspection check); the API validates the value. */
+const PIPELINE_HEALTH_CHECKS = ["high_value_idle", "stale", "unassigned", "needs_action", "missing_close_date", "missing_contact"];
 deals
     .command("list")
     .description("List deals")
@@ -309,6 +322,12 @@ deals
     .option("--pipeline-name <name>", "filter by pipeline name (resolved server-side; errors if not found — never returns the whole account)")
     .option("--stage <id>", "filter by stage UUID")
     .option("--stage-name <name>", "filter by stage name (requires --pipeline or --pipeline-name)")
+    .option("--health-summary", "answer the Pipeline health of the filtered set instead of the deal list: totalOpenDeals, atRiskValue, checks[] (six checks, ordered by money at risk), deals. Each deal row also carries hasNextStep and nextAppointmentAt (null unless your key can view the calendar)")
+    .option("--health-check <check>", `with --health-summary: add this check's deals, highest value first (${PIPELINE_HEALTH_CHECKS.join(" | ")})`)
+    .option("--health-limit <n>", "with --health-summary and --health-check: deals per page, 1-100 (default 5)")
+    .option("--health-offset <n>", "with --health-summary and --health-check: deals to skip (default 0); prefer --health-cursor")
+    .option("--health-cursor <token>", "with --health-summary and --health-check: continue after this cursor, the nextCursor of the previous page, passed back UNCHANGED (opaque signed token; a blank, forged or foreign one is a 400 with health_cursor_blank / health_cursor_invalid / health_cursor_context / health_cursor_needs_check)")
+    .option("--health-rows-only", "with --health-summary and --health-check: answer only that page of the check's deals ({check, offset, items, hasMore, nextCursor}), without the summary")
     .action(run(async (client, opts) => {
     // A provided-but-blank filter must error, not silently become "no filter":
     // buildQuery drops empty strings, so a blank flag would never reach the
@@ -326,6 +345,48 @@ deals
             throw new Error(`${flag} was provided but is blank. Omit it to skip the filter, or pass a real value.`);
         }
     }
+    // Pipeline health (app 10-08): a different answer shape (no data.data / meta.total), so it never goes through the
+    // --all / truncation logic below. The API validates the check, the paging and the cursor (400 + code).
+    const healthFlags = [
+        ["--health-check", opts.healthCheck], ["--health-limit", opts.healthLimit], ["--health-offset", opts.healthOffset],
+        ["--health-cursor", opts.healthCursor], ["--health-rows-only", opts.healthRowsOnly],
+    ];
+    if (opts.healthSummary || healthFlags.some(([, v]) => v !== undefined)) {
+        rejectBlankFlags([["--health-check", opts.healthCheck], ["--health-limit", opts.healthLimit], ["--health-offset", opts.healthOffset]]);
+        if (!opts.healthSummary) {
+            throw new Error(`${healthFlags.find(([, v]) => v !== undefined)[0]} needs --health-summary.`);
+        }
+        if (opts.all || opts.limit !== undefined || opts.page !== undefined) {
+            throw new Error("--health-summary answers the Pipeline health, not the deal list: drop --all / --limit / --page (page a check's deals with --health-limit and --health-cursor).");
+        }
+        const usp = new URLSearchParams();
+        for (const [k, v] of Object.entries({ pipeline: opts.pipeline, pipeline_name: opts.pipelineName, stage: opts.stage, stage_name: opts.stageName })) {
+            if (v !== undefined)
+                usp.set(k, v);
+        }
+        usp.set("health_summary", "true");
+        if (opts.healthCheck !== undefined)
+            usp.set("health_check", opts.healthCheck);
+        if (opts.healthLimit !== undefined)
+            usp.set("health_limit", opts.healthLimit);
+        if (opts.healthOffset !== undefined)
+            usp.set("health_offset", opts.healthOffset);
+        // sent as given, even when blank, so the API answers health_cursor_blank instead of the flag vanishing
+        if (opts.healthCursor !== undefined)
+            usp.set("health_cursor", opts.healthCursor);
+        if (opts.healthRowsOnly)
+            usp.set("health_rows_only", "true");
+        const answer = await client.get(`/api/v1/deals?${usp.toString()}`);
+        // the live rows-only answer is { data: { deals: page } }: print the page itself, as the help promises
+        if (opts.healthRowsOnly) {
+            const page = answer?.data?.deals;
+            if (page === undefined || page === null || typeof page !== "object") {
+                throw new Error("--health-rows-only: the API answered without the page (data.deals). Aborting rather than print another shape.");
+            }
+            return { data: page };
+        }
+        return answer;
+    }
     const MAX_PER_PAGE = 1000; // matches the server's per_page cap
     const parsePos = (v, name) => {
         if (v === undefined)
@@ -425,6 +486,64 @@ deals
     }
     return res;
 }));
+deals
+    .command("health")
+    .description(`Pipeline health for one pipeline (or every visible active pipeline) over its open deals (GET /deals/inspection): totalOpenDeals, atRiskValue, checks[] (${PIPELINE_HEALTH_CHECKS.join(", ")}; ordered by money at risk), deals (null without --check), summary, labels. With --check, deals is that check's page {check, offset, items, hasMore, nextCursor, total}, highest value first. For the board's other filters use \`deals list --health-summary\``)
+    .option("--pipeline <id>", "pipeline UUID; omit for every visible active pipeline")
+    .option("--check <check>", `adds that check's deals (${PIPELINE_HEALTH_CHECKS.join(" | ")})`)
+    .option("--limit <n>", "with --check: deals per page, 1-100 (default 5)")
+    .option("--offset <n>", "with --check: deals to skip (default 0); not combined with --cursor")
+    .option("--cursor <token>", "with --check: continue after this cursor, the nextCursor of the previous page, passed back UNCHANGED (opaque signed token; 400 health_cursor_invalid / health_cursor_context / health_cursor_blank / health_cursor_needs_check)")
+    .action(run(async (client, opts) => {
+    rejectBlankFlags([["--pipeline", opts.pipeline], ["--check", opts.check], ["--limit", opts.limit], ["--offset", opts.offset]]);
+    const usp = new URLSearchParams();
+    if (opts.pipeline !== undefined)
+        usp.set("pipeline", opts.pipeline);
+    if (opts.check !== undefined)
+        usp.set("check", opts.check);
+    if (opts.limit !== undefined)
+        usp.set("limit", opts.limit);
+    if (opts.offset !== undefined)
+        usp.set("offset", opts.offset);
+    // sent as given, even when blank, so the API answers health_cursor_blank
+    if (opts.cursor !== undefined)
+        usp.set("cursor", opts.cursor);
+    const qs = usp.toString();
+    return client.get(`/api/v1/deals/inspection${qs ? `?${qs}` : ""}`);
+}));
+// (BDA board 10-08) settings.dealCardFields: the fields on each kanban deal card, in order
+const cardFields = deals
+    .command("card-fields")
+    .description("The fields shown on each kanban deal card, in order (settings.dealCardFields, max 8)");
+cardFields
+    .command("get")
+    .description("Read the card fields: built-ins (value, contact, phones, company, owner, priority, expectedCloseDate, daysInStage, nextAction, tags, stageHealth, source) and custom:<fieldKey> entries")
+    .action(run(async (client) => {
+    const res = (await client.get("/api/v1/settings"));
+    return { data: { dealCardFields: res?.data?.dealCardFields ?? null } };
+}));
+cardFields
+    .command("set [fields]")
+    .description("REPLACE the card fields (admin key, settings:edit): a comma-separated list of 1 to 8, each a built-in (value, contact, phones, company, owner, priority, expectedCloseDate, daysInStage, nextAction, tags, stageHealth, source) or custom:<deal custom field key>, e.g. `value,contact,custom:next_contact_at`. Or pass the list as a JSON array with --json")
+    .option("--json <json>", "the complete list as a JSON array, e.g. '[\"value\",\"custom:next_contact_at\"]' (instead of the positional list)")
+    .action(run(async (client, fields, opts) => {
+    if ((fields === undefined) === (opts.json === undefined))
+        throw new Error("Pass the fields as a comma-separated list or as --json '[...]', not both and not neither.");
+    let list;
+    if (opts.json !== undefined) {
+        try {
+            list = JSON.parse(opts.json);
+        }
+        catch {
+            throw new Error("--json must be valid JSON.");
+        }
+    }
+    else {
+        list = splitList(fields);
+    }
+    const dealCardFields = validateCardFields(list);
+    return patchGeneralSettingsMerged(client, () => ({ dealCardFields }));
+}));
 deals
     .command("create")
     .description("Create a deal (use `pipelines list` to get pipeline/stage ids)")
@@ -675,6 +794,110 @@ pipelines
     assertStagesShape(body.stages);
     return client.post("/api/v1/pipelines", body);
 }));
+// (BDA board 10-08) PATCH /pipelines/:id: name, description, isDefault, sortOrder and automationOnly (owner / admin key)
+pipelines
+    .command("update <id>")
+    .description("Update a pipeline (PATCH: only the fields you pass change). --automation-only true makes it an automation-only pipeline: its cards are moved and edited only by automations, API keys and owners / admins, a member's edit is refused with 403 pipeline_automation_only (owner / admin key only; `pipelines list` shows the flag)")
+    .option("--name <name>", "pipeline name")
+    .option("--description <text>", "pipeline description")
+    .option("--is-default <bool>", "true|false: the account's default pipeline")
+    .option("--automation-only <bool>", "true|false: only automations, API keys and owners / admins move or edit its cards")
+    .option("--sort-order <n>", "position among the pipelines (integer)")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    assertUuid(id, "pipeline id");
+    const flag = (raw, name) => {
+        if (raw === undefined)
+            return undefined;
+        const v = raw.trim().toLowerCase();
+        if (v === "true")
+            return true;
+        if (v === "false")
+            return false;
+        throw new Error(`${name} must be true or false.`);
+    };
+    // --json is parsed FIRST and wins: a flag is read (and validated) only when the JSON does not carry its key, so
+    // --json can override a flag whose value would not have parsed
+    const fromJson = opts.json !== undefined ? jsonArg(opts.json, "--json") : {};
+    const body = {};
+    const unlessJson = (key) => !Object.prototype.hasOwnProperty.call(fromJson, key);
+    if (opts.name !== undefined && unlessJson("name"))
+        body.name = opts.name;
+    if (opts.description !== undefined && unlessJson("description"))
+        body.description = opts.description;
+    if (unlessJson("isDefault")) {
+        const isDefault = flag(opts.isDefault, "--is-default");
+        if (isDefault !== undefined)
+            body.isDefault = isDefault;
+    }
+    if (unlessJson("automationOnly")) {
+        const automationOnly = flag(opts.automationOnly, "--automation-only");
+        if (automationOnly !== undefined)
+            body.automationOnly = automationOnly;
+    }
+    if (opts.sortOrder !== undefined && unlessJson("sortOrder")) {
+        const n = Number(opts.sortOrder.trim());
+        if (opts.sortOrder.trim() === "" || !Number.isInteger(n))
+            throw new Error("--sort-order must be an integer.");
+        body.sortOrder = n;
+    }
+    Object.assign(body, fromJson);
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    return client.patch(`/api/v1/pipelines/${encodeURIComponent(id)}`, body);
+}));
+// (BDA board 10-08) settings.pipelineStageRules: what a deal needs before it may enter a stage. Read-merge-write with the
+// settings revision (a 409 is re-read and retried once); other stages and pipelines are untouched.
+const stageRules = pipelines
+    .command("stage-rules")
+    .description("Per-stage rules (settings.pipelineStageRules): the fields and documents a deal needs before it may enter a stage");
+stageRules
+    .command("get [pipelineId] [stageId]")
+    .description("Read the stage rules as { pipelineId: { stageId: { requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions } } }, for everything, one pipeline, or one stage")
+    .action(run(async (client, pipelineId, stageId) => {
+    if (pipelineId !== undefined)
+        assertUuid(pipelineId, "pipeline id");
+    if (stageId !== undefined) {
+        if (pipelineId === undefined)
+            throw new Error("stage id needs a pipeline id.");
+        assertUuid(stageId, "stage id");
+    }
+    const res = (await client.get("/api/v1/settings"));
+    const all = res?.data?.pipelineStageRules && typeof res.data.pipelineStageRules === "object" ? res.data.pipelineStageRules : {};
+    if (pipelineId === undefined)
+        return { data: all };
+    const stages = all[pipelineId] ?? {};
+    return { data: { [pipelineId]: stageId === undefined ? stages : stages[stageId] !== undefined ? { [stageId]: stages[stageId] } : {} } };
+}));
+stageRules
+    .command("set <pipelineId> <stageId>")
+    .description("Set ONE stage's rule (admin key, settings:edit). Only the fields you pass change; they are merged into the stage's current rule. --required-fields REPLACES the list (max 25: value, expectedCloseDate, contactId, assignedTo, lostReason, or custom:<deal custom field key>; an empty value clears it). --required-documents is how many documents must be attached before a deal may enter the stage (integer 0-20)")
+    .option("--required-fields <list>", "comma-separated, e.g. contactId,custom:next_contact_at (empty clears)")
+    .option("--required-documents <n>", "integer 0-20")
+    .option("--lost-reason-label <text>", "label of the stage's lost-reason prompt (1-60 chars)")
+    .option("--lost-reason-options <list>", "comma-separated dropdown options of the lost-reason prompt (max 50; empty clears)")
+    .option("--json <json>", "the rule fields as a JSON object ({requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions}), merged over the flags")
+    .action(run(async (client, pipelineId, stageId, opts) => {
+    assertUuid(pipelineId, "pipeline id");
+    assertUuid(stageId, "stage id");
+    const raw = {};
+    if (opts.requiredFields !== undefined)
+        raw.requiredFields = splitList(opts.requiredFields);
+    if (opts.requiredDocuments !== undefined) {
+        const t = opts.requiredDocuments.trim();
+        raw.requiredDocuments = t === "" ? NaN : Number(t);
+    }
+    if (opts.lostReasonLabel !== undefined)
+        raw.lostReasonLabel = opts.lostReasonLabel;
+    if (opts.lostReasonOptions !== undefined)
+        raw.lostReasonOptions = splitList(opts.lostReasonOptions);
+    if (opts.json !== undefined)
+        Object.assign(raw, jsonArg(opts.json, "--json"));
+    const change = validateRuleChange(raw);
+    if (Object.keys(change).length === 0)
+        throw new Error("Nothing to set. Pass --required-fields, --required-documents, --lost-reason-label, --lost-reason-options or --json.");
+    return patchGeneralSettingsMerged(client, (settings) => stageRulePatch(settings, pipelineId, stageId, change));
+}));
 // (system stages 2026-09-24) tri-surface parity: the stage flags the API takes on PATCH /pipelines/:id/stages/:stageId,
 // isSystem included (a system holding stage automations route deals through; hidden from rep pickers, never won or lost)
 pipelines
@@ -1519,13 +1742,13 @@ automations
 }));
 automations
     .command("validate")
-    .description("Validate a workflow graph before saving. Provide the body via --json or --file (needs triggerEvent + graph)")
+    .description("Validate a workflow graph before saving. Provide the body via --json or --file (needs triggerEvent + graph). A delay node waits for a fixed duration by default; waitType \"until_field_date\" (with fieldKey = a deal DATE / DATETIME custom field key and offsetHours = signed hours added to its date, default 0, e.g. 24 = a day after it) waits until that date stored on the deal, re-read at every wake (an empty or past value continues immediately).")
     .option("--json <json>", "full request body as JSON")
     .option("--file <path>", "read the request body from a JSON file")
     .action(run(async (client, opts) => client.post("/api/v1/automations/validate", bodyFromJsonOrFile(opts))));
 automations
     .command("import")
-    .description("Create a workflow (with optional name resolution). Provide the body via --json or --file (needs name + triggerEvent + graph). A sequence step is the action enroll_in_sequence with config {sequenceId, enrollAction: add (default) | remove}; add needs the sequence to allow automation enrollment")
+    .description("Create a workflow (with optional name resolution). Provide the body via --json or --file (needs name + triggerEvent + graph). A sequence step is the action enroll_in_sequence with config {sequenceId, enrollAction: add (default) | remove}; add needs the sequence to allow automation enrollment. A delay node waits for a fixed duration by default; waitType \"until_field_date\" (with fieldKey = a deal DATE / DATETIME custom field key and offsetHours = signed hours added to its date, default 0, e.g. 24 = a day after it) waits until that date stored on the deal, re-read at every wake (an empty or past value continues immediately).")
     .option("--json <json>", "full request body as JSON")
     .option("--file <path>", "read the request body from a JSON file")
     .option("--resolve-names", "set resolveNames=true so name fields in node configs are converted to ids")
@@ -3035,12 +3258,17 @@ replyCapture
 // (400 expected_settings_revision_required) and answers 409 when another save landed first. Every general
 // write below reads the revision first and sends it; a 409 is re-raised with the current settings so the
 // caller re-derives the change instead of overwriting a newer save.
+// the ONE place a general-settings PATCH is sent: it always carries the revision it was derived from (lifecycle-guards.test.ts
+// pins this single call site and that both helpers hand it their revision)
+function patchSettingsWithRevision(client, body, expectedSettingsRevision) {
+    return client.patch("/api/v1/settings", { ...body, ...(expectedSettingsRevision ? { expectedSettingsRevision } : {}) });
+}
 async function patchGeneralSettings(client, body) {
     const read = async () => (await client.get("/api/v1/settings"));
     const before = await read();
     const expectedSettingsRevision = typeof before?.data?.settingsRevision === "string" ? before.data.settingsRevision : null;
     try {
-        return await client.patch("/api/v1/settings", { ...body, ...(expectedSettingsRevision ? { expectedSettingsRevision } : {}) });
+        return await patchSettingsWithRevision(client, body, expectedSettingsRevision);
     }
     catch (err) {
         if (err instanceof Error && /^Conduyt API 409/.test(err.message)) {
@@ -3050,6 +3278,30 @@ async function patchGeneralSettings(client, body) {
         throw err;
     }
 }
+// read-merge-write for a change that depends on what is stored (a per-stage rule): `build` derives the PATCH body from the
+// settings just read and the save carries that read's settingsRevision. A 409 (another save landed first) re-reads and
+// re-derives ONCE; a second 409 is re-raised with the current settings, like patchGeneralSettings.
+async function patchGeneralSettingsMerged(client, build) {
+    const read = async () => (await client.get("/api/v1/settings"));
+    let revision = null;
+    for (let attempt = 0;; attempt += 1) {
+        const before = await read();
+        const settings = before?.data ?? {};
+        revision = typeof settings.settingsRevision === "string" ? settings.settingsRevision : null;
+        const body = build(settings);
+        try {
+            return await patchSettingsWithRevision(client, body, revision);
+        }
+        catch (err) {
+            if (!(err instanceof Error && /^Conduyt API 409/.test(err.message)))
+                throw err;
+            if (attempt === 1) {
+                const current = await read();
+                throw new Error(`${err.message} — the account settings changed twice while this was being saved (last revision read ${revision ?? "?"}); re-run the command (current: ${JSON.stringify(current?.data ?? null).slice(0, 1500)})`);
+            }
+        }
+    }
+}
 function poolFilterOf(settings) {
     const raw = settings.poolFilter;
     const r = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt",
-  "version": "1.60.0",
+  "version": "1.61.0",
   "description": "Command-line interface for Conduyt CRM — manage contacts, deals, pipelines, and run insight queries from your terminal.",
   "type": "module",
   "main": "dist/index.js",