@velaro/cli 1.4.105 → 1.4.106

package/bin/velaro.js

@@ -12,6 +12,7 @@ import { ingestCommand }     from '../lib/commands/ingest.js';
 import { indexMoveCommand }  from '../lib/commands/index-move.js';
 import { safetyCommand }     from '../lib/commands/safety.js';
 import { knowledgeAdvisorCommand } from '../lib/commands/knowledge-advisor.js';
+import { knowledgeCommand } from '../lib/commands/knowledge.js';
 import { productCommand }    from '../lib/commands/product.js';
 import { mcpKeyCommand }     from '../lib/commands/mcp-key.js';
 import { opsCommand }        from '../lib/commands/ops.js';
@@ -63,6 +64,7 @@ import { keywordIntelligenceCommand } from '../lib/commands/keyword-intelligence
 import { aiFieldExtractionCommand } from '../lib/commands/ai-field-extraction.js';
 import { sentimentCommand, qualityCommand, chatIntelligenceThemesCommand } from '../lib/commands/quality-reports.js';
 import { cannedLearningCommand } from '../lib/commands/canned-learning.js';
+import { csatOverrideUnapproveCommand } from '../lib/commands/csat-override.js';
 import { chatIntelligenceTopicsCommand } from '../lib/commands/chat-intelligence-topics.js';
 import { focusCommand }       from '../lib/commands/focus.js';
 import { triageCommand }      from '../lib/commands/triage.js';
@@ -108,6 +110,7 @@ import { supportCommand }           from '../lib/commands/support.js';
 import { routingCommand }           from '../lib/commands/routing.js';
 import { diagnosticsCommand }       from '../lib/commands/diagnostics.js';
 import { aiSpendCommand }           from '../lib/commands/ai-spend.js';
+import { skillUsageCommand }        from '../lib/commands/skill-usage.js';
 import { aiFederationCommand }       from '../lib/commands/ai-federation.js';
 import { statusPageCommand }        from '../lib/commands/status-page.js';
 import { statusNotifyCommand }      from '../lib/commands/status-notify.js';
@@ -116,6 +119,7 @@ import { emailInboxCommand }        from '../lib/commands/email-inbox.js';
 import { callbackCommand }          from '../lib/commands/callback.js';
 import { caseCommand }              from '../lib/commands/case.js';
 import { pickupCommand }            from '../lib/commands/pickup.js';
+import { visitorMonitorCommand }    from '../lib/commands/visitor-monitor.js';
 import { visitorLinkCommand }      from '../lib/commands/visitor-link.js';
 import { applePayCommand }         from '../lib/commands/apple-pay.js';
 import { siteBuilderCommand }        from '../lib/commands/site-builder.js';
@@ -159,6 +163,7 @@ await yargs(hideBin(process.argv))
   .command(indexMoveCommand)
   .command(safetyCommand)
   .command(knowledgeAdvisorCommand)
+  .command(knowledgeCommand)
   .command(productCommand)
   .command(mcpKeyCommand)
   .command(opsCommand)
@@ -213,6 +218,7 @@ await yargs(hideBin(process.argv))
   .command(chatIntelligenceThemesCommand)
   .command(cannedLearningCommand)
   .command(chatIntelligenceTopicsCommand)
+  .command(csatOverrideUnapproveCommand)
   .command(focusCommand)
   .command(triageCommand)
   .command(automationDraftCommand)
@@ -257,6 +263,7 @@ await yargs(hideBin(process.argv))
   .command(routingCommand)
   .command(diagnosticsCommand)
   .command(aiSpendCommand)
+  .command(skillUsageCommand)
   .command(aiFederationCommand)
   .command(statusPageCommand)
   .command(statusNotifyCommand)
@@ -265,6 +272,7 @@ await yargs(hideBin(process.argv))
   .command(callbackCommand)
   .command(caseCommand)
   .command(pickupCommand)
+  .command(visitorMonitorCommand)
   .command(visitorLinkCommand)
   .command(applePayCommand)
   .command(siteBuilderCommand)

package/lib/commands/ai-config.js

@@ -84,7 +84,7 @@ const aiConfigCreateCommand = {
     y
       .option('name',        { type: 'string',  describe: 'Configuration name' })
       .option('prompt',      { type: 'string',  describe: 'System prompt text' })
-      .option('model',       { type: 'string',  describe: 'Model (e.g. gpt-4o-mini, claude-haiku-4-5)' })
+      .option('model',       { type: 'string',  describe: 'Model (e.g. gpt-4o-mini, claude-haiku-5-5)' })
       .option('tone',        { type: 'string',  describe: 'Tone (e.g. friendly, professional)' })
       .option('language',    { type: 'string',  default: 'en', describe: 'Language code' })
       .option('reply-length',{ type: 'string',  describe: 'Reply length (e.g. short, medium, long)' })

package/lib/commands/csat-override.js

@@ -0,0 +1,14 @@
+import { messagingPost } from '../api.js';
+import { runCommand } from '../run.js';
+
+// velaro csat-override-unapprove <id>
+// REST: messaging POST /api/intelligence/csat-override-candidates/{id}/unapprove (site comes from the CLI session)
+export const csatOverrideUnapproveCommand = {
+  command: 'csat-override-unapprove <id>',
+  describe: 'Return an approved Chat Intelligence improvement candidate to Pending (deactivates the override, removes any vectorized copy)',
+  builder: (y) => y.positional('id', { type: 'number', describe: 'Approved override candidate id' }),
+  handler: runCommand(async (a) => {
+    if (!Number.isInteger(a.id) || a.id <= 0) throw new Error('id must be a positive integer');
+    console.log(JSON.stringify(await messagingPost(`/api/intelligence/csat-override-candidates/${a.id}/unapprove`, {}), null, 2));
+  }),
+};

package/lib/commands/knowledge.js

@@ -0,0 +1,114 @@
+// velaro knowledge clinical-text get|set -- emergency and safety wording per channel and language.
+// Backend: velaro-messaging KnowledgeSetupController. Customer routes take the site from auth
+// (GET KnowledgeSetup/state, PUT KnowledgeSetup/clinical-text); --site switches to the staff twins
+// (GET/PUT KnowledgeSetup/Staff/{siteId}/...), Velaro super admin only.
+import fs from 'node:fs';
+import { messagingGet, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+
+const CHANNELS = ['chat', 'voice', 'sms', 'whatsapp', 'email'];
+
+export function basePath(site) {
+  return site ? `/KnowledgeSetup/Staff/${encodeURIComponent(site)}` : '/KnowledgeSetup';
+}
+
+/** Key is default | channel | lang | lang.channel (es.voice). Value is the wording. */
+export function parseEntries(list) {
+  const out = {};
+  for (const raw of [].concat(list ?? [])) {
+    const i = String(raw).indexOf('=');
+    if (i < 1) throw new Error(`Expected key=text (for example es.voice="..."), got: ${raw}`);
+    out[String(raw).slice(0, i).trim().toLowerCase()] = String(raw).slice(i + 1);
+  }
+  return out;
+}
+
+export function buildBody(argv) {
+  if (argv.reset) return { resetToDefault: true };
+  let body = {};
+  if (argv.file) body = JSON.parse(fs.readFileSync(argv.file, 'utf8'));
+  const em = parseEntries(argv.emergency);
+  const rf = parseEntries(argv.referral);
+  if (Object.keys(em).length) body.emergency = { ...(body.emergency ?? {}), ...em };
+  if (Object.keys(rf).length) body.referral = { ...(body.referral ?? {}), ...rf };
+  if (argv['emergency-number'] !== undefined) body.emergencyNumber = argv['emergency-number'];
+  if (argv['service-mode'] !== undefined || argv['service-mode-text'] !== undefined) {
+    body.emergencyServiceMode = {};
+    if (argv['service-mode'] !== undefined) body.emergencyServiceMode.enabled = argv['service-mode'];
+    if (argv['service-mode-text'] !== undefined) body.emergencyServiceMode.text = argv['service-mode-text'];
+    if (argv.confirm) body.emergencyServiceMode.confirm = true;
+  }
+  return body;
+}
+
+export function printState(ct) {
+  console.log(`\nEmergency number: ${ct.overrides?.emergencyNumber || `(default) ${ct.defaultEmergencyNumber}`}`);
+  console.log(`Limits: ${ct.limits?.minLength}-${ct.limits?.maxLength} characters. Emergency text must keep ${ct.placeholder}.`);
+  console.log(`Supported languages: ${(ct.supportedLanguages ?? []).join(', ') || '-'}`);
+  const m = ct.emergencyServiceMode;
+  console.log(`Emergency-service mode: ${m?.enabled ? 'ON' : 'off'}${m?.text ? ` | text: ${m.text}` : ''} (staff only)`);
+  console.log('Custom wording (key = text):');
+  for (const kind of ['emergency', 'referral']) {
+    const e = Object.entries(ct.overrides?.[kind] ?? {});
+    if (!e.length) console.log(`  ${kind}: none, built-in wording`);
+    for (const [k, v] of e) console.log(`  ${kind}.${k} = ${v}`);
+  }
+  console.log('Effective English wording per channel:');
+  for (const c of CHANNELS) {
+    const x = ct.effective?.[c];
+    if (x) console.log(`  ${c}: emergency "${x.emergency}" | referral "${x.referral}"`);
+  }
+}
+
+const clinicalGet = {
+  command: 'get',
+  describe: 'Show emergency/safety wording, supported languages and emergency-service mode',
+  builder: (y) => y
+    .option('site', { type: 'number', describe: 'Target site ID (Velaro staff only; omit for your own site)' })
+    .option('json', { type: 'boolean', default: false }),
+  handler: runCommand(async (argv) => {
+    const state = await messagingGet(`${basePath(argv.site)}/state`);
+    const ct = state?.clinicalText;
+    if (!ct) throw new Error('The setup state did not include clinicalText (backend too old?).');
+    if (argv.json) { console.log(JSON.stringify(ct, null, 2)); return; }
+    printState(ct);
+  }),
+};
+
+const clinicalSet = {
+  command: 'set',
+  describe: 'Set emergency/safety wording. Entries replace the stored set: pass every override you want to keep (use get --json).',
+  builder: (y) => y
+    .option('site', { type: 'number', describe: 'Target site ID (Velaro staff only)' })
+    .option('emergency', { type: 'array', string: true, describe: 'key=text, key is default|chat|voice|sms|whatsapp|email|<lang>|<lang>.<channel>; must contain {emergencyNumber}' })
+    .option('referral', { type: 'array', string: true, describe: 'key=text, same keys as --emergency' })
+    .option('emergency-number', { type: 'string', describe: 'Replaces {emergencyNumber}' })
+    .option('file', { type: 'string', describe: 'JSON body { emergency, referral, emergencyNumber }' })
+    .option('reset', { type: 'boolean', default: false, describe: 'Clear all custom wording' })
+    .option('service-mode', { type: 'boolean', describe: 'Staff only (--site): turn emergency-service mode on/off' })
+    .option('service-mode-text', { type: 'string', describe: 'Staff only: required emergency text for service mode (20-600 chars)' })
+    .option('confirm', { type: 'boolean', default: false, describe: 'Required to turn service mode on' })
+    .option('json', { type: 'boolean', default: false }),
+  handler: runCommand(async (argv) => {
+    const body = buildBody(argv);
+    if (body.emergencyServiceMode && !argv.site) throw new Error('Emergency-service mode is staff only: pass --site <id>.');
+    const r = await messagingPut(`${basePath(argv.site)}/clinical-text`, body);
+    if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
+    console.log(r.changed ? 'Saved.' : 'No change.');
+    if (r.clinicalText) printState(r.clinicalText);
+  }),
+};
+
+export const knowledgeCommand = {
+  command: 'knowledge <subcommand>',
+  describe: 'Knowledge setup safety settings',
+  builder: (y) => y
+    .command({
+      command: 'clinical-text <action>',
+      describe: 'Emergency and safety messages per channel and language',
+      builder: (yy) => yy.command(clinicalGet).command(clinicalSet).demandCommand(1, 'Specify get or set'),
+      handler: () => {},
+    })
+    .demandCommand(1, 'Specify a subcommand: clinical-text'),
+  handler: () => {},
+};

package/lib/commands/skill-usage.js

@@ -0,0 +1,39 @@
+import { messagingGet } from '../api.js';
+import { runCommand } from '../run.js';
+
+const usd = (n) => `$${Number(n ?? 0).toFixed(2)}`;
+
+// Pure formatter so the output shape is unit-testable without a network call.
+export function formatSkillUsage(r) {
+  const lines = [];
+  lines.push(`Site ${r.siteId}, ${r.month}${r.isTrial ? ' (trial)' : ''}, overage: ${r.overageBehavior}`);
+  lines.push('');
+  lines.push('Billable usage (same numbers as the customer Billing page):');
+  for (const u of r.usage ?? []) {
+    const limit = u.unlimited ? 'unlimited' : u.limit.toLocaleString();
+    lines.push(`  ${u.name.padEnd(24)} ${String(u.used.toLocaleString()).padStart(9)} / ${limit.padStart(9)}  ${u.unlimited ? '' : `${u.percent}%`.padStart(5)}  gate: ${u.mode ?? 'n/a'}`);
+  }
+  lines.push('');
+  lines.push('Calls by surface (staff, copilot and composite calls are never billed to the customer):');
+  const surfaces = r.callsBySurface ?? [];
+  if (!surfaces.length) lines.push('  (none recorded)');
+  for (const s of surfaces) lines.push(`  ${String(s.surface).padEnd(20)} ${s.calls.toLocaleString()}`);
+  lines.push('');
+  lines.push('LLM cost this month by key source (BYOK removes this cost only; skill usage above still counts):');
+  const llm = r.llmCostThisMonth ?? [];
+  if (!llm.length) lines.push('  (none logged)');
+  for (const l of llm) lines.push(`  ${String(l.keySource ?? 'unknown').padEnd(12)} ${usd(l.costUsd)} / ${l.calls} calls`);
+  return lines.join('\n');
+}
+
+export const skillUsageCommand = {
+  command: 'skill-usage <siteId>',
+  describe: 'Per-customer skill/integration usage vs plan limits, by surface, with LLM cost split (Velaro staff only)',
+  builder: (y) => y
+    .positional('siteId', { type: 'number', describe: 'Target site ID' })
+    .option('json', { type: 'boolean', default: false }),
+  handler: runCommand(async (argv) => {
+    const r = await messagingGet(`/SupportTools/sites/${argv.siteId}/skill-usage`);
+    console.log(argv.json ? JSON.stringify(r, null, 2) : formatSkillUsage(r));
+  }),
+};

package/lib/commands/teams-phone.js

@@ -4,7 +4,7 @@
  *   velaro teams-phone status                    Show current configuration
  *   velaro teams-phone set --tenant-id ...        Create or update the configuration
  *   velaro teams-phone remove                     Delete the configuration
- *   velaro teams-phone test                       Test the Graph subscription connectivity
+ *   velaro teams-phone test                       Run the inbound-calling readiness checks
  *
  * Backend contract: server/Velaro.Messaging/Controllers/Voice/TeamsPhoneConfigController.cs
  * (velaro-messaging). Site is resolved server-side from the auth context — never
@@ -34,6 +34,9 @@ function printConfig(c) {
   console.log(`  Assigned phone number:           ${c.assignedPhoneNumber ?? '(none)'}`);
   console.log(`  Webhook secret configured:       ${c.webhookSecretConfigured ? `${GRN}yes${RST}` : `${DIM}no${RST}`}`);
   const subColor = c.graphSubscriptionActive ? GRN : YEL;
+  if (typeof c.callingReady === 'boolean') {
+    console.log(`  Inbound calling ready:           ${c.callingReady ? GRN : YEL}${c.callingReady}${RST}`);
+  }
   console.log(`  Graph subscription active:       ${subColor}${c.graphSubscriptionActive}${RST}` +
     (c.graphSubscriptionExpiresAt ? `  (expires ${c.graphSubscriptionExpiresAt})` : ''));
   console.log('');
@@ -82,7 +85,16 @@ async function removeHandler() {
 async function testHandler() {
   const result = await messagingPost('/TeamsPhone/Config/Test', {});
   const color = result?.success ? GRN : RED;
-  console.log(`\n${color}${result?.success ? 'Success' : 'Failed'}${RST}: ${result?.message ?? '(no message)'}\n`);
+  console.log(`\n${color}${result?.success ? 'Success' : 'Failed'}${RST}: ${result?.message ?? '(no message)'}`);
+  if (typeof result?.callingReady === 'boolean') {
+    console.log(`  Inbound calling ready: ${result.callingReady ? GRN : RED}${result.callingReady}${RST}`);
+  }
+  if (Array.isArray(result?.checks)) {
+    for (const ck of result.checks) {
+      console.log(`  ${ck?.ok ? GRN + 'PASS' : RED + 'FAIL'}${RST} ${ck?.name ?? ''}${ck?.message ? ': ' + ck.message : ''}`);
+    }
+  }
+  console.log('');
   if (!result?.success) process.exitCode = 1;
 }
 
@@ -121,7 +133,7 @@ export const teamsPhoneCommand = {
     })
     .command({
       command:  'test',
-      describe: 'Test the Teams Phone connection by creating/renewing the Graph /communications/calls subscription',
+      describe: 'Run the Teams Phone readiness checks (consent, resource account, Graph reachability) and print each check',
       builder:  yy => yy,
       handler:  testHandler,
     })

package/lib/commands/visitor-monitor.js

@@ -0,0 +1,61 @@
+import { messagingGet, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+
+// ── velaro visitor-monitor ────────────────────────────────────────────────────
+// Visitor Monitor view preferences (per user) and site settings. siteId is applied
+// server-side from the JWT (see cli/lib/api.js messagingRequest), never a CLI arg.
+//
+// Backend contract: velaro-messaging VisitorController (PR 2798)
+//   GET/PUT Visitor/preferences  { columns[], groupBy, sortBy, sortDir, regionGrouping }
+//   GET/PUT Visitor/settings     { storeLocationDetail?, activeWindowMinutes? }  (window 5-240; >30 needs Advanced plan, else 403 feature_not_in_plan)
+//   GET     Visitor/active       live sessions + activeWindowMinutes + locationDetailEnabled
+
+const show = data => console.log(JSON.stringify(data, null, 2));
+
+export const visitorMonitorCommand = {
+  command:  'visitor-monitor <subcommand>',
+  describe: 'Visitor Monitor preferences, settings and live visitors',
+  builder:  yargs => yargs
+    .command({
+      command:  'active',
+      describe: 'List live visitors',
+      handler:  runCommand(async () => show(await messagingGet('/Visitor/active'))),
+    })
+    .command({
+      command:  'preferences <action>',
+      describe: 'get or set your saved Visitor Monitor view',
+      builder:  y => y
+        .positional('action', { choices: ['get', 'set'] })
+        .option('columns',         { type: 'string', describe: 'Comma-separated column keys (set)' })
+        .option('group-by',        { type: 'string', describe: 'Group by key (set)' })
+        .option('sort-by',         { type: 'string', describe: 'Sort key (set)' })
+        .option('sort-dir',        { type: 'string', choices: ['asc', 'desc'], describe: 'Sort direction (set)' })
+        .option('region-grouping', { type: 'string', describe: 'region or city (set)' }),
+      handler:  runCommand(async argv => {
+        if (argv.action === 'get') return show(await messagingGet('/Visitor/preferences'));
+        const body = {};
+        if (argv.columns !== undefined) body.columns = String(argv.columns).split(',').map(s => s.trim()).filter(Boolean);
+        if (argv['group-by'] !== undefined) body.groupBy = argv['group-by'];
+        if (argv['sort-by'] !== undefined) body.sortBy = argv['sort-by'];
+        if (argv['sort-dir'] !== undefined) body.sortDir = argv['sort-dir'];
+        if (argv['region-grouping'] !== undefined) body.regionGrouping = argv['region-grouping'];
+        show(await messagingPut('/Visitor/preferences', body));
+      }),
+    })
+    .command({
+      command:  'settings <action>',
+      describe: 'get or set site Visitor Monitor settings',
+      builder:  y => y
+        .positional('action', { choices: ['get', 'set'] })
+        .option('store-location-detail', { type: 'boolean', describe: 'Store region/city + truncated IP (Advanced plan) (set)' })
+        .option('active-window-minutes', { type: 'number', describe: 'Minutes visitors stay listed, 5-240 (above 30 needs Advanced) (set)' }),
+      handler:  runCommand(async argv => {
+        if (argv.action === 'get') return show(await messagingGet('/Visitor/settings'));
+        const body = {};
+        if (argv['store-location-detail'] !== undefined) body.storeLocationDetail = argv['store-location-detail'];
+        if (argv['active-window-minutes'] !== undefined) body.activeWindowMinutes = argv['active-window-minutes'];
+        show(await messagingPut('/Visitor/settings', body));
+      }),
+    })
+    .demandCommand(1),
+};

package/lib/skill-usage.test.js

@@ -0,0 +1,36 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { formatSkillUsage } from './commands/skill-usage.js';
+
+const sample = {
+  siteId: 1032,
+  month: '2026-10',
+  isTrial: true,
+  overageBehavior: 'block',
+  usage: [
+    { metric: 'ai_tool_calls', name: 'AI Tool Calls', used: 120, limit: 500, unlimited: false, percent: 24, mode: 'Enforce' },
+    { metric: 'api_calls', name: 'REST API Calls', used: 9, limit: 0, unlimited: true, percent: 0, mode: 'Observe' },
+  ],
+  callsBySurface: [{ surface: 'McpStaff', calls: 4 }],
+  llmCostThisMonth: [{ keySource: 'byok', costUsd: 1.5, calls: 3 }],
+};
+
+test('shows usage against the limit with the gate mode, and marks unlimited metrics', () => {
+  const out = formatSkillUsage(sample);
+  assert.match(out, /Site 1032, 2026-10 \(trial\), overage: block/);
+  assert.match(out, /AI Tool Calls\s+120 \/\s+500\s+24%\s+gate: Enforce/);
+  assert.match(out, /REST API Calls\s+9 \/\s+unlimited/);
+});
+
+test('lists calls by surface and the LLM cost split, saying BYOK removes LLM cost only', () => {
+  const out = formatSkillUsage(sample);
+  assert.match(out, /McpStaff\s+4/);
+  assert.match(out, /byok\s+\$1\.50 \/ 3 calls/);
+  assert.match(out, /BYOK removes this cost only/);
+});
+
+test('handles a site with no recorded usage without throwing', () => {
+  const out = formatSkillUsage({ siteId: 5, month: '2026-10', overageBehavior: 'warn' });
+  assert.match(out, /\(none recorded\)/);
+  assert.match(out, /\(none logged\)/);
+});

package/package.json

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