conduyt 1.71.0 → 1.73.0

package/dist/index.js

@@ -3,7 +3,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { addPoolFilterSet, listPoolFilterSets, removePoolFilterSet, updatePoolFilterSet } from "./pool-filter-sets.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { Command, CommanderError } from "commander";
+import { Command, CommanderError, Option } from "commander";
 import { ConduytClient, buildQuery } from "./client.js";
 import { minimumGradeOf, minimumGradePatch, parseGradeFlag } from "./message-check-minimum.js";
 import { splitList, stageRulePatch, validateCardFields, validateRuleChange } from "./board-settings.js";
@@ -2121,6 +2121,10 @@ messages
     })}`);
 }));
 // ---- appointments ----
+/** (app 10-13) a booking can name the deal (card) it came from */
+const APPOINTMENT_DEAL_NOTE = " contactId is looked up as a contact of your account first; when no contact has that id it is looked up as a deal (card), so a deal id may be passed there. dealId names the deal explicitly. A named deal must be open, in your account, and visible AND editable to the key (deals scope; seeing it is not enough): the appointment takes the deal's contact, is linked to the deal, and appointment.booked carries dealId; no other card is created. Errors: 400 deal_id_conflict / deal_contact_mismatch / invalid_deal_id / contact_not_found (contactId is neither a contact nor a deal you can use), 404 deal_not_found / deal_deleted, 403 deal_not_editable (you can see the deal but not change it), 409 deal_closed, 409 deal_contact_gone (the deal's contact was merged or deleted), 409 deal_changed (the deal moved to another contact while booking: retry the request).";
+/** (app 10-13) the catalog does not carry automation action config: find_opportunity v2, link_appointment_to_deal, update_deal_field systemField source */
+const DEAL_NODES_NOTE = " Deal nodes: find_opportunity config {version: 2, pipelineIds (ordered; the first pipeline holding a match wins; empty = every pipeline), status (open default | won | lost | abandoned | any), excludeSources (lead sources never matched, case-insensitive), excludeCreatedByAutomationIds (automations whose create_deal cards are skipped; cards created from 2026-10-13 on), matchField {fieldKey, value} (searches the WHOLE WORKSPACE, any contact, for the card whose deal custom field equals the value, merge fields allowed e.g. {{trigger.oes}}; a card is found when its field holds the searched value (trimmed) as the same text exactly (no case folding); a value written with separators such as dashes or spaces also matches its digits as text; it matches a stored number only when the value (or those digits) is a plain number with no leading zero and at most 15 significant digits that a number holds exactly (007 is text and does not match the number 7; a 16-digit value, 1e-400 or 3e-324 is text only); booleans and differently formatted stored values never match; status, pipelines and exclusions still apply; exactly one match is found, several are ambiguous and take not found; a found card becomes the run's contact when the run has none; the field must exist; an empty rendered value finds nothing), resolution}: searches the run's contact's cards; FOUND makes the card the run's deal and follows nextIfTrue (else next), NOT FOUND is a normal outcome that follows nextIfFalse (else next) and leaves the run's existing deal unchanged; without version 2 the step keeps the original single-pipeline lookup (a miss fails the step). Prerequisite: a version 2 find needs step cursors on this workspace; publishing refuses (find_needs_step_cursors) with \"Find opportunity needs step cursors on this workspace; ask support\", so a workflow can validate and import yet fail at publish; every version 2 find must hold its own live step cursor or it hard-stops the run without selecting or routing. A version 2 find cannot be retried on its own: retrying a failed one alone answers 409, so re-trigger the automation for the contact. An automation definition that touches deals needs the `deals` scope on an API key (403 without it). link_appointment_to_deal config {stageId, pipelineId (needs stageId), lostReason}: in an appointment-triggered run, links the trigger's appointment to the run's deal (its appointment fields follow it; a newer booking is never displaced; the appointment must be the deal's contact's), then optionally moves the card; it needs an appointment trigger and the run's deal (find_opportunity first, or a booking made with a deal id). update_deal_field config {systemField: \"source\", value, overwriteExisting}: sets the deal's own lead source instead of a custom field (a value only, trimmed, at most 500 characters; overwriteExisting false writes only while the source is the Unknown label).";
 const appointments = program.command("appointments").description("Manage appointments");
 appointments
     .command("list")
@@ -2154,13 +2158,14 @@ appointments
 }));
 appointments
     .command("create")
-    .description("Create an appointment. --start/--end must be ISO-8601 WITH a timezone offset (e.g. 2026-07-10T15:00:00-07:00)")
+    .description("Create an appointment. --start/--end must be ISO-8601 WITH a timezone offset (e.g. 2026-07-10T15:00:00-07:00)." + APPOINTMENT_DEAL_NOTE)
     .option("--title <title>", "title (required)")
     .option("--start <iso>", "start time, ISO-8601 with tz offset (required)")
     .option("--end <iso>", "end time, ISO-8601 with tz offset (required)")
     .option("--description <text>", "description")
     .option("--calendar <id>", "calendar UUID")
-    .option("--contact <id>", "contact UUID")
+    .option("--contact <id>", "contact UUID, or a deal UUID (looked up as a deal when no contact has it)")
+    .option("--deal <id>", "deal UUID: book for this deal (card; open, visible and editable to you); the appointment takes its contact and is linked to it")
     .option("--assigned <id>", "assignee user UUID")
     .option("--location <location>", "location")
     .option("--status <status>", "status (default confirmed)")
@@ -2179,6 +2184,8 @@ appointments
         body.calendarId = opts.calendar;
     if (opts.contact !== undefined)
         body.contactId = opts.contact;
+    if (opts.deal !== undefined)
+        body.dealId = opts.deal;
     if (opts.assigned !== undefined)
         body.assignedTo = opts.assigned;
     if (opts.location !== undefined)
@@ -2331,13 +2338,13 @@ automations
 }));
 automations
     .command("validate")
-    .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). Card ownership per lane: assign_to_user config {userId | userIds (round robin) | groupId, target|applyTo: contact|deal|both, overwriteExisting, laneSource, lanePipelineId, laneStageId}: laneSource names a card lane (the Deal.source its Auto-Create step wrote, e.g. \"GSM\", max 500 chars) and makes the deal leg assign the contact's newest OPEN card from that lane (inside lanePipelineId when set) instead of the run's deal; when the contact has none and lanePipelineId is set, the card is created there (laneStageId, else the pipeline's first stage) already owned by the user; lanePipelineId or laneStageId without laneSource, or laneStageId without lanePipelineId, is refused; a lane never applies to an Assign-to-contact step. create_deal config {pipelineId (required), stageId, dealName, dealValue, allowDuplicates, status, source, assignedTo, leaveUnassigned}: leaveUnassigned true leaves the card unassigned when no assignee is set (default false: the card goes to the lead's owner). close_other_open_deals config {lostReason (required)}: closes the contact's OTHER open cards as lost with that reason, keeping the run's own card (each moves to its pipeline's lost stage with the usual stage-change effects; cards already won/lost, in the DPP Post-Close pipeline or in a pipeline with no lost stage are skipped; a re-run closes nothing twice); it needs the run's own deal, so use a deal trigger or a find_opportunity step first." + AUTOMATION_KEY_REFUSALS_NOTE)
+    .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). Card ownership per lane: assign_to_user config {userId | userIds (round robin) | groupId, target|applyTo: contact|deal|both, overwriteExisting, laneSource, lanePipelineId, laneStageId}: laneSource names a card lane (the Deal.source its Auto-Create step wrote, e.g. \"GSM\", max 500 chars) and makes the deal leg assign the contact's newest OPEN card from that lane (inside lanePipelineId when set) instead of the run's deal; when the contact has none and lanePipelineId is set, the card is created there (laneStageId, else the pipeline's first stage) already owned by the user; lanePipelineId or laneStageId without laneSource, or laneStageId without lanePipelineId, is refused; a lane never applies to an Assign-to-contact step. create_deal config {pipelineId (required), stageId, dealName, dealValue, allowDuplicates, status, source, assignedTo, leaveUnassigned}: leaveUnassigned true leaves the card unassigned when no assignee is set (default false: the card goes to the lead's owner). close_other_open_deals config {lostReason (required)}: closes the contact's OTHER open cards as lost with that reason, keeping the run's own card (each moves to its pipeline's lost stage with the usual stage-change effects; cards already won/lost, in the DPP Post-Close pipeline or in a pipeline with no lost stage are skipped; a re-run closes nothing twice); it needs the run's own deal, so use a deal trigger or a find_opportunity step first." + DEAL_NODES_NOTE + AUTOMATION_KEY_REFUSALS_NOTE)
     .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. 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). Card ownership per lane: assign_to_user config {userId | userIds (round robin) | groupId, target|applyTo: contact|deal|both, overwriteExisting, laneSource, lanePipelineId, laneStageId}: laneSource names a card lane (the Deal.source its Auto-Create step wrote, e.g. \"GSM\", max 500 chars) and makes the deal leg assign the contact's newest OPEN card from that lane (inside lanePipelineId when set) instead of the run's deal; when the contact has none and lanePipelineId is set, the card is created there (laneStageId, else the pipeline's first stage) already owned by the user; lanePipelineId or laneStageId without laneSource, or laneStageId without lanePipelineId, is refused; a lane never applies to an Assign-to-contact step. create_deal config {pipelineId (required), stageId, dealName, dealValue, allowDuplicates, status, source, assignedTo, leaveUnassigned}: leaveUnassigned true leaves the card unassigned when no assignee is set (default false: the card goes to the lead's owner). close_other_open_deals config {lostReason (required)}: closes the contact's OTHER open cards as lost with that reason, keeping the run's own card (each moves to its pipeline's lost stage with the usual stage-change effects; cards already won/lost, in the DPP Post-Close pipeline or in a pipeline with no lost stage are skipped; a re-run closes nothing twice); it needs the run's own deal, so use a deal trigger or a find_opportunity step first." + AUTOMATION_KEY_REFUSALS_NOTE)
+    .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). Card ownership per lane: assign_to_user config {userId | userIds (round robin) | groupId, target|applyTo: contact|deal|both, overwriteExisting, laneSource, lanePipelineId, laneStageId}: laneSource names a card lane (the Deal.source its Auto-Create step wrote, e.g. \"GSM\", max 500 chars) and makes the deal leg assign the contact's newest OPEN card from that lane (inside lanePipelineId when set) instead of the run's deal; when the contact has none and lanePipelineId is set, the card is created there (laneStageId, else the pipeline's first stage) already owned by the user; lanePipelineId or laneStageId without laneSource, or laneStageId without lanePipelineId, is refused; a lane never applies to an Assign-to-contact step. create_deal config {pipelineId (required), stageId, dealName, dealValue, allowDuplicates, status, source, assignedTo, leaveUnassigned}: leaveUnassigned true leaves the card unassigned when no assignee is set (default false: the card goes to the lead's owner). close_other_open_deals config {lostReason (required)}: closes the contact's OTHER open cards as lost with that reason, keeping the run's own card (each moves to its pipeline's lost stage with the usual stage-change effects; cards already won/lost, in the DPP Post-Close pipeline or in a pipeline with no lost stage are skipped; a re-run closes nothing twice); it needs the run's own deal, so use a deal trigger or a find_opportunity step first." + DEAL_NODES_NOTE + AUTOMATION_KEY_REFUSALS_NOTE)
     .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")
@@ -2365,7 +2372,7 @@ automations
 }));
 automations
     .command("publish <id>")
-    .description("Publish a draft workflow to live. The API binds a publish to the draft you reviewed and answers 409 without its configRevision, so this reads GET /automations/<id> and POSTs its configRevision as expectedConfigRevision (--expected-config-revision N uses the revision you reviewed and skips the read; a draft changed since then is refused 409). A draft holding an action config key the action does not read, or an unregistered action type, is refused 422 with code unknown_action_config_key / unknown_action_type listed in data.errors (with a \"Did you mean\" suggestion); the error text prints the whole refusal")
+    .description("Publish a draft workflow to live. The API binds a publish to the draft you reviewed and answers 409 without its configRevision, so this reads GET /automations/<id> and POSTs its configRevision as expectedConfigRevision (--expected-config-revision N uses the revision you reviewed and skips the read; a draft changed since then is refused 409). A draft holding an action config key the action does not read, or an unregistered action type, is refused 422 with code unknown_action_config_key / unknown_action_type listed in data.errors (with a \"Did you mean\" suggestion); the error text prints the whole refusal. A workflow with a find_opportunity version 2 step is refused 422 find_needs_step_cursors unless the workspace has step cursors (\"Find opportunity needs step cursors on this workspace; ask support\"); validate and import do not check this")
     .option("--expected-config-revision <n>", "the configRevision of the draft you reviewed (from `automations` read / GET /automations/<id>); omit to read the current one")
     .action(run(async (client, id, opts) => {
     assertUuid(id, "automation id");
@@ -2663,57 +2670,104 @@ companies
 }));
 // ---- tags ----
 // ---- saved filters (personal, Velocify-style) ----
+// Smart View icons (app branch fable/smart-view-icons): the 30 current ids in picker order. The API also accepts 17 legacy ids as
+// deprecated inputs (saved as the mapped new id); they are deliberately not listed here.
+const SMART_VIEW_ICON_IDS = [
+    "heart", "star", "trophy", "badge", "target", "eye", "clock", "hourglass", "siren", "bolt",
+    "fire", "rain", "funnel", "pyramid", "flag", "pin", "push-pin", "thumbs-up", "thumbs-down", "coffee",
+    "rocket", "number-1", "number-2", "number-3", "number-4", "number-5", "number-6", "number-7", "number-8", "number-9",
+];
+const SMART_VIEW_ICON_HELP = (omitted) => `the view's icon, one of (picker order): ${SMART_VIEW_ICON_IDS.join(", ")}. ${omitted}. Legacy icon ids are accepted but saved as the new id; anything else is 400 invalid_icon`;
+const SAVED_FILTER_ENTITY_ERROR = "saved filters are contact Smart Views; --entity is no longer supported";
+function rejectEntity(body) {
+    if ("entity" in body || "entityType" in body)
+        throw new Error(SAVED_FILTER_ENTITY_ERROR);
+}
+/** saved-filters update/delete take a Smart View id, but the generic routes also edit/delete SHARED views for admin keys: read the view first and
+ *  refuse anything that is not one of the caller's personal views (the GET is the only request made in the refusal path). A missing view throws the server's reason. */
+async function requirePersonalSmartView(client, id) {
+    const res = (await client.get(`/api/v1/smart-views/${encodeURIComponent(id)}`));
+    if (res?.data?.isPersonal !== true) {
+        throw new Error("this is a shared Smart View; saved filters are personal views only (use `conduyt api PATCH /smart-views/<id> --body '{...}'` or `conduyt api DELETE /smart-views/<id>`)");
+    }
+}
 const savedFilters = program
     .command("saved-filters")
     .description("Manage YOUR personal saved contact filters (the web app's Saved dropdown; requires the 'saved-filters' key scope)");
 savedFilters
     .command("list")
-    .description("List your saved filters")
-    .option("--entity <type>", "entity type (default contact)")
-    .action(run(async (client, opts) => client.get(`/api/v1/saved-filters${buildQuery({ entity_type: opts.entity })}`)));
+    .description("List your saved filters: your PERSONAL Smart Views (GET /smart-views, every page, filtered to isPersonal). The printed id is the Smart View id that update and delete take")
+    .action(run(async (client) => {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const first = (await client.get("/api/v1/smart-views?counts=false"));
+        const rows = [...first.data.data];
+        let meta = first.data.meta;
+        let shifted = false;
+        for (let page = 2; meta.has_more && page <= 50; page += 1) {
+            const next = (await client.get(`/api/v1/smart-views?page=${page}&counts=false`));
+            if (next.data.meta.order_stamp !== first.data.meta.order_stamp) {
+                shifted = true;
+                break;
+            }
+            rows.push(...next.data.data);
+            meta = next.data.meta;
+        }
+        if (!shifted)
+            return rows.filter((v) => v.isPersonal === true);
+    }
+    throw new Error("Smart Views kept changing while they were listed; try again.");
+}));
 savedFilters
     .command("create")
-    .description("Save a named filter (grouped payload via --filters JSON)")
+    .description("Save a named filter (a personal Smart View, private to you; grouped payload via --filters JSON)")
     .option("--name <name>", "display name (required, unique per user, max 60 chars)")
     .option("--filters <json>", `grouped filter payload JSON, e.g. [{"conjunction":"AND","rules":[{"field":"source","operator":"equals","value":"facebook"}]}]`)
     .option("--sort-field <field>", "sort field (default createdAt)")
     .option("--sort-order <dir>", "asc | desc (default desc)")
-    .option("--entity <type>", "entity type (default contact)")
-    .option("--json <json>", "full JSON body, merged over the flags")
+    .addOption(new Option("--entity <type>", "removed").hideHelp()) // not in the help; passing it exits with SAVED_FILTER_ENTITY_ERROR instead of being ignored
+    .option("--icon <id>", SMART_VIEW_ICON_HELP("Omitted: heart (the default)"))
+    .option("--json <json>", "full JSON body, merged over the flags (may carry `icon`: same ids, same default and same 400 invalid_icon as --icon)")
     .action(run(async (client, opts) => {
+    if (opts.entity !== undefined)
+        throw new Error(SAVED_FILTER_ENTITY_ERROR);
     const body = {};
     if (opts.name !== undefined)
         body.name = opts.name;
+    if (opts.icon !== undefined)
+        body.icon = opts.icon;
     if (opts.filters !== undefined)
         body.filters = jsonArrayArg(opts.filters, "--filters");
     if (opts.sortField !== undefined)
         body.sortField = opts.sortField;
     if (opts.sortOrder !== undefined)
         body.sortOrder = opts.sortOrder;
-    if (opts.entity !== undefined)
-        body.entityType = opts.entity;
     if (opts.json !== undefined)
         Object.assign(body, jsonArg(opts.json, "--json"));
+    rejectEntity(body);
     // A --json merge can clobber filters with a non-array; re-assert the
     // shape after ALL merges so a malformed payload fails locally.
     if (body.filters !== undefined && !Array.isArray(body.filters)) {
         throw new Error("filters must be a JSON ARRAY (grouped payload or flat rules).");
     }
-    return client.post("/api/v1/saved-filters", body);
+    // a saved filter IS a personal Smart View (saved-filters write routes retired 2026-09-24, 410): personal:true keeps it private for every key
+    return client.post("/api/v1/smart-views", { ...body, personal: true });
 }));
 savedFilters
     .command("update <id>")
-    .description("Rename a saved filter or replace its filters/sort (owner-only)")
+    .description("Rename a saved filter (a personal Smart View) or replace its filters/sort (owner-only). The id must be one of YOUR personal views (see `saved-filters list`); a shared Smart View id is refused after one GET, nothing is changed (edit a shared view with `conduyt api PATCH /smart-views/<id> --body '{...}'`)")
     .option("--name <name>", "new display name")
     .option("--filters <json>", "grouped filter payload JSON")
     .option("--sort-field <field>", "sort field")
     .option("--sort-order <dir>", "asc | desc")
-    .option("--json <json>", "full JSON body, merged over the flags")
+    .option("--icon <id>", SMART_VIEW_ICON_HELP("Omitted: unchanged"))
+    .option("--json <json>", "full JSON body, merged over the flags (may carry `icon`: same ids and same 400 invalid_icon as --icon)")
     .action(run(async (client, id, opts) => {
     assertUuid(id, "saved filter id");
     const body = {};
     if (opts.name !== undefined)
         body.name = opts.name;
+    if (opts.icon !== undefined)
+        body.icon = opts.icon;
     if (opts.filters !== undefined)
         body.filters = jsonArrayArg(opts.filters, "--filters");
     if (opts.sortField !== undefined)
@@ -2722,18 +2776,21 @@ savedFilters
         body.sortOrder = opts.sortOrder;
     if (opts.json !== undefined)
         Object.assign(body, jsonArg(opts.json, "--json"));
+    rejectEntity(body);
     // Same post-merge shape assertion as create — see above.
     if (body.filters !== undefined && !Array.isArray(body.filters)) {
         throw new Error("filters must be a JSON ARRAY (grouped payload or flat rules).");
     }
-    return client.patch(`/api/v1/saved-filters/${encodeURIComponent(id)}`, body);
+    await requirePersonalSmartView(client, id);
+    return client.patch(`/api/v1/smart-views/${encodeURIComponent(id)}`, body);
 }));
 savedFilters
     .command("delete <id>")
-    .description("Delete one of your saved filters (owner-only)")
+    .description("Delete one of your saved filters (a personal Smart View; owner-only). The id must be one of YOUR personal views (see `saved-filters list`); a shared Smart View id is refused after one GET, nothing is deleted (delete a shared view with `conduyt api DELETE /smart-views/<id>`)")
     .action(run(async (client, id) => {
     assertUuid(id, "saved filter id");
-    return client.del(`/api/v1/saved-filters/${encodeURIComponent(id)}`);
+    await requirePersonalSmartView(client, id);
+    return client.del(`/api/v1/smart-views/${encodeURIComponent(id)}`);
 }));
 const tags = program.command("tags").description("Manage tags");
 tags
@@ -5226,7 +5283,7 @@ reports
     .command("deliveries <sid>")
     .description("The delivery history of a schedule with download URLs")
     .action(run(async (client, sid) => { assertUuid(sid, "schedule id"); return client.get(`/api/v1/reports/subscriptions/${sid}/deliveries`); }));
-const smartViews = program.command("smart-views").description("Smart Views and their Smart Dialing priorities");
+const smartViews = program.command("smart-views").description(`Smart Views and their Smart Dialing priorities. Creating or updating a view (conduyt api POST /smart-views, PATCH /smart-views/<id>, or saved-filters create/update) takes an optional icon, one of (picker order): ${SMART_VIEW_ICON_IDS.join(", ")}. heart is the default on create. Legacy icon ids are accepted but saved as the new id; anything else is 400 invalid_icon`);
 smartViews
     .command("list")
     .description("List Smart Views in sidebar order (= Smart Dialing priority) with lead counts, audience (groupId / members / isPersonal) and dialing settings")

package/package.json

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