@velaro/cli 1.4.65 → 1.4.67

package/lib/commands/experience-impact.js

@@ -12,15 +12,18 @@ export const experienceImpactCommand = {
     .option('from', { type: 'string', describe: 'yyyy-MM-dd (default: 7 days ago)' })
     .option('to', { type: 'string', describe: 'yyyy-MM-dd (default: today)' })
     .option('team-id', { type: 'number', describe: 'Narrow to one team' })
+    .option('include-demo', { type: 'boolean', default: false, describe: 'Show only the seeded sample (demo) data instead of real conversations' })
     .option('json', { type: 'boolean', default: false, describe: 'Raw JSON output' }),
   handler:  runCommand(async (argv) => {
     const qs = new URLSearchParams();
     if (argv.from) qs.set('from', argv.from);
     if (argv.to) qs.set('to', argv.to);
     if (argv.teamId) qs.set('teamId', String(argv.teamId));
+    if (argv.includeDemo) qs.set('includeDemo', 'true');
     const q = qs.toString();
     const d = await messagingGet(`/Reports/experience-impact${q ? `?${q}` : ''}`);
     if (argv.json) { console.log(JSON.stringify(d, null, 2)); return; }
+    if (d.demoAvailable && !argv.includeDemo) console.log('(Sample data is available for this range: re-run with --include-demo)');
     const s = d.summary ?? {};
     console.log(`\nExperience Impact ${d.range?.from}..${d.range?.to}`);
     console.log(`  Experience index: ${s.experienceIndex} / 100`);

package/lib/commands/routing.js

@@ -1,7 +1,7 @@
 import { messagingGet, messagingPut, messagingPost, messagingDel, get as adminGet } from '../api.js';
 import {
   TERMINAL_ACTION_NAMES, buildPolicyUpdate, validatePolicyUpdate, describeChain,
-  describeSimulation, describeTransfers,
+  describeSimulation, describeTransfers, validateAdvancedUpdate,
 } from '../routing-inactivity.js';
 
 // ── helpers ───────────────────────────────────────────────────────────────────
@@ -199,13 +199,24 @@ const policySetCommand = {
     .option('queue-escalation-minutes', { type: 'number', describe: 'Minutes in queue before escalation alert (1-240)' })
     .option('terminal-workflow', { type: 'number', describe: 'Workflow id to run when the terminal action is RunWorkflow' })
     .option('visitor-text', { type: 'string', describe: 'Visitor status text (max 500). Tokens: {{releasedFromAgent}} {{reason}} {{teamName}}' })
-    .option('agent-text', { type: 'string', describe: 'Agent status text (max 500)' }),
+    .option('agent-text', { type: 'string', describe: 'Agent status text (max 500)' })
+    .option('no-typing-after', { type: 'number', describe: 'Advanced: seconds with no agent typing before the stepped-away steps run (10-3600)' })
+    .option('no-typing-message', { type: 'string', describe: 'Advanced: message to the visitor when the agent steps away (max 500)' })
+    .option('no-typing-alert-supervisor', { type: 'boolean', describe: 'Advanced: alert a supervisor when the agent stops typing' })
+    .option('no-typing-reroute', { type: 'boolean', describe: 'Advanced: move the chat to another agent when the agent stops typing' })
+    .option('escalation-team', { type: 'number', describe: 'Advanced: group alerted when the chat stays unattended' })
+    .option('escalation-after', { type: 'number', describe: 'Advanced: seconds unattended before the escalation group is alerted (30-14400)' })
+    .option('terminal-bot', { type: 'number', describe: 'Advanced: bot (AI configuration id) for terminal action ReturnToBot (9)' })
+    .option('apply-to', { type: 'string', choices: ['auto-route', 'queue'], describe: 'Advanced: apply to auto-routing only or the queue only (omit = unchanged)' }),
   handler:  async (argv) => {
     // Load current policy first, then merge
     const current = await messagingGet('/AutoRoutingPolicy');
 
     const updated = buildPolicyUpdate(current, argv);
-    const problems = validatePolicyUpdate(updated);
+    const problems = [
+      ...validatePolicyUpdate(updated),
+      ...validateAdvancedUpdate(updated.advanced, updated.terminalActionOverride, current),
+    ];
     if (problems.length) {
       for (const m of problems) console.error(`  ${RED}x${RESET} ${m}`);
       process.exitCode = 1;

package/lib/routing-inactivity.js

@@ -4,7 +4,7 @@
 // Persisted as ints by messaging (append-only enum); the API accepts and returns the NAME.
 export const TERMINAL_ACTION_NAMES = [
   'Survey', 'CreateTicket', 'SurveyAndCreateTicket', 'Queue', 'OfflineMessage', 'NoOp',
-  'EndChat', 'NotifyManager', 'RunWorkflow',
+  'EndChat', 'NotifyManager', 'RunWorkflow', 'ReturnToBot',
 ];
 
 export function terminalLabel(v) {
@@ -18,7 +18,7 @@ export function terminalForSave(v) {
   if (v === null || v === undefined || v === '') return null;
   if (typeof v === 'number' || /^\d+$/.test(String(v))) {
     const name = TERMINAL_ACTION_NAMES[Number(v)];
-    if (!name) throw new Error(`Unknown terminal action ${v}. Use 0-8: ${TERMINAL_ACTION_NAMES.map((n, i) => `${i}=${n}`).join(' ')}`);
+    if (!name) throw new Error(`Unknown terminal action ${v}. Use 0-9: ${TERMINAL_ACTION_NAMES.map((n, i) => `${i}=${n}`).join(' ')}`);
     return name;
   }
   const hit = TERMINAL_ACTION_NAMES.find(n => n.toLowerCase() === String(v).toLowerCase());
@@ -47,6 +47,72 @@ export const CHAIN_FLAGS = {
  * reassignmentMode is ALWAYS sent (an absent value is treated as Observe by the API and would silently
  * switch reassignment off). The chain block is only sent when the server reports one or a chain flag is set.
  */
+// CLI flag -> AutoRoutingPolicy.advanced field (stepped away / not typing). null on PUT = unchanged.
+export const ADVANCED_FLAGS = {
+  'no-typing-after': 'noTypingAfterSeconds',
+  'no-typing-message': 'noTypingVisitorMessage',
+  'no-typing-alert-supervisor': 'noTypingAlertSupervisor',
+  'no-typing-reroute': 'noTypingReroute',
+  'escalation-team': 'escalationTeamId',
+  'escalation-after': 'escalationAfterSeconds',
+  'terminal-bot': 'terminalBotProfileId',
+  'apply-to': 'applyToRoutingActions',
+};
+
+const APPLY_TO = { acd: 1, 'auto-route': 1, queue: 2 };
+
+/** Returns the `advanced` PUT block for the flags given (others null = unchanged), or null when no advanced flag was passed. */
+export function buildAdvancedUpdate(current, argv) {
+  const given = Object.keys(ADVANCED_FLAGS).filter(f => argv[f] !== undefined);
+  if (!given.length) return null;
+  if (!('advanced' in current)) throw new Error('This messaging build does not report the advanced stepped-away settings yet; they cannot be saved.');
+  const out = Object.fromEntries(Object.values(ADVANCED_FLAGS).map(k => [k, null]));
+  for (const f of given) {
+    let v = argv[f];
+    if (f === 'apply-to') {
+      v = typeof v === 'number' ? v : APPLY_TO[String(v).toLowerCase()];
+      if (v !== 1 && v !== 2) throw new Error('--apply-to must be auto-route or queue. Omit it to leave the setting unchanged.');
+    }
+    out[ADVANCED_FLAGS[f]] = v;
+  }
+  return out;
+}
+
+/** Cross-field/range checks for the advanced block, mirroring the server. Returns a list of messages. */
+export function validateAdvancedUpdate(adv, terminalAction, current) {
+  const errors = [];
+  if (adv) {
+    const i = Number.isInteger;
+    if (adv.noTypingAfterSeconds != null && !(i(adv.noTypingAfterSeconds) && adv.noTypingAfterSeconds >= 10 && adv.noTypingAfterSeconds <= 3600))
+      errors.push('--no-typing-after must be a whole number from 10 to 3600.');
+    if (adv.escalationAfterSeconds != null && !(i(adv.escalationAfterSeconds) && adv.escalationAfterSeconds >= 30 && adv.escalationAfterSeconds <= 14400))
+      errors.push('--escalation-after must be a whole number from 30 to 14400.');
+    if (typeof adv.noTypingVisitorMessage === 'string' && adv.noTypingVisitorMessage.length > 500)
+      errors.push('--no-typing-message must be 500 characters or fewer.');
+    if (adv.escalationAfterSeconds != null && adv.escalationTeamId == null && current?.advanced?.escalationTeamId == null)
+      errors.push('--escalation-after needs --escalation-team <id>.');
+  }
+  if (terminalAction === 'ReturnToBot' && adv?.terminalBotProfileId == null && current?.advanced?.terminalBotProfileId == null)
+    errors.push('Terminal action ReturnToBot needs --terminal-bot <id>.');
+  return errors;
+}
+
+export function describeAdvanced(adv) {
+  if (!adv) return ['  (This messaging build does not report the advanced stepped-away settings.)'];
+  const from = f => (adv.inheritedFrom?.[f] ? ` [from ${adv.inheritedFrom[f]}]` : '');
+  const v = x => (x === null || x === undefined ? 'not set' : x);
+  return [
+    'Advanced (stepped away / not typing):',
+    `  No typing after:     ${adv.noTypingAfterSeconds != null ? `${adv.noTypingAfterSeconds}s` : 'off'}${from('noTypingAfterSeconds')}`,
+    `  Visitor message:     ${v(adv.noTypingVisitorMessage)}${from('noTypingVisitorMessage')}`,
+    `  Alert supervisor:    ${v(adv.noTypingAlertSupervisor)}${from('noTypingAlertSupervisor')}`,
+    `  Move to next agent:  ${v(adv.noTypingReroute)}${from('noTypingReroute')}`,
+    `  Escalation group:    ${v(adv.escalationTeamId)}${adv.escalationAfterSeconds != null ? ` after ${adv.escalationAfterSeconds}s` : ''}${from('escalationTeamId')}`,
+    `  Return-to-bot bot:   ${v(adv.terminalBotProfileId)}${from('terminalBotProfileId')}`,
+    `  Applies to:          ${adv.applyToRoutingActions === 1 ? 'auto-routing only' : adv.applyToRoutingActions === 2 ? 'queue only' : 'auto-routing and queue'}${from('applyToRoutingActions')}`,
+  ];
+}
+
 export function buildPolicyUpdate(current, argv) {
   const merged = { ...current };
   const map = {
@@ -64,7 +130,7 @@ export function buildPolicyUpdate(current, argv) {
     argv['terminal-action'] !== undefined ? argv['terminal-action'] : current.terminalActionOverride
   );
   // Actions 6-8 exist only on a messaging build with the inactivity chain; an older one would store a different value.
-  if (['EndChat', 'NotifyManager', 'RunWorkflow'].includes(merged.terminalActionOverride) && !('inactivityChain' in current))
+  if (['EndChat', 'NotifyManager', 'RunWorkflow', 'ReturnToBot'].includes(merged.terminalActionOverride) && !('inactivityChain' in current))
     throw new Error(`Terminal action ${merged.terminalActionOverride} needs a messaging build with the agent inactivity chain; this one does not report it. Use 0-5.`);
 
   const mode = argv['reassignment-mode'] ?? current.reassignmentMode ?? 'Observe';
@@ -79,6 +145,10 @@ export function buildPolicyUpdate(current, argv) {
     for (const f of patched) chain[CHAIN_FLAGS[f]] = argv[f];
     merged.inactivityChain = chain;
   }
+  // The read-side advanced block carries inheritedFrom; send only the explicit PUT block (or nothing).
+  delete merged.advanced;
+  const adv = buildAdvancedUpdate(current, argv);
+  if (adv) merged.advanced = adv;
   return merged;
 }
 
@@ -117,6 +187,7 @@ export function describeChain(p) {
       `  Terminal workflow:   ${c.terminalWorkflowId ?? 'none'}`,
     );
   }
+  if ('advanced' in p) out.push(...describeAdvanced(p.advanced));
   return out;
 }
 

package/lib/routing-inactivity.test.js

@@ -2,7 +2,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   buildPolicyUpdate, validatePolicyUpdate, terminalForSave, terminalLabel,
-  describeChain, describeSimulation, describeTransfers,
+  describeChain, describeSimulation, describeTransfers, buildAdvancedUpdate, validateAdvancedUpdate, describeAdvanced,
 } from './routing-inactivity.js';
 
 const current = {
@@ -15,7 +15,7 @@ test('terminal action accepts ints and names, rejects junk', () => {
   assert.equal(terminalForSave('7'), 'NotifyManager');
   assert.equal(terminalForSave('runworkflow'), 'RunWorkflow');
   assert.equal(terminalForSave(undefined), null);
-  assert.throws(() => terminalForSave(9), /Unknown terminal action/);
+  assert.throws(() => terminalForSave(10), /Unknown terminal action/);
   assert.throws(() => terminalForSave('Bogus'), /Unknown terminal action/);
   assert.equal(terminalLabel(null), 'Default (Survey)');
   assert.equal(terminalLabel(8), 'RunWorkflow');
@@ -99,3 +99,46 @@ test('describe helpers render the chain, a simulation and a transfer count', ()
   assert.match(describeTransfers({ siteId: 1, days: 30, total: 2, byAgent: [{ agentId: 7, name: 'Sam', count: 2 }], byDay: [] }).join('\n'), /Sam \(id 7\): 2/);
   assert.deepEqual(describeTransfers({ note: 'No agent found' }), ['No agent found']);
 });
+
+const withAdv = { ...current, advanced: { noTypingAfterSeconds: null, inheritedFrom: { noTypingAfterSeconds: 'Default' } } };
+
+test('ReturnToBot is terminal action 9', () => {
+  assert.equal(terminalForSave(9), 'ReturnToBot');
+  assert.equal(terminalForSave('returntobot'), 'ReturnToBot');
+});
+
+test('advanced flags build a PUT block where untouched fields are null (unchanged)', () => {
+  const body = buildPolicyUpdate(withAdv, { 'no-typing-after': 90, 'no-typing-reroute': true, 'apply-to': 'queue' });
+  assert.equal(body.advanced.noTypingAfterSeconds, 90);
+  assert.equal(body.advanced.noTypingReroute, true);
+  assert.equal(body.advanced.applyToRoutingActions, 2);
+  assert.equal(body.advanced.escalationTeamId, null);
+  assert.equal(body.advanced.inheritedFrom, undefined);
+});
+
+test('no advanced flag means the read-side advanced block is not echoed back', () => {
+  const body = buildPolicyUpdate(withAdv, { 'max-reroutes': 4 });
+  assert.equal('advanced' in body, false);
+});
+
+test('advanced flags fail clearly on a messaging build without the block', () => {
+  assert.throws(() => buildPolicyUpdate(current, { 'no-typing-after': 90 }), /does not report the advanced/);
+});
+
+test('advanced validation mirrors the server rules', () => {
+  const adv = buildAdvancedUpdate(withAdv, { 'no-typing-after': 5, 'escalation-after': 10 });
+  const errs = validateAdvancedUpdate(adv, null, withAdv).join(' | ');
+  assert.match(errs, /--no-typing-after/);
+  assert.match(errs, /--escalation-after must be/);
+  assert.match(errs, /needs --escalation-team/);
+  assert.match(validateAdvancedUpdate(null, 'ReturnToBot', withAdv).join(' '), /needs --terminal-bot/);
+  assert.deepEqual(validateAdvancedUpdate(buildAdvancedUpdate(withAdv, { 'terminal-bot': 4 }), 'ReturnToBot', withAdv), []);
+  assert.throws(() => buildAdvancedUpdate(withAdv, { 'apply-to': 'both' }), /--apply-to/);
+});
+
+test('describeAdvanced shows the value and where it is inherited from', () => {
+  const text = describeAdvanced({ noTypingAfterSeconds: 90, inheritedFrom: { noTypingAfterSeconds: 'Team' } }).join('\n');
+  assert.match(text, /No typing after:\s+90s \[from Team\]/);
+  assert.match(describeAdvanced(undefined).join(' '), /does not report/);
+  assert.match(describeChain(withAdv).join('\n'), /Advanced \(stepped away/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.65",
+  "version": "1.4.67",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {