conduyt 1.78.0 → 1.79.0

package/README.md

@@ -47,6 +47,7 @@ conduyt chat mark-read <channelId> <messageId>   # readUpTo: marker moves to tha
 conduyt notifications list [--page n] [--per-page 1-200]   # prints { data, meta }: meta.latestByType = { type: { latest, count } } over the last 24 h, next to unreadCount / unreadByType
 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 list --board-snapshot --pipeline <id> --board-columns <stageId>[:<limit>],...   # every named column of one pipeline from ONE database snapshot (a moved deal is in exactly one column); prints { columns: [{ stageId, limit, deals }], meta: { board_snapshot: true } }; --page / --all / --stage / --stage-name / --health-* refused before any request; 503 board_snapshot_busy or gate_busy exits 1 with Retry-After
 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

package/dist/index.js

@@ -516,6 +516,38 @@ function rejectBlankFlags(flags) {
         }
     }
 }
+/** GET /deals board_snapshot=true limits (the app's lib/deal-board-snapshot-limits, contract at 5729bc7b4). */
+const BOARD_SNAPSHOT_MAX_COLUMNS = 50;
+const BOARD_SNAPSHOT_MAX_COLUMN_ROWS = 1000;
+const BOARD_SNAPSHOT_MAX_TOTAL_ROWS = 5000;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** --board-columns <stageId>[:<limit>],...: the server's own rules checked before any request (1-50 columns, UUID stage
+ *  ids, no stage twice, limit a whole number 1-1000, default --limit, at most 5000 rows in total); the wire value. */
+function parseBoardColumnsFlag(raw, defaultLimit) {
+    const entries = raw.split(",").map((e) => e.trim());
+    if (raw.trim() === "" || entries.some((e) => e === ""))
+        throw new Error("--board-columns must be <stageId>[:<limit>],... with no blank entry.");
+    if (entries.length > BOARD_SNAPSHOT_MAX_COLUMNS)
+        throw new Error(`--board-columns names at most ${BOARD_SNAPSHOT_MAX_COLUMNS} columns (got ${entries.length}).`);
+    const seen = new Set();
+    let total = 0;
+    const out = [];
+    for (const entry of entries) {
+        const parts = entry.split(":");
+        const id = parts[0].trim();
+        if (parts.length > 2 || !UUID_RE.test(id))
+            throw new Error(`--board-columns expects <stageId>[:<limit>] entries with a stage UUID; got ${JSON.stringify(entry)}.`);
+        const limit = parts.length === 2 ? strictIntFlag(parts[1], `--board-columns limit for ${id}`, 1, BOARD_SNAPSHOT_MAX_COLUMN_ROWS) : defaultLimit;
+        if (seen.has(id.toLowerCase()))
+            throw new Error(`--board-columns names stage ${id} more than once.`);
+        seen.add(id.toLowerCase());
+        total += limit;
+        out.push(parts.length === 2 ? `${id}:${limit}` : id);
+    }
+    if (total > BOARD_SNAPSHOT_MAX_TOTAL_ROWS)
+        throw new Error(`--board-columns asks for ${total} rows; one snapshot answers at most ${BOARD_SNAPSHOT_MAX_TOTAL_ROWS}. Read deeper columns with --stage.`);
+    return out.join(",");
+}
 /** 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
@@ -534,6 +566,8 @@ deals
     .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")
+    .option("--board-snapshot", "read every column in --board-columns from ONE database snapshot (a deal moved during the read is in exactly one column). Needs --pipeline or --pipeline-name and --board-columns; refused (exit 1, no request) with --page, --all, --stage, --stage-name or any --health-* flag. Prints { columns: [{ stageId, limit, deals }], meta: { board_snapshot: true } }: columns in the order named, each column's deals exactly what --stage <stageId> --limit <limit> rows-only answers, no totals; deals.length equal to limit means the column may hold more. A 503 board_snapshot_busy (the snapshot could not finish in its budget: read the columns one by one or retry) or gate_busy (any deals list call: the access check could not finish in time) exits 1 with the code and Retry-After; never retried")
+    .option("--board-columns <columns>", `with --board-snapshot: <stageId>[:<limit>],... in answer order; 1-${BOARD_SNAPSHOT_MAX_COLUMNS} live stages of the pipeline, no stage twice, limit 1-${BOARD_SNAPSHOT_MAX_COLUMN_ROWS} (default --limit, itself default 50), at most ${BOARD_SNAPSHOT_MAX_TOTAL_ROWS} rows in total`)
     .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
@@ -551,6 +585,44 @@ deals
             throw new Error(`${flag} was provided but is blank. Omit it to skip the filter, or pass a real value.`);
         }
     }
+    // Board snapshot (#116 for app #111, contract 5729bc7b4): one pipeline's columns from ONE database snapshot. Its
+    // conflicts are refused here, before any request; the answer is { columns, meta } (no data.data / meta.total), so it
+    // never goes through the health branch or the --all / truncation logic below.
+    if (opts.boardSnapshot || opts.boardColumns !== undefined) {
+        if (!opts.boardSnapshot)
+            throw new Error("--board-columns needs --board-snapshot.");
+        const conflicts = [
+            ["--page", opts.page !== undefined], ["--all", opts.all === true],
+            ["--stage", opts.stage !== undefined], ["--stage-name", opts.stageName !== undefined],
+            ["--health-summary", opts.healthSummary === true], ["--health-check", opts.healthCheck !== undefined],
+            ["--health-limit", opts.healthLimit !== undefined], ["--health-offset", opts.healthOffset !== undefined],
+            ["--health-cursor", opts.healthCursor !== undefined], ["--health-rows-only", opts.healthRowsOnly === true],
+        ].filter(([, hit]) => hit).map(([flag]) => flag);
+        if (conflicts.length > 0) {
+            throw new Error(`--board-snapshot cannot be combined with ${conflicts.join(", ")}: it answers every named column's first rows, rows only, from one snapshot.`);
+        }
+        if (opts.pipeline === undefined && opts.pipelineName === undefined)
+            throw new Error("--board-snapshot needs --pipeline or --pipeline-name.");
+        if (opts.boardColumns === undefined)
+            throw new Error("--board-snapshot needs --board-columns <stageId>[:<limit>],...");
+        const perPage = opts.limit === undefined ? 50 : strictIntFlag(opts.limit, "--limit", 1, BOARD_SNAPSHOT_MAX_COLUMN_ROWS);
+        const columns = parseBoardColumnsFlag(opts.boardColumns, perPage);
+        const usp = new URLSearchParams();
+        if (opts.pipeline !== undefined)
+            usp.set("pipeline", opts.pipeline);
+        if (opts.pipelineName !== undefined)
+            usp.set("pipeline_name", opts.pipelineName);
+        if (opts.limit !== undefined)
+            usp.set("per_page", String(perPage));
+        usp.set("board_snapshot", "true");
+        usp.set("board_columns", columns);
+        const answer = await client.get(`/api/v1/deals?${usp.toString()}`);
+        const data = answer?.data;
+        if (!data || !Array.isArray(data.columns) || data.meta?.board_snapshot !== true) {
+            throw new Error("--board-snapshot: the API answered without { columns, meta: { board_snapshot: true } }. Aborting rather than print another shape.");
+        }
+        return answer;
+    }
     // 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 = [

package/package.json

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