@velaro/cli 1.4.72 → 1.4.74

package/bin/velaro.js

@@ -40,11 +40,13 @@ import { appointmentsCommand } from '../lib/commands/appointments.js';
 import { bookingCommand } from '../lib/commands/booking.js';
 import { reportCommand }       from '../lib/commands/report.js';
 import { scheduleAdherenceCommand } from '../lib/commands/schedule-adherence.js';
+import { reportSubscriptionCommand } from '../lib/commands/report-subscription.js';
 import { experienceImpactCommand } from '../lib/commands/experience-impact.js';
 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 { focusCommand }       from '../lib/commands/focus.js';
 import { triageCommand }      from '../lib/commands/triage.js';
@@ -146,8 +148,10 @@ await yargs(hideBin(process.argv))
   .command(bookingCommand)
   .command(reportCommand)
   .command(conversationEfficiencyCommand)
+  .command(executiveInsightsCommand)
   .command(scheduleAdherenceCommand)
   .command(experienceImpactCommand)
+  .command(reportSubscriptionCommand)
   .command(reportBackfillCommand)
   .command({ command: 'staff', desc: 'Velaro staff: cross-site tools (backfill)', builder: staffCommand, handler: () => {} })
   .command(reportExplainCommand)

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/report-subscription.js

@@ -0,0 +1,56 @@
+import { messagingRequest } from '../api.js';
+import { runCommand } from '../run.js';
+import { buildSubscriptionUpdateBody, formatSubscriptionLine } from '../report-subscription.js';
+
+// -- velaro report-subscription list | update | delete ------------------------------
+// Backend: velaro-messaging GET/PUT/DELETE /report-subscriptions (the caller's own subscriptions).
+
+const listCmd = {
+  command: 'list',
+  describe: 'List your report email subscriptions (incl. delivery hour, format, extra recipients)',
+  builder: (y) => y.option('json', { type: 'boolean', default: false }),
+  handler: runCommand(async (argv) => {
+    const rows = await messagingRequest('GET', '/report-subscriptions');
+    if (argv.json) { console.log(JSON.stringify(rows, null, 2)); return; }
+    if (!Array.isArray(rows) || !rows.length) { console.log('No report subscriptions.'); return; }
+    rows.forEach((s) => console.log(formatSubscriptionLine(s)));
+  }),
+};
+
+const updateCmd = {
+  command: 'update <id>',
+  describe: 'Update one subscription by id (only passed fields change)',
+  builder: (y) => y
+    .positional('id', { type: 'number' })
+    .option('frequency', { type: 'string', describe: 'daily | weekly | bi-monthly | monthly' })
+    .option('delivery-hour', { type: 'number', describe: 'Site-local hour 0-23 to deliver at or after' })
+    .option('clear-delivery-hour', { type: 'boolean', default: false })
+    .option('format', { type: 'string', choices: ['pdf', 'html'] })
+    .option('extra-recipients', { type: 'string', describe: 'Comma-separated emails of other users on this account ("" clears)' })
+    .option('active', { type: 'boolean', describe: 'true to resume, false to pause' }),
+  handler: runCommand(async (argv) => {
+    const body = buildSubscriptionUpdateBody({
+      frequency: argv.frequency, deliveryHour: argv.deliveryHour, clearDeliveryHour: argv.clearDeliveryHour,
+      format: argv.format, extraRecipients: argv.extraRecipients, active: argv.active,
+    });
+    await messagingRequest('PUT', `/report-subscriptions/${argv.id}`, body);
+    console.log(`Subscription #${argv.id} updated.`);
+  }),
+};
+
+const deleteCmd = {
+  command: 'delete <id>',
+  describe: 'Delete one subscription by id',
+  builder: (y) => y.positional('id', { type: 'number' }),
+  handler: runCommand(async (argv) => {
+    await messagingRequest('DELETE', `/report-subscriptions/${argv.id}`);
+    console.log(`Subscription #${argv.id} deleted.`);
+  }),
+};
+
+export const reportSubscriptionCommand = {
+  command: 'report-subscription',
+  describe: 'Manage your scheduled report email subscriptions',
+  builder: (y) => y.command(listCmd).command(updateCmd).command(deleteCmd).demandCommand(1),
+  handler: () => {},
+};

package/lib/report-subscription.js

@@ -0,0 +1,29 @@
+// Pure helpers for `velaro report-subscription` (backend: velaro-messaging /report-subscriptions).
+// Site + user scope come from the caller's auth, never an argument.
+
+/** Partial-update body: only fields the caller actually passed are included. */
+export function buildSubscriptionUpdateBody(opts = {}) {
+  const body = {};
+  if (opts.frequency != null && opts.frequency !== '') body.frequency = String(opts.frequency);
+  if (opts.deliveryHour != null) {
+    const h = Number(opts.deliveryHour);
+    if (!Number.isInteger(h) || h < 0 || h > 23) throw new Error('deliveryHour must be an integer 0-23');
+    body.deliveryHour = h;
+  }
+  if (opts.clearDeliveryHour === true) body.clearDeliveryHour = true;
+  if (opts.format != null && opts.format !== '') {
+    const f = String(opts.format).toLowerCase();
+    if (f !== 'pdf' && f !== 'html') throw new Error('format must be pdf or html');
+    body.format = f;
+  }
+  if (opts.extraRecipients != null) body.extraRecipients = String(opts.extraRecipients);
+  if (typeof opts.active === 'boolean') body.isActive = opts.active;
+  if (Object.keys(body).length === 0) throw new Error('nothing to update: pass at least one field');
+  return body;
+}
+
+export function formatSubscriptionLine(s) {
+  const hour = s.deliveryHour == null ? 'any hour' : `${String(s.deliveryHour).padStart(2, '0')}:00`;
+  const extra = s.extraRecipients ? ` | also to ${s.extraRecipients}` : '';
+  return `#${s.id} ${s.reportType}: ${s.isActive ? 'active' : 'paused'}, ${s.frequency}, ${hour}, ${s.format ?? 'pdf'}${extra}`;
+}

package/lib/report-subscription.test.js

@@ -0,0 +1,24 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildSubscriptionUpdateBody, formatSubscriptionLine } from './report-subscription.js';
+
+test('update body includes only provided fields', () => {
+  assert.deepEqual(buildSubscriptionUpdateBody({ deliveryHour: 7, format: 'HTML', extraRecipients: 'a@x.com,b@x.com' }),
+    { deliveryHour: 7, format: 'html', extraRecipients: 'a@x.com,b@x.com' });
+});
+test('empty extraRecipients string is sent so it clears the list', () => {
+  assert.deepEqual(buildSubscriptionUpdateBody({ extraRecipients: '' }), { extraRecipients: '' });
+});
+test('active=false pauses, hour 0 is valid', () => {
+  assert.deepEqual(buildSubscriptionUpdateBody({ active: false, deliveryHour: 0 }), { isActive: false, deliveryHour: 0 });
+});
+test('rejects bad hour, bad format, empty update', () => {
+  assert.throws(() => buildSubscriptionUpdateBody({ deliveryHour: 24 }));
+  assert.throws(() => buildSubscriptionUpdateBody({ format: 'docx' }));
+  assert.throws(() => buildSubscriptionUpdateBody({}));
+});
+test('formats a line with hour, format and extras', () => {
+  assert.equal(formatSubscriptionLine({ id: 5, reportType: 'experience-impact', isActive: true, frequency: 'weekly', deliveryHour: 7, format: 'pdf', extraRecipients: 'a@x.com' }),
+    '#5 experience-impact: active, weekly, 07:00, pdf | also to a@x.com');
+  assert.equal(formatSubscriptionLine({ id: 6, reportType: 'x', isActive: false, frequency: 'daily' }), '#6 x: paused, daily, any hour, pdf');
+});

package/package.json

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