conduyt 1.81.0 → 1.82.0

package/README.md

@@ -56,8 +56,9 @@ conduyt deals health --pipeline <id> --check needs_action   # GET /deals/inspect
 conduyt deals health-fix <dealId> --check stale --expected-updated-at <iso> --stage-id <uuid>   # Pipeline health quick fix (PATCH /deals/{id} with checkOrigin): stale = --stage-id, unassigned = --assigned, missing_close_date = --close-date, missing_contact = --contact; 409 deal_changed / deal_check_cleared and 400 health_fix_mismatch exit 1 verbatim, never retried
 conduyt deals health-next-action <dealId> --check needs_action --expected-updated-at <iso> --title "Call back" --idempotency-key <key>   # "Set next action" (POST /tasks with checkOrigin): one non-done quick-fix task per deal, 409 deal_has_next_action / deal_changed / deal_check_cleared exit 1 verbatim
 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 [--lost-reason-allow-other true]   # what a deal needs to enter the stage; other stages untouched; `stage-rules get [pipelineId] [stageId]` reads
+conduyt pipelines stage-rules set <pipelineId> <stageId> --required-fields contactId,custom:loan_amount --required-documents 2 [--lost-reason-allow-other true] [--entry-by-automation-only true]   # what a deal needs to enter the stage (--entry-by-automation-only true: only an automation can move or create a deal into it, every other entry is refused 422 stage_automation_only; `pipelines list` shows it on each 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 deals bulk-edit --ids <id>,<id> --stage <stage>   # the SAME change on up to 500 deals (POST /bulk/deals/edit { ids, updates }); failed deals are listed with their code (e.g. stage_automation_only), exit 1 if any failed
 conduyt pipelines                       # list pipelines and stages (each carries color, automationOnly, sortOrder)
 conduyt pipelines list --archived       # the archived pipelines (owner / admin key): name, archivedName, openDeals, stageCount
 conduyt pipelines archive <id> --move-open-deals-to <pipelineId|none> [--expected-settings-revision N]   # archive + move the open deals in one transaction; refusals print their code (stale_settings_revision, target_not_open, dpp_post_close, archive_too_large, target_archived, intake_target, pipeline_archived) and exit 1

package/dist/board-settings.js

@@ -11,7 +11,7 @@ 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", "lostReasonAllowOther"];
+export const RULE_KEYS = ["requiredFields", "requiredDocuments", "lostReasonLabel", "lostReasonOptions", "lostReasonAllowOther", "entryByAutomationOnly"];
 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) {
@@ -64,9 +64,9 @@ export function validateRuleChange(raw) {
                 throw new Error("lostReasonLabel must be 1-60 characters.");
             out[k] = t;
         }
-        else if (k === "lostReasonAllowOther") {
+        else if (k === "lostReasonAllowOther" || k === "entryByAutomationOnly") {
             if (typeof v !== "boolean")
-                throw new Error("lostReasonAllowOther must be true or false.");
+                throw new Error(`${k} must be true or false.`);
             out[k] = v;
         }
         else {

package/dist/index.js

@@ -38,6 +38,18 @@ function readVersion() {
         return "0.0.0";
     }
 }
+/** (#289 r3) the bulk deal routes read a fixed field list and silently DROP any other key, so a typo (`titel`) would hide behind a
+ *  partly applied call: refuse it locally. app/api/v1/bulk/deals/edit/route.ts:56 (MAX_BULK_SIZE 500, refused 422 at :139-140) and
+ *  its ALLOWED_FIELDS; app/api/v1/bulk/deals/update/route.ts:49-60 (MAX_BULK_SIZE 100, ALLOWED_FIELDS plus customFields; each item also has id). */
+const BULK_EDIT_MAX_IDS = 500;
+const BULK_UPDATE_MAX_ITEMS = 100;
+const BULK_EDIT_FIELDS = ["title", "stageId", "value", "currency", "status", "priority", "assignedTo", "expectedCloseDate", "lostReason"];
+const BULK_UPDATE_FIELDS = ["id", ...BULK_EDIT_FIELDS, "customFields"];
+function assertAllowedKeys(keys, allowed, where) {
+    const bad = keys.filter((k) => !allowed.includes(k));
+    if (bad.length > 0)
+        throw new Error(`${where}: unknown field ${bad.map((k) => `"${k}"`).join(", ")}. The API ignores unknown fields silently, so nothing was sent. Allowed: ${allowed.join(", ")}.`);
+}
 const program = new Command();
 program
     .name("conduyt")
@@ -891,7 +903,7 @@ cardFields
 }));
 deals
     .command("create")
-    .description("Create a deal (use `pipelines list` to get pipeline/stage ids)")
+    .description("Create a deal (use `pipelines list` to get pipeline/stage ids). A stage set to \"Entry by automation only\" refuses every entry: 422 code stage_automation_only, message \"Only an automation can move a deal into <stage>\" (admins and API keys included; moving out is free); the code and message are printed on stderr unchanged.")
     .option("--title <title>", "deal title")
     .option("--pipeline <id>", "pipeline UUID")
     .option("--stage <id>", "stage UUID")
@@ -958,7 +970,7 @@ function assertDealSource(body) {
 }
 deals
     .command("update <id>")
-    .description("Update a deal (PATCH — only the fields you pass change). --stage moves the deal (won/lost status auto-derives from the target stage's flags)")
+    .description("Update a deal (PATCH — only the fields you pass change). --stage moves the deal (won/lost status auto-derives from the target stage's flags). A stage set to \"Entry by automation only\" refuses every entry: 422 code stage_automation_only, message \"Only an automation can move a deal into <stage>\" (admins and API keys included; moving out is free); the code and message are printed on stderr unchanged.")
     .option("--title <title>", "deal title")
     .option("--value <n>", "deal value (number)")
     .option("--currency <code>", "ISO currency, e.g. GBP")
@@ -1027,7 +1039,7 @@ deals
 }));
 deals
     .command("bulk-update")
-    .description("Update up to 100 deals in one request (POST /bulk/deals/update). Pass a JSON array of { id, ...editable fields (title, stageId, value, currency, status, priority, assignedTo, expectedCloseDate, lostReason, customFields) } via --updates or --file. Each item is applied on its own; prints the summary and one result per item, and exits 1 when any item failed (the full result is still printed). Rate limited to 5 requests a minute")
+    .description("Update up to 100 deals in one request (POST /bulk/deals/update). Pass a JSON array of { id, ...editable fields (title, stageId, value, currency, status, priority, assignedTo, expectedCloseDate, lostReason, customFields) } via --updates or --file. Each item is applied on its own; prints the summary and one result per item, and exits 1 when any item failed (the full result is still printed). Rate limited to 5 requests a minute. A stage change into an \"Entry by automation only\" stage fails that item with code stage_automation_only; the code stays on its result row in the printed output and is repeated on its `Failed <id>` stderr line")
     .option("--updates <json>", "the updates as a JSON array (or @file)")
     .option("--file <path>", "read the updates JSON array from a file")
     .action(async (opts) => {
@@ -1060,6 +1072,10 @@ deals
         }
         if (!Array.isArray(updates))
             throw new Error("The updates must be a JSON array of { id, ...fields } objects.");
+        if (updates.length > BULK_UPDATE_MAX_ITEMS)
+            throw new Error(`The updates take at most ${BULK_UPDATE_MAX_ITEMS} items (got ${updates.length}); the API refuses more with 422.`);
+        updates.forEach((u, i) => { if (u && typeof u === "object" && !Array.isArray(u))
+            assertAllowedKeys(Object.keys(u), BULK_UPDATE_FIELDS, `updates[${i}]`); });
         const client = new ConduytClient();
         const res = await client.post("/api/v1/bulk/deals/update", { updates });
         print(res);
@@ -1083,7 +1099,7 @@ deals
         const failedItems = results.filter((r) => r.success === false);
         if (failedItems.length > 0 || Number(sm.failed) > 0) {
             for (const r of failedItems)
-                process.stderr.write(`Failed ${r.id}: ${r.error ?? "unknown error"}\n`);
+                process.stderr.write(`Failed ${r.id}: ${r.error ?? "unknown error"}${typeof r.code === "string" ? ` [code: ${r.code}]` : ""}\n`);
             process.stderr.write(`Error: ${failedItems.length || sm.failed} of ${sm.total} updates failed.\n`);
             process.exitCode = 1;
         }
@@ -1092,6 +1108,83 @@ deals
         fail(err);
     }
 });
+deals
+    .command("bulk-edit")
+    .description("Apply the SAME field changes to many deals in one request (POST /bulk/deals/edit, body { ids, updates }; up to 500 ids). --ids is a comma-separated list of deal UUIDs; the update flags (--stage, --title, --value, --currency, --status, --priority, --assigned-to, --expected-close-date, --lost-reason) or --json build the one updates object. Each deal is applied on its own; prints { updated, skippedNoOp, requested, errors } and exits 1 when any deal failed (the full result is still printed). A stage change into an \"Entry by automation only\" stage fails that deal with code stage_automation_only and the message \"Only an automation can move a deal into <stage>\": the code stays on its row in the printed errors and is repeated on its `Failed <id>` stderr line. For different changes per deal use `deals bulk-update`")
+    .requiredOption("--ids <list>", "comma-separated deal UUIDs")
+    .option("--stage <name-or-uuid>", "move every deal to this stage (a stage name is resolved via /automations/resolve)")
+    .option("--title <title>", "deal title")
+    .option("--value <n>", "deal value (number)")
+    .option("--currency <code>", "ISO currency, e.g. GBP")
+    .option("--status <status>", "explicit status (open|won|lost)")
+    .option("--priority <priority>", "priority, e.g. low|medium|high")
+    .option("--assigned-to <id>", "owner user UUID")
+    .option("--expected-close-date <date>", "expected close date (ISO 8601)")
+    .option("--lost-reason <reason>", "reason for a lost/disqualified deal")
+    .option("--json <json>", "the updates object as JSON, merged over the flags")
+    .action(async (opts) => {
+    try {
+        // Preflight: everything the CLI can check is checked BEFORE the stage name is looked up and before any request.
+        const ids = uuidList(opts.ids, "--ids");
+        if (ids.length > BULK_EDIT_MAX_IDS)
+            throw new Error(`--ids takes at most ${BULK_EDIT_MAX_IDS} deal ids (got ${ids.length}); the API refuses more with 422.`);
+        const updates = {};
+        if (opts.title !== undefined)
+            updates.title = opts.title;
+        if (opts.value !== undefined) {
+            const t = opts.value.trim();
+            const n = Number(t);
+            if (t === "" || !Number.isFinite(n))
+                throw new Error("--value must be a finite number.");
+            updates.value = n;
+        }
+        if (opts.currency !== undefined)
+            updates.currency = opts.currency;
+        if (opts.status !== undefined)
+            updates.status = opts.status;
+        if (opts.priority !== undefined)
+            updates.priority = opts.priority;
+        if (opts.assignedTo !== undefined)
+            updates.assignedTo = uuidOf(opts.assignedTo, "--assigned-to");
+        if (opts.expectedCloseDate !== undefined)
+            updates.expectedCloseDate = opts.expectedCloseDate;
+        if (opts.lostReason !== undefined) {
+            if (opts.lostReason.trim() === "")
+                throw new Error("--lost-reason was provided but is blank. Omit it or pass a reason.");
+            updates.lostReason = opts.lostReason;
+        }
+        if (opts.stage !== undefined && opts.stage.trim() === "")
+            throw new Error("--stage was provided but is blank. Omit it or pass a stage name/UUID.");
+        if (opts.json !== undefined)
+            Object.assign(updates, jsonArg(opts.json, "--json"));
+        assertAllowedKeys(Object.keys(updates), BULK_EDIT_FIELDS, "--json updates");
+        assertFiniteValue(updates.value);
+        const stageFromFlag = opts.stage !== undefined && updates.stageId === undefined;
+        if (Object.keys(updates).length === 0 && !stageFromFlag)
+            throw new Error("Nothing to apply. Pass at least one update flag or --json.");
+        const client = new ConduytClient();
+        if (stageFromFlag)
+            updates.stageId = await resolveStageId(client, opts.stage);
+        const res = await client.post("/api/v1/bulk/deals/edit", { ids, updates });
+        print(res);
+        const data = unwrap(res);
+        const errors = data && typeof data === "object" && Array.isArray(data.errors) ? data.errors : null;
+        if (!errors || typeof data.updated !== "number" || typeof data.requested !== "number") {
+            process.stderr.write("Error: Unexpected response shape from the API: expected data.updated, data.requested and data.errors.\n");
+            process.exitCode = 1;
+            return;
+        }
+        if (errors.length > 0) {
+            for (const e of errors)
+                process.stderr.write(`Failed ${String(e?.id ?? "?")}: ${e?.error ?? "unknown error"}${typeof e?.code === "string" ? ` [code: ${e.code}]` : ""}\n`);
+            process.stderr.write(`Error: ${errors.length} of ${data.requested} deals failed.\n`);
+            process.exitCode = 1;
+        }
+    }
+    catch (err) {
+        fail(err);
+    }
+});
 // ---- pipelines ----
 // Default action preserves the original published `conduyt pipelines` (list)
 // invocation now that pipelines is a group — without it, commander prints help
@@ -1103,7 +1196,7 @@ const pipelines = program
     .action(run(async (client) => client.get("/api/v1/pipelines")));
 pipelines
     .command("list")
-    .description("List pipelines and their stages (each pipeline carries color, automationOnly, sortOrder). --archived lists the ARCHIVED pipelines instead (owner / admin key): id, name (the pre-archive name), archivedName, color, archivedAt, openDeals, stageCount")
+    .description("List pipelines and their stages (each pipeline carries color, automationOnly, sortOrder; each stage carries entryByAutomationOnly: true = only an automation can move or create a deal INTO it, every other entry is refused 422 stage_automation_only; set it with `pipelines stage-rules set --entry-by-automation-only`). --archived lists the ARCHIVED pipelines instead (owner / admin key): id, name (the pre-archive name), archivedName, color, archivedAt, openDeals, stageCount")
     .option("--archived", "list the archived pipelines (GET /pipelines?archived=true) instead of the active ones")
     .action(run(async (client, opts) => client.get(opts.archived ? "/api/v1/pipelines?archived=true" : "/api/v1/pipelines")));
 pipelines
@@ -1205,7 +1298,7 @@ const stageRules = pipelines
     .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, lostReasonAllowOther } } }, for everything, one pipeline, or one stage")
+    .description("Read the stage rules as { pipelineId: { stageId: { requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther, entryByAutomationOnly } } }, for everything, one pipeline, or one stage")
     .action(run(async (client, pipelineId, stageId) => {
     if (pipelineId !== undefined)
         assertUuid(pipelineId, "pipeline id");
@@ -1229,7 +1322,8 @@ stageRules
     .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("--lost-reason-allow-other <bool>", "true|false: the rep may also pick \"Other\" and type the reason (stored as the reason text; takes effect while the stage has lost-reason options)")
-    .option("--json <json>", "the rule fields as a JSON object ({requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther}), merged over the flags")
+    .option("--entry-by-automation-only <bool>", "true|false: \"Entry by automation only\": only an automation run can move or create a deal INTO the stage; every other entry (admins and API keys included) is refused 422 stage_automation_only; moving out stays free (to correct by hand: set false, move the deal, set true; the starting stage of automatic intake deals cannot be one)")
+    .option("--json <json>", "the rule fields as a JSON object ({requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther, entryByAutomationOnly}), merged over the flags")
     .action(run(async (client, pipelineId, stageId, opts) => {
     assertUuid(pipelineId, "pipeline id");
     assertUuid(stageId, "stage id");
@@ -1246,18 +1340,20 @@ stageRules
         raw.lostReasonOptions = splitList(opts.lostReasonOptions);
     if (opts.lostReasonAllowOther !== undefined)
         raw.lostReasonAllowOther = boolFlag(opts.lostReasonAllowOther, "--lost-reason-allow-other");
+    if (opts.entryByAutomationOnly !== undefined)
+        raw.entryByAutomationOnly = boolFlag(opts.entryByAutomationOnly, "--entry-by-automation-only");
     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, --lost-reason-allow-other or --json.");
+        throw new Error("Nothing to set. Pass --required-fields, --required-documents, --lost-reason-label, --lost-reason-options, --lost-reason-allow-other, --entry-by-automation-only 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
     .command("update-stage <pipelineId> <stageId>")
-    .description("Update one stage (PATCH — only the fields you pass change). --is-system marks a system holding stage: automations route deals through it, reps never see it in a picker, and it can never be won or lost. A soft-deleted stage (`pipelines delete-stage`) answers 404")
+    .description("Update one stage (PATCH — only the fields you pass change). --is-system marks a system holding stage: automations route deals through it, reps never see it in a picker, and it can never be won or lost. A soft-deleted stage (`pipelines delete-stage`) answers 404. The \"Entry by automation only\" flag is not set here (the API reads it from the stage rules): use `pipelines stage-rules set --entry-by-automation-only`")
     .option("--name <name>", "stage name")
     .option("--color <hex>", "stage colour")
     .option("--is-won <bool>", "true|false — entering this stage closes the deal as won")
@@ -1309,7 +1405,7 @@ pipelines
 // (pipeline settings 10-08) archive / restore / reorder, stage delete with a move, the stale-in-stage days.
 pipelines
     .command("archive <id>")
-    .description("Archive a pipeline (owner / admin key): renamed with the archived prefix, never deleted; its closed deals stay as history and `pipelines restore` brings it back. Every OPEN deal moves in the same transaction to --move-open-deals-to's first stage through the normal stage-entry rules; any refusal aborts all of it. Pass --move-open-deals-to none only when there are no open deals. Waits up to 75 s; if it times out the archive may have committed, so run `pipelines list` / `pipelines list --archived` before retrying. The default pipeline cannot be archived. Refusal codes are printed with the error and the command exits 1: stale_settings_revision, target_not_open, dpp_post_close, archive_too_large, target_archived, intake_target, pipeline_archived, open_deals, default_pipeline, stage_requirements, archive_raced, pipeline_automation_only. An already-archived pipeline answers { archived: true, alreadyArchived: true }")
+    .description("Archive a pipeline (owner / admin key): renamed with the archived prefix, never deleted; its closed deals stay as history and `pipelines restore` brings it back. Every OPEN deal moves in the same transaction to --move-open-deals-to's first stage through the normal stage-entry rules; any refusal aborts all of it. Pass --move-open-deals-to none only when there are no open deals. Waits up to 75 s; if it times out the archive may have committed, so run `pipelines list` / `pipelines list --archived` before retrying. The default pipeline cannot be archived. Refusal codes are printed with the error and the command exits 1: stale_settings_revision, target_not_open, dpp_post_close, archive_too_large, target_archived, intake_target, pipeline_archived, open_deals, default_pipeline, stage_requirements, archive_raced, pipeline_automation_only, stage_automation_only (422, the destination is an \"Entry by automation only\" stage; nothing moved). An already-archived pipeline answers { archived: true, alreadyArchived: true }")
     .requiredOption("--move-open-deals-to <pipelineId|none>", "the active pipeline the open deals move to (its first stage must be open), or none when the pipeline has no open deals")
     .option("--expected-settings-revision <n>", "the settingsRevision from `pipelines settings-revision`; refused 409 stale_settings_revision when settings changed since")
     .action(run(async (client, id, opts) => {
@@ -1350,7 +1446,7 @@ pipelines
 }));
 pipelines
     .command("delete-stage <pipelineId> <stageId>")
-    .description("Soft-delete a stage (owner / admin key). An EMPTY stage can always be deleted, even if deals once used it: the row is kept so deal history and reports keep its name, but it is hidden from every pipeline / stage list, GET / PATCH on it answer 404, there is NO restore in v1, and its name may be reused by a new stage; its stage rule, outcome mappings and status metadata go with it. With --move-to the live deals move to another stage of the SAME pipeline (same won / lost setting, not a system stage) and the stage is deleted in one transaction. With --expected-settings-revision the answer is { id, deleted: true, settingsRevision }. A refusal exits 1 with the server's message printed verbatim and its code when it has one (never retried): deals currently in the stage and no --move-to; 'Cannot delete stage: it is used by N active automation(s) (names). Change their stage or pause them first.' (a published automation uses the stage in an action, trigger, condition or wait-until); the DPP status map selects it; stale_settings_revision, pipeline_archived, intake_target. A --move-to that is not a valid target is a 400. Accepted window: a run parked or in flight before the delete is not tracked; at the step that targets the deleted stage it fails or is skipped with a clear reason in the execution log")
+    .description("Soft-delete a stage (owner / admin key). An EMPTY stage can always be deleted, even if deals once used it: the row is kept so deal history and reports keep its name, but it is hidden from every pipeline / stage list, GET / PATCH on it answer 404, there is NO restore in v1, and its name may be reused by a new stage; its stage rule, outcome mappings and status metadata go with it. With --move-to the live deals move to another stage of the SAME pipeline (same won / lost setting, not a system stage) and the stage is deleted in one transaction. With --expected-settings-revision the answer is { id, deleted: true, settingsRevision }. A refusal exits 1 with the server's message printed verbatim and its code when it has one (never retried): deals currently in the stage and no --move-to; 'Cannot delete stage: it is used by N active automation(s) (names). Change their stage or pause them first.' (a published automation uses the stage in an action, trigger, condition or wait-until); the DPP status map selects it; stale_settings_revision, pipeline_archived, intake_target. A --move-to that is not a valid target is a 400, and a --move-to stage that is \"Entry by automation only\" is refused 422 stage_automation_only (code and message unchanged). Accepted window: a run parked or in flight before the delete is not tracked; at the step that targets the deleted stage it fails or is skipped with a clear reason in the execution log")
     .option("--move-to <stageId>", "another stage of the same pipeline the live deals move to")
     .option("--expected-settings-revision <n>", "the settingsRevision from `pipelines settings-revision`; refused 409 stale_settings_revision when settings changed since")
     .action(run(async (client, pipelineId, stageId, opts) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt",
-  "version": "1.81.0",
+  "version": "1.82.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",