conduyt 1.65.0 → 1.66.0

package/README.md

@@ -44,6 +44,8 @@ conduyt notifications list [--page n] [--per-page 1-200]   # prints { data, meta
 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 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 deals bulk-update --file updates.json   # update up to 100 deals at once ([{id, stageId, value, ...}]); per-item results, exit 1 if any failed
@@ -93,6 +95,24 @@ Pass `--input '{"...":"..."}'` to `insights` and `--body '{"...":"..."}'` to `ap
 
 All output is JSON, ready to pipe into `jq`.
 
+## Error output grammar
+
+A refused call (HTTP 4xx/5xx) prints one line on stderr and exits 1:
+
+```
+Error: Conduyt API <status>: <server message>[ [Retry-After: <N>s]][ <details>]
+```
+
+`[Retry-After: Ns]` appears only when the server sent the header (shown, never acted on: nothing is retried). `<details>` appears
+only when the body had more than `error`: it is ONE JSON object and the FINAL token. To extract it, try each `{` from the left
+until the rest of the line parses as JSON (a server message may itself contain a brace). Scalars (`code`, revision) come
+first, nested objects whole; `HealthFixRefusal.row` is always whole, any other nested object too large for the bound is left
+out and named in `_omitted`. Every HTTP refusal takes this path (JSON calls, text exports and streams alike). The settings-conflict commands merge their hint and the current settings INTO that final object (`{...details, hint, current}`), never after it. Example:
+
+```
+Error: Conduyt API 503: Contact merge in progress [Retry-After: 5s] {"code":"merge_in_progress"}
+```
+
 ## License
 
 MIT

package/dist/client.js

@@ -7,6 +7,55 @@ function ambiguousTimeout(err, method, path, timeoutMs, what) {
     }
     return err;
 }
+/** Room for the nested objects of an error body (a 409 contact_changed's `contact`, a stage-requirements list). */
+const ERROR_DETAILS_BOUND = 1000;
+/** Error-body keys that are the actionable state itself and are always rendered WHOLE: HealthFixRefusal.row (the deal's
+ *  current health row, which a caller needs to choose again). */
+const ALWAYS_WHOLE_KEYS = new Set(["row"]);
+/** Everything but `error` as ONE valid JSON object: scalars first (a very long string is shortened inside its quotes), then
+ *  nested objects whole while they fit ERROR_DETAILS_BOUND, plus ALWAYS_WHOLE_KEYS; one that does not fit is left out and
+ *  named in `_omitted`. JSON is never cut mid-object. */
+export function renderErrorDetails(body) {
+    const entries = Object.entries(body).filter(([k]) => k !== "error");
+    if (entries.length === 0)
+        return "";
+    const isScalar = (v) => v === null || typeof v !== "object";
+    const out = {};
+    for (const [k, v] of entries.filter(([, v]) => isScalar(v)))
+        out[k] = typeof v === "string" && v.length > ERROR_DETAILS_BOUND ? v.slice(0, ERROR_DETAILS_BOUND) + "...[shortened]" : v;
+    const omitted = [];
+    for (const [k, v] of entries.filter(([, v]) => !isScalar(v))) {
+        if (ALWAYS_WHOLE_KEYS.has(k) || JSON.stringify({ ...out, [k]: v }).length <= ERROR_DETAILS_BOUND)
+            out[k] = v;
+        else
+            omitted.push(k);
+    }
+    if (omitted.length > 0)
+        out._omitted = omitted;
+    return JSON.stringify(out);
+}
+/**
+ * The ONE place an HTTP refusal becomes an Error (request, postText and stream all use it). Grammar (stable):
+ * `Conduyt API <status>: <message>[ [Retry-After: <N>s]][ <details>]`; <details> is ONE JSON object and the FINAL token
+ * (renderErrorDetails). Retry-After is shown, never acted on. A structured body without `error` IS the details object.
+ */
+export function formatHttpError(res, text) {
+    const json = text ? safeParse(text) : null;
+    const ra = res.headers.get("retry-after");
+    const raN = ra === null || ra.trim() === "" ? NaN : Number(ra);
+    const raTag = Number.isFinite(raN) && raN >= 0 ? ` [Retry-After: ${raN}s]` : "";
+    const obj = json && typeof json === "object" && !Array.isArray(json) ? json : null;
+    if (obj && typeof obj.error === "string" && obj.error) {
+        const extras = renderErrorDetails(obj);
+        return new Error(`Conduyt API ${res.status}: ${obj.error}${raTag}${extras ? ` ${extras}` : ""}`);
+    }
+    // several endpoints answer the data a caller needs IN the error body (custom-field delete 409 valueCount / dependencyCount)
+    const extras = obj ? renderErrorDetails(obj) : "";
+    if (extras)
+        return new Error(`Conduyt API ${res.status}:${raTag} ${extras}`);
+    const plain = typeof json === "string" && json ? json.slice(0, 500) : "";
+    return new Error(`Conduyt API ${res.status}: ${plain || res.statusText || `HTTP ${res.status}`}${raTag}`);
+}
 export class ConduytClient {
     baseUrl;
     apiKey;
@@ -25,6 +74,7 @@ export class ConduytClient {
             res = await fetch(url, {
                 method,
                 headers: {
+                    ...(opts?.headers ?? {}),
                     Authorization: `Bearer ${this.apiKey}`,
                     "Content-Type": "application/json",
                 },
@@ -45,31 +95,7 @@ export class ConduytClient {
         }
         const json = text ? safeParse(text) : null;
         if (!res.ok) {
-            // Preserve structured non-2xx bodies: several endpoints return the data
-            // a caller needs to proceed IN the error body (e.g. custom-field delete
-            // 409 carries valueCount/dependencyCount for the --confirm flow).
-            // Reducing those to statusText would strand the user.
-            const structured = json && typeof json === "object" && !json.error
-                ? JSON.stringify(json)
-                : null;
-            let msg = json?.error || structured || res.statusText || `HTTP ${res.status}`;
-            // Bodies with BOTH an error message and structured context (e.g. the
-            // STAGE_REQUIREMENTS 422 carries lostReasonOptions) keep the context —
-            // same principle as `structured` above, bounded against huge bodies.
-            if (json && typeof json === "object" && json.error) {
-                // Scalars first (code, revision), nested objects last: a 409 contact_changed also carries the whole current
-                // `contact`, and the bound below may cut that, never the code or the current revision.
-                const isScalar = (v) => v === null || typeof v !== "object";
-                const entries = Object.entries(json).filter(([k]) => k !== "error");
-                const extras = Object.fromEntries([
-                    ...entries.filter(([, v]) => isScalar(v)),
-                    ...entries.filter(([, v]) => !isScalar(v)),
-                ]);
-                if (Object.keys(extras).length > 0) {
-                    msg = `${msg} ${JSON.stringify(extras).slice(0, 1000)}`;
-                }
-            }
-            throw new Error(`Conduyt API ${res.status}: ${msg}`);
+            throw formatHttpError(res, text);
         }
         return json;
     }
@@ -98,14 +124,8 @@ export class ConduytClient {
             body: body === undefined ? undefined : JSON.stringify(body),
         });
         const text = await res.text();
-        if (!res.ok) {
-            let msg = text.slice(0, 500);
-            try {
-                msg = JSON.parse(text).error ?? msg;
-            }
-            catch { /* keep the raw text */ }
-            throw new Error(`Conduyt API ${res.status}: ${msg}`);
-        }
+        if (!res.ok)
+            throw formatHttpError(res, text);
         return { text, filename: res.headers.get("x-report-filename"), contentType: res.headers.get("content-type") };
     }
     // Stream `ai chat`'s text/event-stream response to stdout as clean answer
@@ -127,10 +147,7 @@ export class ConduytClient {
             body: body !== undefined ? JSON.stringify(body) : undefined,
         });
         if (!res.ok || !res.body) {
-            const text = await res.text();
-            const json = text ? safeParse(text) : null;
-            const msg = json?.error || res.statusText || `HTTP ${res.status}`;
-            throw new Error(`Conduyt API ${res.status}: ${msg}`);
+            throw formatHttpError(res, await res.text());
         }
         const reader = res.body.getReader();
         const decoder = new TextDecoder();

package/dist/index.js

@@ -536,6 +536,73 @@ deals
     const qs = usp.toString();
     return client.get(`/api/v1/deals/inspection${qs ? `?${qs}` : ""}`);
 }));
+const HEALTH_FIX_REFUSALS = "Error line grammar: `Error: Conduyt API <status>: <message>[ [Retry-After: Ns]][ <one JSON object, the final token>]` (README, Error output grammar). Refusals exit 1 with the server's status, message and code printed verbatim, sent once (never retried): 409 deal_changed (the deal is no longer at --expected-updated-at; the error carries updatedAt and the deal's current health row: read it and choose again against row.updatedAt), 409 deal_check_cleared (the deal no longer fails that check), 400 health_fix_mismatch, 404";
+deals
+    .command("health-fix <id>")
+    .description(`Pipeline health QUICK FIX for a deal row (PATCH /deals/{id} with checkOrigin). Send the check the row came from, --expected-updated-at (the deal's updatedAt as the health row carried it, REQUIRED) and ONLY that check's fix: stale = --stage-id (+ --expected-stage-id), unassigned = --assigned, missing_close_date = --close-date, missing_contact = --contact. Anything else is refused 400 health_fix_mismatch and nothing is read or written. For high_value_idle / needs_action use \`deals health-next-action\`. ${HEALTH_FIX_REFUSALS}; an uncoded 409 is a stage move by another writer, a stale --expected-stage-id or an in-flight publication`)
+    .requiredOption("--check <check>", "stale | unassigned | missing_close_date | missing_contact")
+    .requiredOption("--expected-updated-at <iso>", "the deal's updatedAt as the health row carried it (PipelineHealthDeal.updatedAt)")
+    .option("--stage-id <uuid>", "stale: the stage UUID to move the deal to")
+    .option("--expected-stage-id <uuid>", "stale: the stage the move was chosen against; 409 (nothing written) when the deal is no longer in it")
+    .option("--assigned <uuid>", "unassigned: the user (owner) UUID to assign")
+    .option("--close-date <date>", "missing_close_date: the expected close date (ISO 8601)")
+    .option("--contact <uuid>", "missing_contact: the contact UUID to link")
+    .action(run(async (client, id, opts) => {
+    const dealId = uuidOf(id, "deal id");
+    if (!["stale", "unassigned", "missing_close_date", "missing_contact"].includes(opts.check))
+        throw new Error("--check must be stale, unassigned, missing_close_date or missing_contact (for high_value_idle / needs_action use `deals health-next-action`).");
+    rejectBlankFlags([["--close-date", opts.closeDate]]);
+    const body = { checkOrigin: opts.check, expectedUpdatedAt: isoDate(opts.expectedUpdatedAt, "--expected-updated-at") };
+    if (opts.stageId !== undefined)
+        body.stageId = uuidOf(opts.stageId, "--stage-id");
+    if (opts.expectedStageId !== undefined)
+        body.expectedStageId = uuidOf(opts.expectedStageId, "--expected-stage-id");
+    if (opts.assigned !== undefined)
+        body.assignedTo = uuidOf(opts.assigned, "--assigned");
+    if (opts.closeDate !== undefined)
+        body.expectedCloseDate = opts.closeDate;
+    if (opts.contact !== undefined)
+        body.contactId = uuidOf(opts.contact, "--contact");
+    return client.patch(`/api/v1/deals/${encodeURIComponent(dealId)}`, body);
+}));
+deals
+    .command("health-next-action <id>")
+    .description(`Pipeline health QUICK FIX "Set next action" (POST /tasks with checkOrigin): creates a follow-up task on deal <id> from a High-value idle or Needs next action row. The task is created only while, under the deal's next-action lock, the deal is still at --expected-updated-at, still has no next action and still fails the check. Pass --idempotency-key (1-255 printable ASCII) so a retry after a lost response replays the first task; reuse it ONLY for the same request. The database allows at most one non-done quick-fix task per deal (a second is refused 409 deal_has_next_action); ordinary tasks (\`tasks create\`) are unconstrained and may coexist with or race a quick fix. ${HEALTH_FIX_REFUSALS.replace("409 deal_check_cleared", "409 deal_has_next_action (This deal already has a next action booked.), 409 deal_check_cleared")}; also an uncoded 409 (the contact was merged or deleted mid-request: retry against the surviving record) and the idempotency 409 idempotency_key_spent / 503 idempotency_claim_held / idempotency_outcome_unknown (verify the outcome before using a new key)`)
+    .requiredOption("--check <check>", "high_value_idle | needs_action")
+    .requiredOption("--expected-updated-at <iso>", "the deal's updatedAt as the health row carried it (sent as expectedDealUpdatedAt)")
+    .requiredOption("--title <title>", "task title (1-500 chars)")
+    .option("--description <text>", "description (max 5000)")
+    .option("--due <date>", "due date: YYYY-MM-DD is stored as noon UTC that day; a date-time as given")
+    .option("--priority <priority>", "low|medium|high|urgent (default medium)")
+    .option("--status <status>", "todo|in_progress|done (default todo)")
+    .option("--assigned <id>", "assignee user UUID, or @me / @owner (assigning to someone else needs tasks.assign)")
+    .option("--contact <uuid>", "link to contact UUID")
+    .option("--idempotency-key <key>", "sent as the Idempotency-Key header")
+    .action(run(async (client, id, opts) => {
+    const dealId = uuidOf(id, "deal id");
+    if (!["high_value_idle", "needs_action"].includes(opts.check))
+        throw new Error("--check must be high_value_idle or needs_action (for the other checks use `deals health-fix`).");
+    if (opts.title.trim() === "" || opts.title.length > 500)
+        throw new Error("--title must be 1 to 500 characters.");
+    if (opts.description !== undefined && opts.description.length > 5000)
+        throw new Error("--description must be at most 5000 characters.");
+    if (opts.idempotencyKey !== undefined && !/^[!-~](?:[ -~]{0,253}[!-~])?$/.test(opts.idempotencyKey))
+        throw new Error("--idempotency-key must be 1-255 printable ASCII characters, not blank.");
+    const body = { checkOrigin: opts.check, dealId, expectedDealUpdatedAt: isoDate(opts.expectedUpdatedAt, "--expected-updated-at"), title: opts.title };
+    if (opts.description !== undefined)
+        body.description = opts.description;
+    if (opts.due !== undefined)
+        body.dueDate = opts.due;
+    if (opts.priority !== undefined)
+        body.priority = opts.priority;
+    if (opts.status !== undefined)
+        body.status = opts.status;
+    if (opts.assigned !== undefined)
+        body.assignedTo = opts.assigned;
+    if (opts.contact !== undefined)
+        body.contactId = uuidOf(opts.contact, "--contact");
+    return client.post("/api/v1/tasks", body, opts.idempotencyKey !== undefined ? { headers: { "Idempotency-Key": opts.idempotencyKey } } : undefined);
+}));
 // (BDA board 10-08) settings.dealCardFields: the fields on each kanban deal card, in order
 const cardFields = deals
     .command("card-fields")
@@ -1413,7 +1480,7 @@ tasks
 }));
 tasks
     .command("create")
-    .description("Create a task (--assigned accepts a user UUID, or the magic strings @me / @owner)")
+    .description("Create a task (--assigned accepts a user UUID, or the magic strings @me / @owner). This is the ORDINARY task route: ordinary tasks are unconstrained and may coexist with or race a Pipeline health quick-fix task; the database allows at most one non-done quick-fix task per deal (a second is refused 409 deal_has_next_action). Create the quick fix itself with `deals health-next-action`. A 409 without a code means the contact was merged or deleted mid-request: retry against the surviving record")
     .option("--title <title>", "task title (required)")
     .option("--description <text>", "description")
     .option("--status <status>", "todo|in_progress|done (default todo)")
@@ -1447,7 +1514,7 @@ tasks
 }));
 tasks
     .command("update <id>")
-    .description("Update a task (PATCH — only the fields you pass change)")
+    .description("Update a task (PATCH — only the fields you pass change). A 409 means nothing was written, printed verbatim with exit 1 and never retried: code deal_has_next_action (\"This deal already has a next action booked.\": re-opening or re-linking a quick-fix task would give the deal a second open one), or no code (the task changed while saving: read it again and retry)")
     .option("--title <title>", "task title")
     .option("--description <text>", "description")
     .option("--status <status>", "todo|in_progress|done")
@@ -3651,6 +3718,28 @@ replyCapture
 }));
 // ---- lifecycle (master lead status + intake deals) ----
 // ---- general settings writes (09-15) ----
+/** Split an error message into its prefix and its trailing details object (the grammar's final token): try each `{` from the
+ *  left until the rest parses as a JSON object. */
+function splitErrorDetails(message) {
+    for (let i = message.indexOf("{"); i !== -1; i = message.indexOf("{", i + 1)) {
+        try {
+            const v = JSON.parse(message.slice(i));
+            if (v && typeof v === "object" && !Array.isArray(v))
+                return { prefix: message.slice(0, i).trimEnd(), details: v };
+        }
+        catch { /* next brace */ }
+    }
+    return { prefix: message, details: {} };
+}
+/** A settings conflict re-raised with a hint and the CURRENT settings: the original details object and the extra state are merged
+ *  into ONE final JSON object `{...details, hint, current}`, so nothing follows it. `current` is kept whole up to 20000 characters;
+ *  past that it is left out and `currentOmitted` says so (re-read with `settings get`). */
+function settingsConflictError(err, hint, current) {
+    const { prefix, details } = splitErrorDetails(err.message);
+    const whole = JSON.stringify(current ?? null);
+    const extra = whole.length <= 20000 ? { hint, current: current ?? null } : { hint, currentOmitted: `${whole.length} characters; re-read the settings` };
+    return new Error(`${prefix} ${JSON.stringify({ ...details, ...extra })}`);
+}
 // PATCH /api/v1/settings refuses a general-settings change without the settingsRevision the editor loaded
 // (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
@@ -3670,7 +3759,7 @@ async function patchGeneralSettings(client, body) {
     catch (err) {
         if (err instanceof Error && /^Conduyt API 409/.test(err.message)) {
             const current = await read();
-            throw new Error(`${err.message} — the account settings changed since revision ${expectedSettingsRevision ?? "?"} was read; re-run the command (current: ${JSON.stringify(current?.data ?? null).slice(0, 1500)})`);
+            throw settingsConflictError(err, `the account settings changed since revision ${expectedSettingsRevision ?? "?"} was read; re-run the command`, current?.data);
         }
         throw err;
     }
@@ -3694,7 +3783,7 @@ async function patchGeneralSettingsMerged(client, build) {
                 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)})`);
+                throw settingsConflictError(err, `the account settings changed twice while this was being saved (last revision read ${revision ?? "?"}); re-run the command`, current?.data);
             }
         }
     }

package/package.json

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