@velaro/cli 1.4.73 → 1.4.75

package/bin/velaro.js

@@ -46,7 +46,12 @@ import { reportBackfillCommand } from '../lib/commands/report-backfill.js';
 import { staffCommand } from '../lib/commands/staff.js';
 import { reportExplainCommand } from '../lib/commands/report-explain.js';
 import { conversationEfficiencyCommand } from '../lib/commands/conversation-efficiency.js';
+import { executiveInsightsCommand } from '../lib/commands/executive-insights.js';
 import { dbCommand } from '../lib/commands/db.js';
+import { skillRoutingCommand } from '../lib/commands/skill-routing.js';
+import { keywordIntelligenceCommand } from '../lib/commands/keyword-intelligence.js';
+import { aiFieldExtractionCommand } from '../lib/commands/ai-field-extraction.js';
+import { sentimentCommand, qualityCommand, chatIntelligenceThemesCommand } from '../lib/commands/quality-reports.js';
 import { focusCommand }       from '../lib/commands/focus.js';
 import { triageCommand }      from '../lib/commands/triage.js';
 import { automationDraftCommand } from '../lib/commands/automation-draft.js';
@@ -147,6 +152,7 @@ await yargs(hideBin(process.argv))
   .command(bookingCommand)
   .command(reportCommand)
   .command(conversationEfficiencyCommand)
+  .command(executiveInsightsCommand)
   .command(scheduleAdherenceCommand)
   .command(experienceImpactCommand)
   .command(reportSubscriptionCommand)
@@ -154,6 +160,12 @@ await yargs(hideBin(process.argv))
   .command({ command: 'staff', desc: 'Velaro staff: cross-site tools (backfill)', builder: staffCommand, handler: () => {} })
   .command(reportExplainCommand)
   .command(dbCommand)
+  .command(skillRoutingCommand)
+  .command(keywordIntelligenceCommand)
+  .command(aiFieldExtractionCommand)
+  .command(sentimentCommand)
+  .command(qualityCommand)
+  .command(chatIntelligenceThemesCommand)
   .command(focusCommand)
   .command(triageCommand)
   .command(automationDraftCommand)

package/lib/commands/ai-field-extraction.js

@@ -0,0 +1,106 @@
+import { messagingGet, messagingPost, messagingPut, messagingDel } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro ai-field-extraction -------------------------------------------------------
+// Post-resolve AI field extraction settings and agent corrections
+// (velaro-messaging /AiFieldExtraction/*). Site comes from auth.
+
+const print = (data) => console.log(JSON.stringify(data, null, 2));
+
+const get = {
+  command: 'get',
+  describe: 'Show the extraction config',
+  handler: runCommand(async () => print(await messagingGet('/AiFieldExtraction/Config'))),
+};
+
+const FLAG_KEYS = {
+  enabled: 'Enabled',
+  extractLineOfBusiness: 'ExtractLineOfBusiness',
+  extractIntent: 'ExtractIntent',
+  extractState: 'ExtractState',
+  extractIdentifiers: 'ExtractIdentifiers',
+  createThemeTags: 'CreateThemeTags',
+};
+
+// Partial update: only fields the caller passed are sent.
+function body(a) {
+  const b = {};
+  for (const [key, pascal] of Object.entries(FLAG_KEYS)) {
+    if (a[key] !== undefined) b[pascal] = a[key];
+  }
+  if (a.monthlyCap !== undefined) b.MonthlyCap = a.monthlyCap;
+  if (a.minConfidence !== undefined) b.MinConfidence = a.minConfidence;
+  return b;
+}
+
+const builder = (y) => {
+  y.option('enabled', { type: 'boolean', describe: 'Opt-in switch (default off)' });
+  y.option('extract-line-of-business', { type: 'boolean' });
+  y.option('extract-intent', { type: 'boolean' });
+  y.option('extract-state', { type: 'boolean' });
+  y.option('extract-identifiers', { type: 'boolean' });
+  y.option('create-theme-tags', { type: 'boolean' });
+  y.option('monthly-cap', { type: 'number', describe: '1..50000' });
+  y.option('min-confidence', { type: 'number', describe: '0..1' });
+  return y;
+};
+
+const create = {
+  command: 'create',
+  describe: 'Create the extraction config (opt-in; extraction stays off until --enabled)',
+  builder,
+  handler: runCommand(async (a) => print(await messagingPost('/AiFieldExtraction/Config', body(a)))),
+};
+
+const update = {
+  command: 'update',
+  describe: 'Partial update of the extraction config (only passed fields change)',
+  builder,
+  handler: runCommand(async (a) => print(await messagingPut('/AiFieldExtraction/Config', body(a)))),
+};
+
+const del = {
+  command: 'delete',
+  describe: 'Delete the extraction config',
+  handler: runCommand(async () => {
+    await messagingDel('/AiFieldExtraction/Config');
+    console.log('Deleted');
+  }),
+};
+
+const fields = {
+  command: 'fields <conversationId>',
+  describe: 'Show extracted fields for a conversation',
+  builder: (y) => y.positional('conversationId', { type: 'number' }),
+  handler: runCommand(async (a) => print(await messagingGet(`/AiFieldExtraction/Conversation/${a.conversationId}/Fields`))),
+};
+
+const correct = {
+  command: 'correct <conversationId> <fieldName>',
+  describe: 'Agent correction of one extracted field',
+  builder: (y) => y
+    .positional('conversationId', { type: 'number' })
+    .positional('fieldName', { type: 'string' })
+    .option('value', { type: 'string', demandOption: true }),
+  handler: runCommand(async (a) => {
+    await messagingPut(`/AiFieldExtraction/Conversation/${a.conversationId}/Fields/${encodeURIComponent(a.fieldName)}`, { Value: a.value });
+    console.log('Corrected');
+  }),
+};
+
+const extract = {
+  command: 'extract <conversationId>',
+  describe: 'Run extraction now for one conversation',
+  builder: (y) => y.positional('conversationId', { type: 'number' }),
+  handler: runCommand(async (a) => print(await messagingPost(`/AiFieldExtraction/Conversation/${a.conversationId}/Extract`, {}))),
+};
+
+export const aiFieldExtractionCommand = {
+  command: 'ai-field-extraction',
+  describe: 'AI field extraction: opt-in settings, monthly cap, extracted fields and corrections',
+  builder: (y) => y
+    .command(get).command(create).command(update).command(del)
+    .command(fields).command(correct).command(extract)
+    .demandCommand(1, 'Specify a subcommand. Run "velaro ai-field-extraction --help".'),
+  handler: () => {},
+};

package/lib/commands/executive-insights.js

@@ -0,0 +1,91 @@
+import { writeFileSync } from 'node:fs';
+import { messagingGet, messagingPost } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro executive-insights ---------------------------------------------------
+// CLI for the Friction Radar, the Executive Brief and the CSV data export. Endpoints live in
+// velaro-messaging at /api/executive-insights/*; the site always comes from the login, never from
+// CLI args. Gated on the Chat Intelligence entitlement (403 when not entitled).
+// Scheduling reuses report subscriptions: `velaro executive-insights subscribe`.
+
+function rangeArgs(argv) {
+  const days = Math.min(Math.max(Number(argv.days) || 7, 1), 92);
+  const to = argv.to ? new Date(argv.to) : new Date();
+  const from = argv.from ? new Date(argv.from) : new Date(to.getTime() - days * 86400000);
+  return new URLSearchParams({ from: from.toISOString(), to: to.toISOString() });
+}
+
+const rangeOptions = (y) => y
+  .option('days', { type: 'number', default: 7, describe: 'Look-back window in days (max 92)' })
+  .option('from', { type: 'string', describe: 'ISO start (overrides --days)' })
+  .option('to', { type: 'string', describe: 'ISO end (default now)' });
+
+const frictionCommand = {
+  command: 'friction-radar',
+  describe: 'Topics ranked by estimated agent cost with week-over-week growth and example chats',
+  builder: (y) => rangeOptions(y).option('limit', { type: 'number', default: 20 }),
+  handler: runCommand(async (argv) => {
+    const qs = rangeArgs(argv);
+    qs.set('limit', String(argv.limit ?? 20));
+    const r = await messagingGet(`/executive-insights/friction-radar?${qs}`);
+    console.log(`Friction radar: ${r.conversationsScanned} conversations scanned${r.truncated ? ' (truncated)' : ''}`);
+    for (const t of r.topics ?? []) {
+      const growth = t.isNew ? 'new' : t.growthPct == null ? 'n/a' : `${t.growthPct}%`;
+      console.log(`  #${t.costRank} ${t.topic}: ${t.volume} chats (volume rank ${t.volumeRank}, ${growth}), ${t.escalations} escalated, ${t.abandoned} abandoned, ~${Math.round(t.estimatedCostMinutes)} agent min, examples ${t.exampleConversationIds.join(', ') || '-'}`);
+    }
+  }),
+};
+
+const briefCommand = {
+  command: 'brief',
+  describe: 'Executive brief: volume, sentiment, QA, Experience Impact, rising keywords, top friction',
+  builder: rangeOptions,
+  handler: runCommand(async (argv) => {
+    const r = await messagingGet(`/executive-insights/brief?${rangeArgs(argv)}`);
+    console.log(JSON.stringify(r.brief, null, 2));
+  }),
+};
+
+const exportCommand = {
+  command: 'export',
+  describe: 'CSV of conversations with sentiment, QA score, tag, escalations, handle time and keywords',
+  builder: (y) => rangeOptions(y).option('out', { type: 'string', describe: 'Write the CSV to this file (default: stdout)' }),
+  handler: runCommand(async (argv) => {
+    const r = await messagingGet(`/executive-insights/export?${rangeArgs(argv)}`);
+    if (argv.out) {
+      writeFileSync(argv.out, r.csv, 'utf8');
+      console.log(`Wrote ${r.rows} rows to ${argv.out}${r.truncated ? ' (truncated at the row cap)' : ''}`);
+    } else {
+      process.stdout.write(r.csv);
+    }
+  }),
+};
+
+const subscribeCommand = {
+  command: 'subscribe <type>',
+  describe: 'Email yourself the executive-brief (Monday 7 AM site time by default) or data-export on a schedule',
+  builder: (y) => y
+    .positional('type', { choices: ['executive-brief', 'data-export'] })
+    .option('frequency', { type: 'string', default: 'weekly', choices: ['daily', 'biweekly', 'weekly', 'monthly'] })
+    .option('hour', { type: 'number', default: 7, describe: 'Site-local delivery hour 0-23' }),
+  handler: runCommand(async (argv) => {
+    await messagingPost('/report-subscriptions', {
+      reportType: argv.type,
+      frequency: argv.frequency,
+      deliveryHour: argv.hour,
+    });
+    console.log(`Subscribed to ${argv.type} (${argv.frequency}, ${argv.hour}:00 site time).`);
+  }),
+};
+
+export const executiveInsightsCommand = {
+  command: 'executive-insights',
+  describe: 'Friction radar, executive brief and data export (Chat Intelligence)',
+  builder: (y) => y
+    .command(frictionCommand)
+    .command(briefCommand)
+    .command(exportCommand)
+    .command(subscribeCommand)
+    .demandCommand(1, 'Specify a subcommand. Run "velaro executive-insights --help" for options.'),
+  handler: () => {},
+};

package/lib/commands/keyword-intelligence.js

@@ -0,0 +1,53 @@
+import { messagingGet } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro keyword-intelligence ----------------------------------------------------
+// Top customer keywords/phrases and conversation drill-down
+// (velaro-messaging /api/keyword-intelligence/*). Site comes from auth.
+
+const print = (data) => console.log(JSON.stringify(data, null, 2));
+
+const top = {
+  command: 'top',
+  describe: 'Top keywords/phrases in a date range',
+  builder: (y) => y
+    .option('from', { type: 'string', demandOption: true, describe: 'ISO start date' })
+    .option('to', { type: 'string', demandOption: true, describe: 'ISO end date' })
+    .option('group-by', { type: 'string', default: 'none' })
+    .option('ngram', { type: 'number', default: 3 })
+    .option('limit', { type: 'number', default: 50 })
+    .option('team', { type: 'number' })
+    .option('agent', { type: 'number' })
+    .option('website', { type: 'string' }),
+  handler: runCommand(async (a) => {
+    const qs = new URLSearchParams({ from: a.from, to: a.to, groupBy: a.groupBy, ngram: String(a.ngram), limit: String(a.limit) });
+    if (a.team != null) qs.set('teamId', String(a.team));
+    if (a.agent != null) qs.set('agentId', String(a.agent));
+    if (a.website) qs.set('website', a.website);
+    print(await messagingGet(`/api/keyword-intelligence/top?${qs}`));
+  }),
+};
+
+const conversations = {
+  command: 'conversations',
+  describe: 'Conversations containing a keyword',
+  builder: (y) => y
+    .option('keyword', { type: 'string', demandOption: true })
+    .option('from', { type: 'string', demandOption: true })
+    .option('to', { type: 'string', demandOption: true })
+    .option('team', { type: 'number' })
+    .option('agent', { type: 'number' }),
+  handler: runCommand(async (a) => {
+    const qs = new URLSearchParams({ keyword: a.keyword, from: a.from, to: a.to });
+    if (a.team != null) qs.set('teamId', String(a.team));
+    if (a.agent != null) qs.set('agentId', String(a.agent));
+    print(await messagingGet(`/api/keyword-intelligence/conversations?${qs}`));
+  }),
+};
+
+export const keywordIntelligenceCommand = {
+  command: 'keyword-intelligence',
+  describe: 'Keyword Intelligence: what customers talk about, with drill-down',
+  builder: (y) => y.command(top).command(conversations).demandCommand(1, 'Specify a subcommand. Run "velaro keyword-intelligence --help".'),
+  handler: () => {},
+};

package/lib/commands/quality-reports.js

@@ -0,0 +1,120 @@
+import { messagingGet, messagingPost, messagingPut, messagingDel } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro sentiment | quality | chat-intelligence ---------------------------------
+// Report CLI with the optional Website (deploymentId) and team filters, plus QA
+// rubric/alert commands. Endpoints live in velaro-messaging; site comes from auth and
+// deploymentId/teamId are verified server-side against that site.
+
+const print = (data) => console.log(JSON.stringify(data, null, 2));
+const scope = (y) => y
+  .option('deployment', { type: 'number', describe: 'Website (deployment row id)' })
+  .option('team', { type: 'number', describe: 'Team id' });
+
+const SENTIMENT_ROUTES = {
+  overview: 'sentiment-overview',
+  breakdown: 'sentiment-breakdown',
+  'conversation-overview': 'conversation-sentiment-overview',
+  'conversation-breakdown': 'conversation-sentiment-breakdown',
+  'contact-overview': 'contact-sentiment-overview',
+  'agent-breakdown': 'agent-sentiment-breakdown',
+};
+
+export const sentimentCommand = {
+  command: 'sentiment [kind]',
+  describe: 'Sentiment report, optionally per website/team',
+  builder: (y) => scope(y
+    .positional('kind', { choices: Object.keys(SENTIMENT_ROUTES), default: 'overview' })
+    .option('from', { type: 'string' })
+    .option('to', { type: 'string' })
+    .option('group-by', { type: 'string', default: 'day' })),
+  handler: runCommand(async (a) => {
+    const end = a.to ? new Date(a.to) : new Date();
+    const start = a.from ? new Date(a.from) : new Date(end.getTime() - 30 * 86400000);
+    const body = { Start: start.toISOString(), End: end.toISOString(), GroupBy: a.groupBy };
+    if (a.deployment != null) body.DeploymentId = a.deployment;
+    if (a.team != null) body.TeamId = a.team;
+    print(await messagingPost(`/Reports/${SENTIMENT_ROUTES[a.kind]}`, body));
+  }),
+};
+
+const agentPerformance = {
+  command: 'agent-performance',
+  describe: 'AI quality scores per agent, optionally per website/team',
+  builder: (y) => scope(y.option('days', { type: 'number', default: 30 })),
+  handler: runCommand(async (a) => {
+    const qs = new URLSearchParams({ days: String(a.days) });
+    if (a.deployment != null) qs.set('deploymentId', String(a.deployment));
+    if (a.team != null) qs.set('teamId', String(a.team));
+    print(await messagingGet(`/api/admin/Reports/AgentPerformance?${qs}`));
+  }),
+};
+
+const lowScores = {
+  command: 'low-scores',
+  describe: 'Conversations below the QA threshold',
+  builder: (y) => y.option('threshold', { type: 'number' }).option('days', { type: 'number', default: 30 }).option('agent', { type: 'number' }).option('take', { type: 'number', default: 50 }),
+  handler: runCommand(async (a) => {
+    const qs = new URLSearchParams({ days: String(a.days), take: String(a.take) });
+    if (a.threshold != null) qs.set('threshold', String(a.threshold));
+    if (a.agent != null) qs.set('agentId', String(a.agent));
+    print(await messagingGet(`/api/admin/QualityQa/low-scores?${qs}`));
+  }),
+};
+
+const calibration = {
+  command: 'calibration',
+  describe: 'AI score vs human review calibration',
+  builder: (y) => y.option('days', { type: 'number', default: 90 }),
+  handler: runCommand(async (a) => print(await messagingGet(`/api/admin/QualityQa/calibration?days=${a.days}`))),
+};
+
+const rubric = {
+  command: 'rubric <action>',
+  describe: 'QA rubrics: list | get | default | create | update | delete (--json for the rubric body)',
+  builder: (y) => y.positional('action', { choices: ['list', 'get', 'default', 'create', 'update', 'delete'] })
+    .option('id', { type: 'number' }).option('json', { type: 'string', describe: 'Rubric JSON body' }),
+  handler: runCommand(async (a) => {
+    const base = '/api/admin/QualityQa/rubrics';
+    const body = a.json ? JSON.parse(a.json) : {};
+    if (a.action === 'list') return print(await messagingGet(base));
+    if (a.action === 'default') return print(await messagingGet(`${base}/default`));
+    if (a.action === 'create') return print(await messagingPost(base, body));
+    if (a.id == null) throw new Error('--id is required');
+    if (a.action === 'get') return print(await messagingGet(`${base}/${a.id}`));
+    if (a.action === 'update') return print(await messagingPut(`${base}/${a.id}`, body));
+    print(await messagingDel(`${base}/${a.id}`));
+  }),
+};
+
+const alerts = {
+  command: 'alerts',
+  describe: 'Quality alert settings (read; pass --json to update)',
+  builder: (y) => y.option('json', { type: 'string' }),
+  handler: runCommand(async (a) => {
+    const path = '/api/admin/QualityQa/alert-settings';
+    print(a.json ? await messagingPut(path, JSON.parse(a.json)) : await messagingGet(path));
+  }),
+};
+
+export const qualityCommand = {
+  command: 'quality',
+  describe: 'Conversation Quality: agent performance, QA rubrics, low scores, calibration, alerts',
+  builder: (y) => y.command(agentPerformance).command(lowScores).command(calibration).command(rubric).command(alerts)
+    .demandCommand(1, 'Specify a subcommand. Run "velaro quality --help".'),
+  handler: () => {},
+};
+
+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' })),
+  handler: runCommand(async (a) => {
+    const qs = new URLSearchParams({ groupBy: a.groupBy });
+    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));
+    if (a.team != null) qs.set('teamId', String(a.team));
+    print(await messagingGet(`/Reports/chat-intelligence/themes?${qs}`));
+  }),
+};

package/lib/commands/skill-routing.js

@@ -0,0 +1,61 @@
+import { messagingGet, messagingPost, messagingPut, messagingDel } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro skill-routing ---------------------------------------------------------
+// CLI for skill-based routing (velaro-messaging SkillRoutingController, route
+// /SkillRouting). Site comes from the caller's auth, never from CLI args.
+// Gated by the EnableSkillBasedRouting entitlement (403 when not entitled).
+// Requirements are disabled by default and PUT is partial (omitted fields unchanged).
+
+const print = (data) => console.log(JSON.stringify(data, null, 2));
+const ids = (v) => (v == null ? undefined : String(v).split(',').map((x) => Number(x.trim())).filter((n) => !Number.isNaN(n)));
+const strip = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+
+function crud(resource, noun, addOpts, toBody) {
+  return {
+    command: `${resource.toLowerCase()} <action>`,
+    describe: `${noun}: list | create | update | delete`,
+    builder: (y) => addOpts(y.positional('action', { choices: ['list', 'create', 'update', 'delete'] }).option('id', { type: 'number', describe: 'Row id (update/delete)' })),
+    handler: runCommand(async (argv) => {
+      const base = `/SkillRouting/${resource}`;
+      if (argv.action === 'list') return print(await messagingGet(base));
+      if (argv.action === 'create') return print(await messagingPost(base, toBody(argv)));
+      if (argv.id == null) throw new Error('--id is required for update/delete');
+      if (argv.action === 'update') return print(await messagingPut(`${base}/${argv.id}`, toBody(argv)));
+      print(await messagingDel(`${base}/${argv.id}`));
+    }),
+  };
+}
+
+const skills = crud('Skills', 'Skill catalog',
+  (y) => y.option('name', { type: 'string' }).option('description', { type: 'string' }),
+  (a) => strip({ Name: a.name, Description: a.description }));
+
+const assignments = crud('Assignments', 'Agent skill assignments',
+  (y) => y.option('agent', { type: 'number', describe: 'workspaceUserId' }).option('skill', { type: 'number', describe: 'agentSkillId' }).option('proficiency', { type: 'number', describe: '1-5' }),
+  (a) => strip({ WorkspaceUserId: a.agent, AgentSkillId: a.skill, Proficiency: a.proficiency }));
+
+const requirements = crud('Requirements', 'Required/preferred skills per deployment/team',
+  (y) => y.option('deployment', { type: 'number' }).option('team', { type: 'number' })
+    .option('required', { type: 'string', describe: 'Comma-separated skill ids' })
+    .option('preferred', { type: 'string', describe: 'Comma-separated skill ids' })
+    .option('overflow-wait', { type: 'number', describe: 'Seconds before falling back to all agents' })
+    .option('enabled', { type: 'boolean', describe: 'Turn the requirement on/off (default off)' }),
+  (a) => strip({ DeploymentId: a.deployment, TeamId: a.team, RequiredSkillIds: ids(a.required), PreferredSkillIds: ids(a.preferred), OverflowWaitSeconds: a.overflowWait, IsEnabled: a.enabled }));
+
+const simulate = {
+  command: 'simulate',
+  describe: 'Dry-run skill routing for a team (never assigns, never writes the decision log)',
+  builder: (y) => y.option('team', { type: 'number' }).option('waited', { type: 'number', describe: 'Seconds the conversation has waited' }),
+  handler: runCommand(async (argv) => {
+    print(await messagingPost('/SkillRouting/Simulate', { TeamId: argv.team ?? null, WaitedSeconds: argv.waited ?? null }));
+  }),
+};
+
+export const skillRoutingCommand = {
+  command: 'skill-routing',
+  describe: 'Skill-based routing: skills, agent assignments, requirements, simulator',
+  builder: (y) => y.command(skills).command(assignments).command(requirements).command(simulate)
+    .demandCommand(1, 'Specify a subcommand. Run "velaro skill-routing --help".'),
+  handler: () => {},
+};

package/package.json

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