@velaro/cli 1.4.98 → 1.4.100

package/bin/velaro.js

@@ -15,6 +15,7 @@ import { knowledgeAdvisorCommand } from '../lib/commands/knowledge-advisor.js';
 import { productCommand }    from '../lib/commands/product.js';
 import { mcpKeyCommand }     from '../lib/commands/mcp-key.js';
 import { opsCommand }        from '../lib/commands/ops.js';
+import { cobrowseCommand }   from '../lib/commands/cobrowse.js';
 import { deployStateCommand } from '../lib/commands/deploy-state.js';
 import { checkCommand }      from '../lib/commands/check.js';
 import { logsCommand }       from '../lib/commands/logs.js';
@@ -26,6 +27,7 @@ import { statusCommand }     from '../lib/commands/status.js';
 import { activityCommand }   from '../lib/commands/activity.js';
 import { ruleCommand }       from '../lib/commands/rule.js';
 import { teamCommand }       from '../lib/commands/team.js';
+import { dynamicsCommand }   from '../lib/commands/dynamics.js';
 import { workflowCommand }   from '../lib/commands/workflow.js';
 import { aiConfigCommand }   from '../lib/commands/ai-config.js';
 import { deploymentCommand } from '../lib/commands/deployment.js';
@@ -39,6 +41,7 @@ import { calendlyCommand }   from '../lib/commands/calendly.js';
 import { copilotStudioCommand } from '../lib/commands/copilotstudio.js';
 import { acuityCommand }     from '../lib/commands/acuity.js';
 import { avatarCommand }     from '../lib/commands/avatar.js';
+import { imageAnalysisCommand } from '../lib/commands/image-analysis.js';
 import { integrationCommand } from '../lib/commands/integration.js';
 import { appointmentsCommand } from '../lib/commands/appointments.js';
 import { bookingCommand } from '../lib/commands/booking.js';
@@ -149,6 +152,7 @@ await yargs(hideBin(process.argv))
   .command(productCommand)
   .command(mcpKeyCommand)
   .command(opsCommand)
+  .command(cobrowseCommand)
   .command(deployStateCommand)
   .command(checkCommand)
   .command(logsCommand)
@@ -160,6 +164,7 @@ await yargs(hideBin(process.argv))
   .command(activityCommand)
   .command(ruleCommand)
   .command(teamCommand)
+  .command(dynamicsCommand)
   .command(workflowCommand)
   .command(aiConfigCommand)
   .command(deploymentCommand)
@@ -173,6 +178,7 @@ await yargs(hideBin(process.argv))
   .command(copilotStudioCommand)
   .command(acuityCommand)
   .command(avatarCommand)
+  .command(imageAnalysisCommand)
   .command(integrationCommand)
   .command(appointmentsCommand)
   .command(bookingCommand)

package/lib/cobrowse-settings.js

@@ -0,0 +1,90 @@
+// Pure helpers for `velaro cobrowse ...` (kept free of I/O so they are unit-testable).
+//
+// The platform API (messaging: GET/PUT superadmin/sites/{siteId}/cobrowse...) has REPLACE semantics: every setting
+// that is not sent goes back to the platform default. For a CLI that is a footgun, so `set` first reads the current
+// raw settings and only overwrites what the operator named on the command line.
+
+export const TRI_FIELDS = [
+  ['cues', 'cuesEnabled'],
+  ['formFill', 'formFillEnabled'],
+  ['strictMask', 'strictMaskMode'],
+  ['disableMobile', 'disableOnMobile'],
+];
+
+/** "on" / "off" / "default" (also true/false) -> true / false / null. Throws on anything else. */
+export function parseTri(value, flag) {
+  if (value === undefined) return undefined;
+  const v = String(value).trim().toLowerCase();
+  if (['on', 'true', 'yes', '1'].includes(v)) return true;
+  if (['off', 'false', 'no', '0'].includes(v)) return false;
+  if (['default', 'inherit', 'null', ''].includes(v)) return null;
+  throw new Error(`--${flag} must be on, off or default (got "${value}")`);
+}
+
+function parseIntOrDefault(value, flag) {
+  if (value === undefined) return undefined;
+  const v = String(value).trim().toLowerCase();
+  if (v === 'default' || v === '') return null;
+  const n = Number(v);
+  if (!Number.isInteger(n)) throw new Error(`--${flag} must be a whole number of minutes or "default" (got "${value}")`);
+  return n;
+}
+
+function parseTextOrDefault(value) {
+  if (value === undefined) return undefined;
+  return String(value).trim().toLowerCase() === 'default' ? null : String(value);
+}
+
+/**
+ * Merge operator flags over the site's current raw settings. Returns the full request body to PUT.
+ * Protected pages: "default" -> platform list, "none" -> no protected pages, otherwise a newline/comma list.
+ */
+export function buildCobrowseUpdate(current, args) {
+  const body = { ...(current ?? {}) };
+  delete body.updatedAt;
+
+  for (const [flag, field] of TRI_FIELDS) {
+    const v = parseTri(args[flag], flag);
+    if (v !== undefined) body[field] = v;
+  }
+
+  if (args.protectedPages !== undefined) {
+    const raw = String(args.protectedPages).trim();
+    const lower = raw.toLowerCase();
+    body.blockedUrlPatterns = lower === 'default' ? null : lower === 'none' ? '' : raw.split(/[\n,]/).map(s => s.trim()).filter(Boolean).join('\n');
+  }
+
+  const max = parseIntOrDefault(args.maxMinutes, 'max-minutes');
+  if (max !== undefined) body.maxSessionMinutes = max;
+  const idle = parseIntOrDefault(args.idleMinutes, 'idle-minutes');
+  if (idle !== undefined) body.idleStopMinutes = idle;
+
+  const title = parseTextOrDefault(args.consentTitle);
+  if (title !== undefined) body.consentTitle = title;
+  const message = parseTextOrDefault(args.consentMessage);
+  if (message !== undefined) body.consentMessage = message;
+  const allow = parseTextOrDefault(args.consentAllow);
+  if (allow !== undefined) body.consentAllowLabel = allow;
+
+  const teams = parseTextOrDefault(args.teams);
+  if (teams !== undefined) body.allowedTeamIds = teams === 'none' ? null : teams;
+  const roles = parseTextOrDefault(args.roles);
+  if (roles !== undefined) body.allowedRoles = roles === 'none' ? null : roles;
+
+  return body;
+}
+
+export function describeEffective(e) {
+  if (!e) return [];
+  return [
+    ['Agent cues', e.cuesEnabled ? 'on' : 'off'],
+    ['Guided form fill', e.formFillEnabled ? 'on' : 'off'],
+    ['Strict mask mode', e.strictMask ? 'on' : 'off'],
+    ['Off on mobile', e.disableOnMobile ? 'yes' : 'no'],
+    ['Protected pages', (e.blockedUrlPatterns ?? []).length ? e.blockedUrlPatterns.join('  ') : 'none'],
+    ['Max session / idle stop', `${e.maxSessionMinutes} min / ${e.idleStopMinutes} min`],
+    ['Who can start', (e.allowedTeamIds ?? []).length || (e.allowedRoles ?? []).length
+      ? `teams [${(e.allowedTeamIds ?? []).join(', ')}] roles [${(e.allowedRoles ?? []).join(', ')}]`
+      : 'everyone with a seat'],
+  ];
+}

package/lib/cobrowse-settings.test.js

@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { buildCobrowseUpdate, parseTri, describeEffective } from './cobrowse-settings.js';
+
+test('parseTri maps on/off/default and rejects anything else', () => {
+  assert.equal(parseTri('on', 'cues'), true);
+  assert.equal(parseTri('OFF', 'cues'), false);
+  assert.equal(parseTri('default', 'cues'), null);
+  assert.equal(parseTri(undefined, 'cues'), undefined);
+  assert.throws(() => parseTri('maybe', 'cues'), /--cues must be on, off or default/);
+});
+
+test('set only changes the flags named; everything else is preserved (the API itself replaces)', () => {
+  const current = { cuesEnabled: true, strictMaskMode: true, maxSessionMinutes: 30, blockedUrlPatterns: '/a\n/b', updatedAt: '2026-10-15T00:00:00Z' };
+  const body = buildCobrowseUpdate(current, { formFill: 'on', maxMinutes: '60' });
+  assert.deepEqual(body, { cuesEnabled: true, strictMaskMode: true, maxSessionMinutes: 60, blockedUrlPatterns: '/a\n/b', formFillEnabled: true });
+});
+
+test('default clears a setting back to the platform default', () => {
+  const body = buildCobrowseUpdate({ cuesEnabled: false, maxSessionMinutes: 30 }, { cues: 'default', maxMinutes: 'default' });
+  assert.equal(body.cuesEnabled, null);
+  assert.equal(body.maxSessionMinutes, null);
+});
+
+test('protected pages: default / none / explicit list', () => {
+  assert.equal(buildCobrowseUpdate({}, { protectedPages: 'default' }).blockedUrlPatterns, null);
+  assert.equal(buildCobrowseUpdate({}, { protectedPages: 'none' }).blockedUrlPatterns, '');
+  assert.equal(buildCobrowseUpdate({}, { protectedPages: '/checkout, /portal/pay ' }).blockedUrlPatterns, '/checkout\n/portal/pay');
+});
+
+test('teams and roles accept "none"', () => {
+  const body = buildCobrowseUpdate({ allowedTeamIds: '1,2', allowedRoles: 'Manager' }, { teams: 'none', roles: 'Agent' });
+  assert.equal(body.allowedTeamIds, null);
+  assert.equal(body.allowedRoles, 'Agent');
+});
+
+test('non-integer minutes are rejected before anything is sent', () => {
+  assert.throws(() => buildCobrowseUpdate({}, { maxMinutes: 'soon' }), /whole number/);
+});
+
+test('describeEffective renders a readable summary', () => {
+  const rows = describeEffective({ cuesEnabled: true, formFillEnabled: false, strictMask: false, disableOnMobile: false, blockedUrlPatterns: ['/checkout'], maxSessionMinutes: 120, idleStopMinutes: 15, allowedTeamIds: [], allowedRoles: [] });
+  assert.ok(rows.some(([k, v]) => k === 'Protected pages' && v === '/checkout'));
+  assert.ok(rows.some(([k, v]) => k === 'Who can start' && v === 'everyone with a seat'));
+});

package/lib/commands/chat-intelligence-topics.js

@@ -4,14 +4,16 @@ import { runCommand } from '../run.js';
 const print = (data) => console.log(JSON.stringify(data, null, 2));
 const list = (v) => (v == null ? [] : String(v).split(',').map((s) => s.trim()).filter(Boolean));
 
-// velaro chat-topics <show|set|template|merge|rename|retire|group|group-suggestions|suggestions|accept|dismiss|
+// velaro chat-topics <show|settings|set|template|merge|rename|retire|group|group-suggestions|suggestions|accept|dismiss|
 //                     reclassify-estimate|reclassify|analysis-estimate|analysis|proposal>
 // REST: messaging /ChatIntelligenceTopics/*  (site comes from the CLI session, never an argument)
 export const chatIntelligenceTopicsCommand = {
   command: 'chat-topics <action>',
   describe: 'Chat Intelligence topics: edit the list, merge/rename/group (no AI cost), suggested topics, optional reclassify and analysis',
   builder: (y) => y
-    .positional('action', { choices: ['show', 'set', 'template', 'merge', 'rename', 'retire', 'group', 'group-suggestions', 'suggestions', 'accept', 'dismiss', 'reclassify-estimate', 'reclassify', 'analysis-estimate', 'analysis', 'proposal'] })
+    .positional('action', { choices: ['show', 'settings', 'set', 'template', 'merge', 'rename', 'retire', 'group', 'group-suggestions', 'suggestions', 'accept', 'dismiss', 'reclassify-estimate', 'reclassify', 'analysis-estimate', 'analysis', 'proposal'] })
+    .option('multi-topic', { type: 'boolean', describe: 'settings: turn multi-topic tracking on (--multi-topic) or off (--no-multi-topic); omit to just show' })
+    .option('re-eval', { type: 'number', describe: 'settings: re-check after N new visitor messages (1-50)' })
     .option('topics', { type: 'string', describe: 'set: comma-separated topic list' })
     .option('industry', { type: 'string', describe: 'template: insurance|healthcare|retail|ecommerce|financial|saas|government|manufacturing' })
     .option('from', { type: 'string', describe: 'merge/rename/retire/group: comma-separated topics' })
@@ -29,6 +31,9 @@ export const chatIntelligenceTopicsCommand = {
     const ops = (op) => messagingPost(`${base}/mapping`, { ops: [{ op, from: list(a.from), to: a.to ?? null, group: a.group ?? null }] });
     switch (a.action) {
       case 'show': return print(await messagingGet(base));
+      case 'settings':
+        if (a.multiTopic == null && a.reEval == null) return print(await messagingGet(`${base}/settings`));
+        return print(await messagingPut(`${base}/settings`, { themeMultiTopicEnabled: a.multiTopic ?? null, themeReEvalEveryNMessages: a.reEval ?? null }));
       case 'set': return print(await messagingPut(base, { topics: list(a.topics) }));
       case 'template': return print(await messagingPost(`${base}/template`, { industry: a.industry }));
       case 'merge': case 'rename': case 'retire': case 'group': return print(await ops(a.action));

package/lib/commands/cobrowse.js

@@ -0,0 +1,99 @@
+import { messagingGet, messagingPut } from '../api.js';
+import { buildCobrowseUpdate, describeEffective } from '../cobrowse-settings.js';
+
+// velaro cobrowse show|set|reset|sessions <siteId>
+//
+// Staff view and control of a site's Co-Browse configuration (what the plan entitles it to, what the site switched
+// on, the effective values after platform defaults and hard caps, and recent session metadata). Goes through the
+// messaging SuperAdmin endpoints, which share ONE validated service with the customer admin UI and the MCP tools,
+// so the CLI cannot store anything the UI cannot, and every change lands in the site's Activity Log.
+
+const RESET = '\x1b[0m';
+const BOLD  = '\x1b[1m';
+const DIM   = '\x1b[2m';
+const GRN   = '\x1b[32m';
+const RED   = '\x1b[31m';
+
+function fmtDate(iso) {
+  if (!iso) return '-';
+  return new Date(iso).toLocaleString('en-US', { timeZone: 'America/Los_Angeles', dateStyle: 'short', timeStyle: 'short' });
+}
+
+const siteArg = (y) => y.positional('siteId', { type: 'number', describe: 'Site id' });
+
+function printSite(data) {
+  const ent = data.entitlements ?? {};
+  const chip = (on) => (on ? `${GRN}yes${RESET}` : `${RED}no${RESET}`);
+  console.log(`\n${BOLD}Co-Browse - site ${data.siteId}${RESET}`);
+  console.log(`  Entitled:  Co-Browse ${chip(ent.coBrowse)}   Plus cues ${chip(ent.cues)}   Plus form fill ${chip(ent.formFill)}   Plus redaction ${chip(ent.enhancedPiiRedaction)}`);
+  console.log(`\n${BOLD}Effective settings${RESET} ${DIM}(null in the raw settings = platform default)${RESET}`);
+  for (const [k, v] of describeEffective(data.effective)) console.log(`  ${k.padEnd(26)} ${v}`);
+}
+
+const showCommand = {
+  command: 'show <siteId>',
+  describe: 'Show entitlement, settings and recent sessions for a site',
+  builder: siteArg,
+  handler: async (argv) => {
+    const data = await messagingGet(`/superadmin/sites/${argv.siteId}/cobrowse`);
+    if (argv.json) return console.log(JSON.stringify(data, null, 2));
+    printSite(data);
+    console.log(`\n${BOLD}Recent sessions${RESET} ${DIM}(metadata only, Pacific time)${RESET}`);
+    const rows = data.recentSessions ?? [];
+    if (rows.length === 0) console.log('  none');
+    for (const s of rows) {
+      console.log(`  ${fmtDate(s.startedAt).padEnd(18)} conv #${String(s.conversationId).padEnd(8)} agent ${String(s.initiatedByUserId ?? '-').padEnd(7)} ${String(s.durationSeconds ?? '-').padStart(5)}s  ${s.outcome ?? '-'}${s.endReason ? ` (${s.endReason})` : ''}`);
+    }
+  },
+};
+
+const setCommand = {
+  command: 'set <siteId>',
+  describe: 'Change Co-Browse settings for a site (only the flags you pass change)',
+  builder: (y) => siteArg(y)
+    .option('cues',            { type: 'string', describe: 'Agent pointer/highlight/annotation (Plus): on | off | default' })
+    .option('form-fill',       { type: 'string', describe: 'Guided form fill (Plus): on | off | default', alias: 'formFill' })
+    .option('strict-mask',     { type: 'string', describe: 'Strict mask mode: on | off | default', alias: 'strictMask' })
+    .option('disable-mobile',  { type: 'string', describe: 'Turn off on mobile: on | off | default', alias: 'disableMobile' })
+    .option('protected-pages', { type: 'string', describe: 'URL patterns (newline/comma separated), "default" or "none"', alias: 'protectedPages' })
+    .option('max-minutes',     { type: 'string', describe: 'Max session minutes (5-240) or default', alias: 'maxMinutes' })
+    .option('idle-minutes',    { type: 'string', describe: 'Idle auto-stop minutes (2-60) or default', alias: 'idleMinutes' })
+    .option('consent-title',   { type: 'string', alias: 'consentTitle' })
+    .option('consent-message', { type: 'string', alias: 'consentMessage' })
+    .option('consent-allow',   { type: 'string', alias: 'consentAllow' })
+    .option('teams',           { type: 'string', describe: 'Comma separated team ids allowed to start, or "none"' })
+    .option('roles',           { type: 'string', describe: 'Comma separated roles allowed to start (Administrator, Manager, Agent), or "none"' }),
+  handler: async (argv) => {
+    const current = await messagingGet(`/superadmin/sites/${argv.siteId}/cobrowse`);
+    const body = buildCobrowseUpdate(current.settings, argv);
+    const saved = await messagingPut(`/superadmin/sites/${argv.siteId}/cobrowse-settings`, body);
+    if (argv.json) return console.log(JSON.stringify(saved, null, 2));
+    console.log(`${GRN}Saved.${RESET} Effective settings now:`);
+    for (const [k, v] of describeEffective(saved.effective)) console.log(`  ${k.padEnd(26)} ${v}`);
+  },
+};
+
+const resetCommand = {
+  command: 'reset <siteId>',
+  describe: 'Reset every Co-Browse setting for a site to the platform defaults',
+  builder: siteArg,
+  handler: async (argv) => {
+    const saved = await messagingPut(`/superadmin/sites/${argv.siteId}/cobrowse-settings`, {});
+    if (argv.json) return console.log(JSON.stringify(saved, null, 2));
+    console.log(`${GRN}Reset to platform defaults.${RESET}`);
+    for (const [k, v] of describeEffective(saved.effective)) console.log(`  ${k.padEnd(26)} ${v}`);
+  },
+};
+
+export const cobrowseCommand = {
+  command: 'cobrowse <subcommand>',
+  describe: 'View and control a site\'s Co-Browse settings and session history',
+  builder: (y) => y
+    .option('json', { type: 'boolean', describe: 'Print raw JSON' })
+    .command(showCommand)
+    .command(setCommand)
+    .command(resetCommand)
+    .demandCommand(1, 'Specify a subcommand: show, set, reset')
+    .strict(),
+  handler: () => {},
+};

package/lib/commands/dynamics.js

@@ -0,0 +1,44 @@
+import { request } from '../api.js';
+import { runCommand } from '../run.js';
+
+// ── velaro dynamics team-overrides ────────────────────────────────────────────
+// Per-team (group) override of Dynamics field mappings + activity type.
+// Effective value = team override ?? the connection's own setting ("apply to all groups" default).
+// Site is resolved server-side from the caller's credentials, never passed by the client.
+
+const base = (config) => `/Dynamics/Configs/${config}/team-overrides`;
+
+export const dynamicsCommand = {
+  command:  'dynamics <subcommand>',
+  describe: 'Dynamics 365 integration settings',
+  builder:  yargs => yargs
+    .command({
+      command:  'team-overrides <action>',
+      describe: 'Per-team overrides of field mappings / activity type (get | set | reset)',
+      builder:  y => y
+        .positional('action', { choices: ['get', 'set', 'reset'] })
+        .option('config',   { type: 'number', demandOption: true, describe: 'Dynamics config id (velaro dynamics config list in the admin UI)' })
+        .option('team',     { type: 'number', describe: 'Team id (required for set/reset; see: velaro team list)' })
+        .option('activity', { type: 'string', describe: 'Activity logical name (e.g. phonecall, task). Empty string = inherit the default.' })
+        .option('mappings', { type: 'string', describe: 'customFieldMappingsJson (JSON array). Empty string = inherit the default.' }),
+      handler:  runCommand(async argv => {
+        if (argv.action === 'get') {
+          const data = await request('GET', base(argv.config));
+          console.log(JSON.stringify(data, null, 2));
+          return;
+        }
+        if (!argv.team) throw new Error('--team is required for set/reset');
+        if (argv.action === 'reset') {
+          console.log(JSON.stringify(await request('DELETE', `${base(argv.config)}/${argv.team}`), null, 2));
+          return;
+        }
+        const body = {};
+        if (argv.activity !== undefined) body.activityLogicalName = argv.activity;
+        if (argv.mappings !== undefined) body.customFieldMappingsJson = argv.mappings;
+        if (!Object.keys(body).length) throw new Error('Pass --activity and/or --mappings (omitted fields are left unchanged).');
+        console.log(JSON.stringify(await request('PUT', `${base(argv.config)}/${argv.team}`, body), null, 2));
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: team-overrides'),
+  handler: () => {},
+};

package/lib/commands/image-analysis.js

@@ -0,0 +1,27 @@
+import { request } from '../api.js';
+import { runCommand } from '../run.js';
+
+// velaro image-analysis limits --site N
+// Shows the Image Analysis (analyze_image) add-on cap and usage for any site (Velaro admin only).
+// To change the cap: velaro support set-limit --site N --key MaxImageAnalysesPerMonth --value 500
+export const imageAnalysisCommand = {
+  command:  'image-analysis <subcommand>',
+  describe: 'Image Analysis add-on limits and usage (Velaro admin only)',
+  builder:  yargs => yargs
+    .command({
+      command:  'limits',
+      describe: 'Show monthly cap, usage this month and per-chat cap for a site',
+      builder:  y => y.option('site', { type: 'number', demandOption: true, describe: 'Site ID' }),
+      handler:  runCommand(async argv => {
+        const d = await request('GET', `/ImageAnalysisLimits/superadmin?siteId=${argv.site}`);
+        const ent = d.entitled === null ? 'unknown' : d.entitled ? 'yes' : 'no';
+        console.log(`\nSite ${argv.site}: Image Analysis`);
+        console.log(`  Entitled:         ${ent}`);
+        console.log(`  Monthly cap:      ${d.monthlyCap} (effective ${d.effectiveMonthlyCap}, hard cap, no automatic overage)`);
+        console.log(`  Used this month:  ${d.usedThisMonth === null ? 'unknown' : d.usedThisMonth}`);
+        console.log(`  Per-chat cap:     ${d.perConversationCap}`);
+        console.log(`  Extra block size: ${d.blockSize}\n`);
+      }),
+    })
+    .demandCommand(1),
+};

package/lib/commands/quality-reports.js

@@ -108,9 +108,10 @@ export const qualityCommand = {
 export const chatIntelligenceThemesCommand = {
   command: 'chat-intelligence',
   describe: 'Chat Intelligence themes, optionally per website/team',
-  builder: (y) => scope(y.option('from', { type: 'string' }).option('to', { type: 'string' }).option('group-by', { type: 'string', default: 'month' })),
+  builder: (y) => scope(y.option('from', { type: 'string' }).option('to', { type: 'string' }).option('group-by', { type: 'string', default: 'month' }).option('include-secondary', { type: 'boolean', default: false, describe: 'Also show secondary topics (needs the site multi-topic setting on)' })),
   handler: runCommand(async (a) => {
     const qs = new URLSearchParams({ groupBy: a.groupBy });
+    if (a.includeSecondary) qs.set('includeSecondary', 'true');
     if (a.from) qs.set('startDate', a.from);
     if (a.to) qs.set('endDate', a.to);
     if (a.deployment != null) qs.set('deploymentId', String(a.deployment));

package/package.json

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