callkaro-cli-unofficial 0.4.0 → 0.5.0

package/dist/commands/workflows.js

@@ -0,0 +1,458 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflowsSchemaCommand = workflowsSchemaCommand;
+exports.workflowsListCommand = workflowsListCommand;
+exports.workflowsGetCommand = workflowsGetCommand;
+exports.workflowsCreateCommand = workflowsCreateCommand;
+exports.workflowsImportCommand = workflowsImportCommand;
+exports.workflowsUpdateCommand = workflowsUpdateCommand;
+exports.workflowsValidateCommand = workflowsValidateCommand;
+exports.workflowsExportCommand = workflowsExportCommand;
+exports.workflowsDuplicateCommand = workflowsDuplicateCommand;
+exports.workflowsDeleteCommand = workflowsDeleteCommand;
+exports.workflowsLeadsCommand = workflowsLeadsCommand;
+exports.workflowsLeadCommand = workflowsLeadCommand;
+exports.workflowsRunCommand = workflowsRunCommand;
+exports.workflowsJourneyCommand = workflowsJourneyCommand;
+exports.workflowsAddNodeCommand = workflowsAddNodeCommand;
+exports.workflowsSetNodeCommand = workflowsSetNodeCommand;
+exports.workflowsRemoveNodeCommand = workflowsRemoveNodeCommand;
+exports.workflowsConnectCommand = workflowsConnectCommand;
+exports.workflowsDisconnectCommand = workflowsDisconnectCommand;
+const fs_1 = require("fs");
+const session_1 = require("../lib/session");
+const ui_1 = require("../lib/ui");
+const edit = __importStar(require("../lib/workflowEdit"));
+const jsonInput_1 = require("./jsonInput");
+const HANGUP_REASONS = [
+    'CLIENT_INITIATED', 'PARTICIPANT_REMOVED', 'SESSION_TIMEOUT', 'VOICEMAIL_DETECTED', 'USER_REJECTED',
+    'USER_UNAVAILABLE', 'USER_UNRESPONSIVE', 'INVALID_PHONE_NUMBER', 'UNKNOWN', 'OUTSIDE_TRIGGER_WINDOW',
+    'DELETED_SCH_CALL_ALL', 'DELETED_SCH_CALL_ONE', 'NO_SLOTS_AVAILABLE', 'PRE_CALL_FN_FAILED', 'DUPLICATE_IDENTITY',
+    'SERVER_SHUTDOWN', 'ROOM_DELETED', 'STATE_MISMATCH', 'JOIN_FAILURE', 'MIGRATION', 'SIGNAL_CLOSE', 'ROOM_CLOSED',
+    'SIP_TRUNK_FAILURE',
+];
+const NODE_REFERENCE = `Workflow graph: { "nodes": [...], "edges": [...] }
+
+Every node: { id (unique), type, name, x, y }. Exactly one "start"; at least one
+"end" must be reachable from it. Nothing may lead into start or out of an end.
+
+Node types — required fields, then a sample (x/y optional)
+These are the only types; the dashboard's Add Node menu offers exactly these:
+  End = end · Send Call = send-call · Send WhatsApp Template = wa-template ·
+  Send WhatsApp Message = wa-message · Wait = wait · Conditions = conditions ·
+  API Call — Basic = api-basic · API Call — Advanced = api-advanced ·
+  Update Contact = update-lead   (Start is created with the workflow, never added)
+
+  start         {"id":"start-1","type":"start","name":"Start","x":320,"y":180}
+  end           {"id":"end-1","type":"end","name":"End","x":2400,"y":180}
+
+  send-call     agentId; optional retries, retryGapMinutes, retryGaps[]
+    {"id":"call-1","type":"send-call","name":"Send Call","agentId":"6ab2c0aa04d91efaa62cebba","retries":0,"retryGapMinutes":30,"retryGaps":[]}
+
+  wait          minutes (>= 1)
+    {"id":"wait-1","type":"wait","name":"Wait","minutes":2}
+
+  wa-template   templateId, templateName, languageCode, templateBody, parameters[],
+                phoneNumberId, displayPhoneNumber, provider ("whatsapp")
+    {"id":"wat-1","type":"wa-template","name":"WhatsApp Template","provider":"whatsapp","templateId":"2167373513730912","templateName":"hello_world","languageCode":"en_US","templateBody":"Welcome!","parameters":[],"phoneNumberId":"1251245231415392","displayPhoneNumber":"917943495456"}
+
+  wa-message    message, phoneNumberId, displayPhoneNumber, parameters[], provider
+    {"id":"wam-1","type":"wa-message","name":"WhatsApp Message","provider":"whatsapp","phoneNumberId":"1251245231415392","displayPhoneNumber":"917943495456","message":"Hello, how are you?","parameters":[]}
+
+  api-basic     url (+ optional method, headers, parameters, bodyFields)
+    {"id":"api-1","type":"api-basic","name":"API Call","method":"POST","url":"https://example.com/hook"}
+
+  api-advanced  code  (one function; everything is on "context")
+    {"id":"fn-1","type":"api-advanced","name":"Custom Function","code":"async function handler(context) {\\n  // context.call_metadata.lead_id\\n}"}
+
+  update-lead   updates: [{ attribute, source, value }]   (source as for conditions;
+                static_value takes the literal in "value")
+    {"id":"upd-1","type":"update-lead","name":"Update Lead","updates":[{"attribute":"age","source":"static_value","value":"20"}]}
+
+  conditions    exits: [{ id, label, next:"", condition?: { source, field, op, value } }]
+                the exit WITHOUT a condition is the fallback (label "otherwise");
+                each exit id is the fromHandle of its edge
+    {"id":"cond-1","type":"conditions","name":"Conditions","exits":[
+      {"id":"o_1","label":"long call","next":"","condition":{"source":"call_duration","field":"","op":"gt","value":"5"}},
+      {"id":"o_2","label":"otherwise","next":""}]}
+
+Edges: { id, from, fromHandle, to }
+  fromHandle is "out" for every node except conditions, where it is the exit's id.
+  A handle with no edge is legal (the run ends there).
+  One edge per (from, fromHandle); "to" is a node id.
+    {"id":"e1","from":"start-1","fromHandle":"out","to":"wait-1"}
+    {"id":"e2","from":"cond-1","fromHandle":"o_1","to":"wam-1"}     (conditions exit "o_1")
+    {"id":"e3","from":"cond-1","fromHandle":"o_2","to":"end-1"}     (conditions exit "o_2")
+
+Unique ids: every node id must be unique across the whole graph (duplicates are
+rejected). Keep edge ids and conditions exit ids unique too — a type-timestamp
+pattern works: "wait-1791233332977", "edge-1791233336426", "o_muvq4qid1".
+Edges refer to nodes by these ids, so never rename an id without updating its edges.
+
+Condition ops:      eq ne contains gt lt empty not_empty
+Condition sources:  contact post_call_variables call_metadata fn_response
+                    static_value  (need "field")
+                    phone_number connected_call voicemail hangup_reason
+                    call_duration conversion_status  (no field)
+
+wa-template "parameters": one row per template variable, { key, source, value }.
+  key is ORIGIN::token, e.g. "BODY::{{1}}", "HEADER::{{1}}", "HEADER::MEDIA",
+  "BUTTON_URL[0]::{{1}}". source is as for conditions (contact -> value is a CRM
+  attribute name; static_value -> value is the literal). Media rows use static_value.
+    {"key":"BODY::{{1}}","source":"contact","value":"first_name"}
+
+hangup_reason values: ${HANGUP_REASONS.join(' ')}
+conversion_status: compare with "true" (converted) or "false" (not converted).
+post_call_variables: field = the agent's post-call variable name: the "name" of each entry in
+  postcall[] (skip type call_drop_off_reason). postcall is on the VERSION: take publishedVersionId
+  from  cku agents get <agentId> --json  then  cku agents get <agentId> --versions <versionId> --json
+fn_response: field = "<apiNodeId>.returned.<key>", e.g. "api-basic-1791233000000.returned.data.id";
+  the keys under "returned" are whatever that API/function returns.
+  A node's own result, "<apiNodeId>.success", says whether it ran without error.
+
+Real ids -- never invent them:
+  agentId                    cku agents list
+  phoneNumberId / display    cku whatsapp list
+  templateId, name, language cku chat-agents templates   (cku chat-agents template <id> prints
+                             the exact variables[].id to use as parameters[].key)
+  CRM attribute names        cku contacts attributes list
+Check a file with:  cku workflows validate --file graph.json
+Real example:       cku workflows get <id> --json`;
+/** Accepts a bare graph, { graph }, or an exported { data: { graph } } file. */
+function graphFrom(parsed) {
+    const graph = parsed?.data?.graph ?? parsed?.graph ?? parsed;
+    if (!graph || !Array.isArray(graph.nodes)) {
+        throw new Error('Expected a graph with a "nodes" array (and "edges"). See `cku workflows schema`.');
+    }
+    return { nodes: graph.nodes, edges: Array.isArray(graph.edges) ? graph.edges : [] };
+}
+async function readJson(arg, file) {
+    const input = await (0, jsonInput_1.resolveJsonInput)(arg, file);
+    try {
+        return (0, jsonInput_1.parseJsonInput)(input);
+    }
+    catch (error) {
+        throw new Error(`Input is not valid JSON: ${error.message}${(0, jsonInput_1.jsonHelpTip)(input.raw, input.fromShell)}`);
+    }
+}
+function output(value, opts, label) {
+    if (opts.file) {
+        (0, fs_1.writeFileSync)(opts.file, JSON.stringify(value, null, 2));
+        (0, ui_1.success)(`Saved ${label} to ${opts.file}`);
+        return true;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(value, null, 2));
+        return true;
+    }
+    return false;
+}
+const date = (value) => (value ? new Date(String(value)).toLocaleDateString('en-US') : '');
+function printErrors(errors) {
+    for (const e of errors)
+        console.error(`  ${e.nodeId ? `[${e.nodeId}] ` : ''}${e.message}`);
+}
+function workflowsSchemaCommand() {
+    console.log(NODE_REFERENCE);
+}
+async function workflowsListCommand(opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const { workflows } = await api.listWorkflows(opts.search);
+        if (output(workflows, opts, 'workflows'))
+            return;
+        if (!workflows.length)
+            return void (0, ui_1.info)('No workflows yet.');
+        (0, ui_1.table)(['ID', 'NAME', 'NODES', 'UPDATED'], workflows.map((w) => [w._id, w.workFlowName, w.graph?.nodes?.length ?? 0, date(w.updatedAt)]));
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function workflowsGetCommand(id, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const wf = await api.getWorkflow(id);
+        if (output(wf, opts, 'workflow'))
+            return;
+        (0, ui_1.keyValue)({ ID: wf._id, Name: wf.workFlowName, Updated: date(wf.updatedAt) });
+        const nodes = wf.graph?.nodes ?? [];
+        const edges = wf.graph?.edges ?? [];
+        console.log();
+        (0, ui_1.table)(['NODE ID', 'TYPE', 'NAME', 'NEXT'], nodes.map((n) => [
+            n.id,
+            n.type,
+            n.name ?? '',
+            edges
+                .filter((e) => e.from === n.id)
+                .map((e) => (e.fromHandle === 'out' ? e.to : `${e.fromHandle}→${e.to}`))
+                .join(', '),
+        ]));
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function workflowsCreateCommand(name, json, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const graph = json || opts.file ? graphFrom(await readJson(json, opts.file)) : undefined;
+        const wf = await api.createWorkflow({ workFlowName: name, graph });
+        (0, ui_1.success)(`Workflow "${wf.workFlowName}" created (${wf._id}).`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function workflowsImportCommand(json, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const parsed = await readJson(json, opts.file);
+        const name = opts.name || parsed?.data?.workFlowName || parsed?.workFlowName;
+        if (!name)
+            throw new Error('The file has no workFlowName; pass --name.');
+        const wf = await api.createWorkflow({ workFlowName: name, graph: graphFrom(parsed) });
+        (0, ui_1.success)(`Workflow "${wf.workFlowName}" imported (${wf._id}).`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function workflowsUpdateCommand(id, json, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        if (!opts.name && !json && !opts.file) {
+            throw new Error('Nothing to update: pass --name and/or a graph via --file or @file.');
+        }
+        const graph = json || opts.file ? graphFrom(await readJson(json, opts.file)) : undefined;
+        const wf = await api.updateWorkflow(id, { workFlowName: opts.name, graph });
+        (0, ui_1.success)(`Workflow "${wf.workFlowName}" updated.`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/** Validate a local graph file, or a saved workflow by id. */
+async function workflowsValidateCommand(id, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const graph = id ? (await api.getWorkflow(id)).graph : graphFrom(await readJson(undefined, opts.file));
+        const { valid, errors } = await api.validateWorkflowGraph(graph);
+        if (valid)
+            return void (0, ui_1.success)('Graph is valid.');
+        (0, ui_1.fail)(`${errors.length} problem(s):`);
+        printErrors(errors);
+        process.exitCode = 1;
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/** Same payload as the dashboard's Export, so it round-trips through `import`. */
+async function workflowsExportCommand(id, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const wf = await api.getWorkflow(id);
+        const payload = {
+            type: 'callkaro_workflow',
+            version: 1,
+            exportedAt: new Date().toISOString(),
+            data: { workFlowName: wf.workFlowName, type: 'normal', graph: wf.graph ?? { nodes: [], edges: [] } },
+        };
+        if (opts.file) {
+            (0, fs_1.writeFileSync)(opts.file, JSON.stringify(payload, null, 2));
+            return void (0, ui_1.success)(`Saved workflow to ${opts.file}`);
+        }
+        console.log(JSON.stringify(payload, null, 2));
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function workflowsDuplicateCommand(id, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const wf = await api.duplicateWorkflow(id, opts.name);
+        (0, ui_1.success)(`Duplicated as "${wf.workFlowName}" (${wf._id}).`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function workflowsDeleteCommand(id, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        if (!opts.yes) {
+            const wf = await api.getWorkflow(id);
+            if (!(await (0, ui_1.confirm)(`Delete workflow "${wf.workFlowName}"? This cannot be undone.`, opts.yes)))
+                return;
+        }
+        await api.deleteWorkflow(id);
+        (0, ui_1.success)('Workflow deleted.');
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function workflowsLeadsCommand(id, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const res = await api.listWorkflowLeads(id, { search: opts.search, page: opts.page, pageSize: opts.pageSize });
+        if (output(res, opts, 'leads'))
+            return;
+        (0, ui_1.info)(Object.entries(res.counts || {})
+            .map(([k, v]) => `${k}: ${v}`)
+            .join('  ') || 'No leads yet.');
+        if (!res.leads.length)
+            return;
+        (0, ui_1.table)(['PHONE', 'LEAD ID', 'STATUS', 'AT STEP', 'CALLS', 'RUN ID'], res.leads.map((l) => [l.phone, l.lead_id ?? '', l.status, l.current_step ?? '', l.total_calls ?? 0, l.run_id]));
+        const p = res.pagination;
+        (0, ui_1.info)(`Page ${p.page}/${p.totalPages || 1} — ${p.totalDocs} lead(s)${p.hasNext ? '  (use --page to see more)' : ''}`);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function workflowsLeadCommand(id, phone, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const summary = await api.getWorkflowLead(id, phone);
+        if (output(summary, opts, 'lead'))
+            return;
+        (0, ui_1.keyValue)(Object.fromEntries(Object.entries(summary).map(([k, v]) => [k, typeof v === 'object' ? JSON.stringify(v) : v])));
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/** The lead's latest run, step by step: why it went the way it did. */
+async function workflowsRunCommand(id, phone, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const detail = await api.getWorkflowRunByPhone(id, phone);
+        if (output(detail, opts, 'run'))
+            return;
+        const { run, steps } = detail;
+        (0, ui_1.keyValue)({
+            Run: run.run_id,
+            Phone: run.phone_number,
+            Status: run.status,
+            'Current node': run.current_node_id,
+            'Next node': run.next_node_id || undefined,
+            'Resumes at': run.resume_at && !String(run.resume_at).startsWith('1970') ? run.resume_at : undefined,
+            Started: run.started_at,
+        });
+        console.log();
+        (0, ui_1.table)(['#', 'AT', 'NODE', 'ACTION', 'STATUS', 'HANDLE', 'ERROR'], steps.map((s) => [s.seq, s.createdAt, s.node_name || s.node_id, s.action ?? '', s.status, s.handle ?? '', s.error ?? '']));
+        (0, ui_1.info)("Use --json for each step's action_results and the run variables.");
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function workflowsJourneyCommand(id, phone, opts) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const { calls } = await api.workflowJourney(id, phone);
+        if (output(calls, opts, 'calls'))
+            return;
+        if (!calls.length)
+            return void (0, ui_1.info)('No calls to or from this number in this workflow.');
+        (0, ui_1.table)(['CALL ID', 'AT', 'STATUS', 'DURATION', 'HANGUP'], calls.map((c) => [c._id, c.createdAt ?? c.time ?? '', c.status ?? '', c.call_duration ?? '', c.hangup_reason ?? '']));
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+/** Read the saved graph, apply one edit, save. The server's validation is the final word. */
+async function editGraph(id, apply) {
+    const api = (0, session_1.requireApi)();
+    try {
+        const wf = await api.getWorkflow(id);
+        if (wf.type && wf.type !== 'normal')
+            throw new Error('This workflow is deprecated and cannot be edited.');
+        const graph = {
+            nodes: JSON.parse(JSON.stringify(wf.graph?.nodes ?? [])),
+            edges: JSON.parse(JSON.stringify(wf.graph?.edges ?? [])),
+        };
+        const summary = apply(graph);
+        await api.updateWorkflow(id, { graph });
+        (0, ui_1.success)(summary);
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+const num = (v) => (v === undefined ? undefined : Number(v));
+async function workflowsAddNodeCommand(id, opts) {
+    let fields;
+    try {
+        fields = opts.set ? await readJson(opts.set, undefined) : undefined;
+    }
+    catch (err) {
+        return (0, ui_1.handleError)(err);
+    }
+    await editGraph(id, (g) => edit.addNode(g, { ...opts, set: fields, x: num(opts.x), y: num(opts.y) }));
+}
+async function workflowsSetNodeCommand(id, nodeId, opts) {
+    try {
+        const fields = opts.set ? await readJson(opts.set, undefined) : {};
+        if (opts.name)
+            fields.name = opts.name;
+        if (!Object.keys(fields).length)
+            throw new Error('Nothing to change: pass --set <json> and/or --name.');
+        await editGraph(id, (g) => edit.setNode(g, nodeId, fields));
+    }
+    catch (err) {
+        (0, ui_1.handleError)(err);
+    }
+}
+async function workflowsRemoveNodeCommand(id, nodeId, opts) {
+    try {
+        if (!(await (0, ui_1.confirm)(`Remove node "${nodeId}" and its edges?`, opts.yes)))
+            return;
+    }
+    catch (err) {
+        return (0, ui_1.handleError)(err);
+    }
+    await editGraph(id, (g) => edit.removeNode(g, nodeId, opts.reconnect));
+}
+async function workflowsConnectCommand(id, opts) {
+    await editGraph(id, (g) => edit.connect(g, opts.from, opts.to, opts.handle));
+}
+async function workflowsDisconnectCommand(id, opts) {
+    await editGraph(id, (g) => edit.disconnect(g, opts.from, opts.handle));
+}

package/dist/index.js

@@ -27,6 +27,8 @@ const ongoing_1 = require("./commands/ongoing");
 const transcribers_1 = require("./commands/transcribers");
 const voices_1 = require("./commands/voices");
 const secrets_1 = require("./commands/secrets");
+const workflows_1 = require("./commands/workflows");
+const contacts_1 = require("./commands/contacts");
 const skills_1 = require("./commands/skills");
 const update_1 = require("./commands/update");
 const analytics_1 = require("./commands/analytics");
@@ -326,6 +328,100 @@ secrets.command('remove <name>').description('remove a secret')
     .option('--yes', 'skip confirmation').action(secrets_1.secretsRemoveCommand);
 secrets.command('rename <oldName> <newName>').description('rename a secret without changing its value')
     .action(secrets_1.secretsRenameCommand);
+// --- workflows -------------------------------------------------------------
+const workflows = program.command('workflows').description('manage workflows (graphs of calls, WhatsApp, waits, conditions)');
+workflows.command('schema').description('print the workflow graph JSON reference (node types, fields, edges)').action(workflows_1.workflowsSchemaCommand);
+workflows.command('list').description('list workflows').option('--search <text>', 'filter by name').option('--json', 'output raw JSON').option('--file <path>', 'save JSON to a file').action(workflows_1.workflowsListCommand);
+workflows.command('get <id>').description('show a workflow and its nodes').option('--json', 'output the full workflow as JSON').option('--file <path>', 'save JSON to a file').action(workflows_1.workflowsGetCommand);
+workflows.command('create <name> [json]').description('create a workflow, optionally from a graph JSON').option('--file <path>', 'read the graph from a file').action(workflows_1.workflowsCreateCommand);
+workflows.command('import [json]').description('create a workflow from an exported workflow file').option('--file <path>', 'read JSON from a file').option('--name <name>', 'override the workflow name').action(workflows_1.workflowsImportCommand);
+workflows.command('update <id> [json]').description('rename a workflow and/or replace its graph').option('--name <name>', 'new name').option('--file <path>', 'read the new graph from a file').action(workflows_1.workflowsUpdateCommand);
+workflows.command('validate [id]').description('check a graph (saved workflow id, or --file) without saving').option('--file <path>', 'read the graph from a file').action(workflows_1.workflowsValidateCommand);
+workflows.command('export <id>').description('export a workflow as a re-importable JSON file').option('--file <path>', 'write to a file instead of stdout').action(workflows_1.workflowsExportCommand);
+workflows.command('duplicate <id>').description('copy a workflow').option('--name <name>', 'name for the copy').action(workflows_1.workflowsDuplicateCommand);
+workflows.command('delete <id>').description('delete a workflow').option('--yes', 'skip confirmation').action(workflows_1.workflowsDeleteCommand);
+workflows.command('leads <id>').description('leads enrolled in a workflow and where each one is').option('--search <text>', 'phone number or lead id').option('--page <n>', 'page number').option('--page-size <n>', 'page size (max 200)').option('--json', 'output raw JSON').option('--file <path>', 'save JSON to a file').action(workflows_1.workflowsLeadsCommand);
+workflows.command('lead <id> <phone>').description("one lead's call totals and enrolment time in a workflow").option('--json', 'output raw JSON').option('--file <path>', 'save JSON to a file').action(workflows_1.workflowsLeadCommand);
+workflows.command('run <id> <phone>').description("a lead's latest run, step by step").option('--json', 'full detail incl. step results and variables').option('--file <path>', 'save JSON to a file').action(workflows_1.workflowsRunCommand);
+workflows.command('journey <id> <phone>').description('every call to or from a number inside this workflow').option('--json', 'output raw JSON').option('--file <path>', 'save JSON to a file').action(workflows_1.workflowsJourneyCommand);
+workflows.command('add-node <id>').description('add a node; with --after it is spliced into the chain after that node').requiredOption('--type <type>', 'send-call | wa-template | wa-message | wait | conditions | api-basic | api-advanced | update-lead | end').option('--name <name>', 'node name').option('--set <json>', 'extra fields as JSON or @file.json, e.g. \'{"minutes":5}\'').option('--after <nodeId>', 'insert after this node').option('--handle <handle>', 'which branch of --after (conditions exit id)').option('--x <n>', 'canvas x').option('--y <n>', 'canvas y').action(workflows_1.workflowsAddNodeCommand);
+workflows.command('set-node <id> <nodeId>').description("change a node's fields (merged; id and type are fixed)").option('--set <json>', 'fields as JSON or @file.json').option('--name <name>', 'rename').action(workflows_1.workflowsSetNodeCommand);
+workflows.command('remove-node <id> <nodeId>').description('remove a node and its edges').option('--reconnect', 'link what led into it to what it led to').option('--yes', 'skip confirmation').action(workflows_1.workflowsRemoveNodeCommand);
+workflows.command('connect <id>').description('link a node to another (replaces any existing link from that handle)').requiredOption('--from <nodeId>', 'source node').requiredOption('--to <nodeId>', 'target node').option('--handle <handle>', 'source branch (conditions exit id); default "out"').action(workflows_1.workflowsConnectCommand);
+workflows.command('disconnect <id>').description('remove the link leaving a node (or one of its branches)').requiredOption('--from <nodeId>', 'source node').option('--handle <handle>', 'source branch (conditions exit id)').action(workflows_1.workflowsDisconnectCommand);
+// --- contacts (CRM) --------------------------------------------------------
+const contacts = program.command('contacts').description('manage CRM contacts, attributes, imports, exports and assignment');
+contacts.command('list').description('list contacts (filters match the dashboard)')
+    .option('--search <text>', 'match phone number or text')
+    .option('--channel <channel>', 'filter by channel')
+    .option('--attr <name=value>', 'attribute filter (repeatable)', contacts_1.collect, [])
+    .option('--last-message-state <state>', 'read | delivered | sent | failed | clicked | not_clicked')
+    .option('--created-from <YYYY-MM-DD>', 'created on/after (IST)')
+    .option('--created-to <YYYY-MM-DD>', 'created on/before (IST)')
+    .option('--updated-from <YYYY-MM-DD>', 'updated on/after (IST)')
+    .option('--updated-to <YYYY-MM-DD>', 'updated on/before (IST)')
+    .option('--page <n>', 'page number')
+    .option('--page-size <n>', 'page size (max 50)')
+    .option('--columns <a,b>', 'attribute columns to show')
+    .option('--assigned-to-me', 'only contacts whose conversations are assigned to you')
+    .option('--json', 'output raw JSON').option('--file <path>', 'save JSON to a file')
+    .action(contacts_1.contactsListCommand);
+contacts.command('get <phone>').description('show one contact and its attributes').option('--json', 'output raw JSON').option('--file <path>', 'save JSON to a file').action(contacts_1.contactsGetCommand);
+contacts.command('create <phone>').description('create a contact (or merge into an existing one)').option('--attr <name=value>', 'attribute value (repeatable)', contacts_1.collect, []).option('--channel <channel>', 'channel (repeatable)', contacts_1.collect, []).action(contacts_1.contactsCreateCommand);
+contacts.command('update <phone>').description('set or clear attribute values on a contact').option('--attr <name=value>', 'attribute value (repeatable)', contacts_1.collect, []).option('--clear <name>', 'clear an attribute (repeatable)', contacts_1.collect, []).action(contacts_1.contactsUpdateCommand);
+contacts.command('delete <phone>').description('delete a contact').option('--yes', 'skip confirmation').action(contacts_1.contactsDeleteCommand);
+contacts.command('upload <csv>').description('import contacts from a CSV (needs a phone_number column; other columns must be defined attributes)').option('--ignore-unknown', 'drop columns that are not defined attributes instead of refusing').action(contacts_1.contactsUploadCommand);
+contacts.command('export').description('export contacts to CSV (same filters as list)')
+    .option('--search <text>', 'match phone number or text')
+    .option('--channel <channel>', 'filter by channel')
+    .option('--attr <name=value>', 'attribute filter (repeatable)', contacts_1.collect, [])
+    .option('--last-message-state <state>', 'read | delivered | sent | failed | clicked | not_clicked')
+    .option('--created-from <YYYY-MM-DD>', 'created on/after (IST)')
+    .option('--created-to <YYYY-MM-DD>', 'created on/before (IST)')
+    .option('--updated-from <YYYY-MM-DD>', 'updated on/after (IST)')
+    .option('--updated-to <YYYY-MM-DD>', 'updated on/before (IST)')
+    .option('--fields <a,b>', 'columns to include (base fields and/or attribute names)')
+    .option('--email <address>', 'email the export instead of downloading (required above 5000 rows)')
+    .option('--file <path>', 'write CSV to a file instead of stdout')
+    .action(contacts_1.contactsExportCommand);
+contacts.command('assign').description('add contacts to a workflow (--workflow) or call them with a voice agent (--agent)')
+    .option('--phones <a,b>', 'specific phone numbers; otherwise the filters below select the set')
+    .option('--search <text>', 'match phone number or text')
+    .option('--channel <channel>', 'filter by channel')
+    .option('--attr <name=value>', 'attribute filter (repeatable)', contacts_1.collect, [])
+    .option('--last-message-state <state>', 'read | delivered | sent | failed | clicked | not_clicked')
+    .option('--created-from <YYYY-MM-DD>', 'created on/after (IST)')
+    .option('--created-to <YYYY-MM-DD>', 'created on/before (IST)')
+    .option('--updated-from <YYYY-MM-DD>', 'updated on/after (IST)')
+    .option('--updated-to <YYYY-MM-DD>', 'updated on/before (IST)')
+    .option('--workflow <id>', 'workflow to enroll into')
+    .option('--agent <id>', 'voice agent to call with')
+    .option('--name <name>', 'batch / enrollment name')
+    .option('--language <code>', 'language (default en)')
+    .option('--at <ISO>', 'start later at this time')
+    .option('--window <HH:MM-HH:MM>', 'daily trigger window')
+    .option('--retries <n>', 'retries (voice agent only)')
+    .option('--gaps <m,m>', 'minutes between retries (voice agent only)')
+    .option('--carry-over', 'carry unfinished calls over to the next day')
+    .option('--priority <n>', 'batch priority')
+    .option('--force', 'workflow: restart contacts that are already running')
+    .option('--dry-run', 'show who would be assigned and where; start nothing')
+    .option('--yes', 'skip confirmation when assigning all contacts')
+    .action(contacts_1.contactsAssignCommand);
+const attributes = contacts.command('attributes').description('manage the CRM attribute definitions contacts can hold');
+attributes.command('list').description('list attribute definitions').option('--json', 'output raw JSON').option('--file <path>', 'save JSON to a file').action(contacts_1.attributesListCommand);
+attributes.command('set <name>').description('create an attribute, or change only the given fields of an existing one')
+    .option('--type <type>', 'string | description | enum | number | date | boolean | datetime | time | array | object')
+    .option('--label <text>', 'display name')
+    .option('--description <text>', 'description')
+    .option('--options <a,b>', 'allowed values (enum)')
+    .option('--manual-only', 'AI/functions may not update it').option('--ai-updatable', 'AI/functions may update it')
+    .option('--required', 'make required').option('--optional', 'make optional')
+    .option('--hidden', 'hide on screen').option('--visible', 'show on screen')
+    .option('--default-mode <mode>', 'drop | type_default | custom (value for imports that omit it)')
+    .option('--default-value <value>', 'default when mode is custom')
+    .action(contacts_1.attributesSetCommand);
+attributes.command('delete <name>').description('delete an attribute definition (values on contacts are kept, hidden)').option('--yes', 'skip confirmation').action(contacts_1.attributesDeleteCommand);
 // --- agents ----------------------------------------------------------------
 const agents = program.command('agents').description('manage voice agents');
 agents.command('list').description('list all your agents')
@@ -690,20 +786,23 @@ const sim = program.command('sim').description('agent simulations & test cases')
 sim.command('tests <agentId>').description('list test cases').option('--json', 'raw JSON').action(simulations_1.simTestsListCommand);
 sim.command('create <agentId>').description('create a test case')
     .option('--name <name>', 'test case name')
+    .option('--persona <text>', 'who the simulated caller is')
     .option('--prompt <text>', 'simulated user prompt')
     .option('--criteria <text>', 'success criteria')
-    .option('--model <model>', 'test LLM model')
+    .option('--model <model>', 'test LLM model (default: platform default; see `cku sim models`)')
     .option('--variables <json|@file>', 'testVariables: a JSON object of name -> value (non-strings are stringified)')
     .option('--functions <json|@file>', 'function mocks: a JSON array of {"name": ..., "response": ...}')
     .action(simulations_1.simCreateCommand);
 sim.command('update <testCaseId>').description('edit a test case (only the fields you pass are sent)')
     .option('--name <name>', 'test case name')
+    .option('--persona <text>', 'who the simulated caller is')
     .option('--prompt <text>', 'simulated user prompt')
     .option('--criteria <text>', 'success criteria')
     .option('--model <model>', 'test LLM model')
     .option('--variables <json|@file>', 'testVariables: replaces the whole map')
     .option('--functions <json|@file>', 'function mocks: replaces the whole list')
     .action(simulations_1.simUpdateCommand);
+sim.command('models').description('models that can play the simulated caller').option('--json', 'raw JSON').action(simulations_1.simModelsCommand);
 sim.command('delete <testCaseId>').description('delete a test case').option('--yes', 'skip confirmation')
     .action(simulations_1.simDeleteCommand);
 sim.command('run <agentId>').description('run a batch simulation (async)')