@velaro/cli 1.4.71 → 1.4.72

package/bin/velaro.js

@@ -41,10 +41,13 @@ import { bookingCommand } from '../lib/commands/booking.js';
 import { reportCommand }       from '../lib/commands/report.js';
 import { scheduleAdherenceCommand } from '../lib/commands/schedule-adherence.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 { dbCommand } from '../lib/commands/db.js';
 import { focusCommand }       from '../lib/commands/focus.js';
+import { triageCommand }      from '../lib/commands/triage.js';
 import { automationDraftCommand } from '../lib/commands/automation-draft.js';
 import { magentoCommand }       from '../lib/commands/magento.js';
 import { mondayCommand }        from '../lib/commands/monday.js';
@@ -145,9 +148,12 @@ await yargs(hideBin(process.argv))
   .command(conversationEfficiencyCommand)
   .command(scheduleAdherenceCommand)
   .command(experienceImpactCommand)
+  .command(reportBackfillCommand)
+  .command({ command: 'staff', desc: 'Velaro staff: cross-site tools (backfill)', builder: staffCommand, handler: () => {} })
   .command(reportExplainCommand)
   .command(dbCommand)
   .command(focusCommand)
+  .command(triageCommand)
   .command(automationDraftCommand)
   .command(magentoCommand)
   .command(mondayCommand)

package/lib/commands/focus.js

@@ -278,6 +278,32 @@ const draftPregenerationReportCommand = {
   },
 };
 
+// ── triage economy report (customer) ──────────────────────────────────────────
+
+export function renderTriageReport(r) {
+  const q = r.quality ?? {};
+  const usd = (n) => (n == null ? '—' : '$' + Number(n).toFixed(2));
+  return [
+    '\n' + BOLD + '── Triage Economy Report (' + (r.siteId != null ? 'site ' + r.siteId : 'platform') + ', ' + r.days + 'd) ──' + RESET,
+    '  Mode: ' + (r.effectiveMode ?? '—') + ' (source: ' + (r.effectiveModeSource ?? '—') + ')',
+    '  Triaged: ' + r.conversationsTriaged + '  Rules: ' + r.handledByRules + '  Haiku: ' + r.handledByHaiku + '  Hit rate: ' + r.rulesHitRatePercent + '%',
+    '  ' + GRN + 'Saved: ' + usd(r.estimatedUsdSaved) + RESET + '  Haiku calls avoided: ' + r.haikuCallsAvoided + '  Avg Haiku cost: ' + usd(r.avgHaikuCostUsd),
+    '  Latency: rules ' + (r.rulesLatencyMs ?? '—') + 'ms vs Haiku ' + (r.avgHaikuLatencyMs ?? '—') + 'ms',
+    '  Correction rate: rules ' + (q.rulesCorrectionRatePercent ?? '—') + '% (' + (q.rulesCorrections ?? 0) + ') vs Haiku ' + (q.haikuCorrectionRatePercent ?? '—') + '% (' + (q.haikuCorrections ?? 0) + ')',
+    '  Skill selection: ' + (r.skillSelectionImpact ?? 'unaffected') + (r.skillSelectionNote ? ' - ' + r.skillSelectionNote : '') + '\n',
+  ].join('\n');
+}
+
+const triageReportCommand = {
+  command:  'triage-report',
+  describe: 'Triage Economy report: dollars saved, rules hit rate, correction-rate delta vs Haiku',
+  builder:  (y) => y.option('days', { type: 'number', default: 30 }).option('json', { type: 'boolean', default: false }),
+  handler:  async (argv) => {
+    const r = await messagingGet('/Focus/Triage/EconomyReport?days=' + argv.days);
+    console.log(argv.json ? JSON.stringify(r, null, 2) : renderTriageReport(r));
+  },
+};
+
 // ── top-level focus command ───────────────────────────────────────────────────
 
 export const focusCommand = {
@@ -292,6 +318,7 @@ export const focusCommand = {
     .command(triageRulesCommand)
     .command(setTriageRuleCommand)
     .command(draftPregenerationReportCommand)
+    .command(triageReportCommand)
     .demandCommand(1, 'Specify a focus subcommand.')
     .strict(),
   handler:  () => {},

package/lib/commands/report-backfill.js

@@ -0,0 +1,23 @@
+import { messagingPost } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro report-backfill <type> --from --to [--apply] ---------------------------
+// Backend: velaro-messaging POST /Reports/backfill/{type}?from&to&apply (site managers; site from auth).
+// Preview by default ("would fill N"); --apply writes. Idempotent. Type "csat" fills survey ratings only.
+export const reportBackfillCommand = {
+  command:  'report-backfill <type>',
+  describe: 'Backfill report data for your site (preview by default; --apply to write). Type: csat',
+  builder:  (y) => y
+    .positional('type', { type: 'string', describe: 'Backfill type, e.g. csat' })
+    .option('from', { type: 'string', demandOption: true, describe: 'yyyy-MM-dd' })
+    .option('to', { type: 'string', demandOption: true, describe: 'yyyy-MM-dd' })
+    .option('apply', { type: 'boolean', default: false, describe: 'Write the changes (default: preview only)' })
+    .option('json', { type: 'boolean', default: false, describe: 'Raw JSON output' }),
+  handler:  runCommand(async (argv) => {
+    const qs = new URLSearchParams({ from: argv.from, to: argv.to, apply: String(!!argv.apply) });
+    const r = await messagingPost(`/Reports/backfill/${encodeURIComponent(argv.type)}?${qs}`);
+    if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
+    console.log(argv.apply ? '\nBackfill APPLIED' : '\nBackfill PREVIEW (nothing written; add --apply to write)');
+    console.log(JSON.stringify(r, null, 2));
+  }),
+};

package/lib/commands/staff.js

@@ -0,0 +1,31 @@
+// velaro staff backfill --site <id> --type csat --from --to [--apply] -- Velaro staff only.
+// Backend: messaging GET SuperAdmin/backfill-types, POST SuperAdmin/sites/{siteId}/backfill.
+// Site is always explicit in the route, never derived from the caller's auth.
+import { messagingGet, messagingPost } from '../api.js';
+
+async function run(argv) {
+  if (argv.list) {
+    const t = await messagingGet('/SuperAdmin/backfill-types');
+    if (argv.json) { console.log(JSON.stringify(t, null, 2)); return; }
+    for (const x of t) console.log(`${x.type}: ${x.title} - ${x.description}`);
+    return;
+  }
+  if (!argv.site || !argv.type || !argv.from || !argv.to) throw new Error('--site, --type, --from and --to are required (or use --list).');
+  const r = await messagingPost(`/SuperAdmin/sites/${encodeURIComponent(argv.site)}/backfill`, { type: argv.type, from: argv.from, to: argv.to, apply: !!argv.apply });
+  if (argv.json) { console.log(JSON.stringify(r, null, 2)); return; }
+  console.log(argv.apply ? `\nBackfill APPLIED for site ${argv.site}` : `\nBackfill PREVIEW for site ${argv.site} (nothing written; add --apply)`);
+  console.log(JSON.stringify(r, null, 2));
+}
+
+export function staffCommand(yargs) {
+  return yargs
+    .command('backfill', 'Preview/apply a report-data backfill for any site (staff only)', (y) => y
+      .option('site', { type: 'number', describe: 'Target site id' })
+      .option('type', { type: 'string', describe: 'Backfill type, e.g. csat' })
+      .option('from', { type: 'string', describe: 'yyyy-MM-dd' })
+      .option('to', { type: 'string', describe: 'yyyy-MM-dd' })
+      .option('apply', { type: 'boolean', default: false, describe: 'Write (default preview)' })
+      .option('list', { type: 'boolean', default: false, describe: 'List backfill types' })
+      .option('json', { type: 'boolean', describe: 'Raw JSON' }), (a) => run(a).catch(e => { console.error(e.message); process.exit(1); }))
+    .demandCommand(1, 'Specify a subcommand: backfill');
+}

package/lib/commands/triage.js

@@ -0,0 +1,66 @@
+// Staff-only (Velaro Administrator) Triage Economy controls: platform default/force mode,
+// per-site effective modes, and the savings/quality report. Resolution is
+// force ?? perSite ?? platformDefault ?? "economy". Skill: .claude/skills/triage-economy-report/SKILL.md
+import { messagingGet, messagingPut } from '../api.js';
+import { renderTriageReport } from './focus.js';
+
+const MODES = ['off', 'economy', 'null'];
+const toMode = (v) => (v === 'null' ? null : v);
+
+const platformGet = {
+  command: 'get',
+  describe: 'Show platform forceMode / defaultMode',
+  builder: (y) => y,
+  handler: async () => console.log(JSON.stringify(await messagingGet('/superadmin/focus-triage/platform'), null, 2)),
+};
+
+const platformSet = {
+  command: 'set',
+  describe: 'Set platform defaultMode and/or forceMode (off|economy|null; omitted = unchanged)',
+  builder: (y) => y
+    .option('default', { type: 'string', choices: MODES, describe: 'Mode for sites with no own setting' })
+    .option('force', { type: 'string', choices: MODES, describe: 'Mode forced on ALL sites (null clears)' }),
+  handler: async (argv) => {
+    const body = {};
+    if (argv.default !== undefined) body.defaultMode = toMode(argv.default);
+    if (argv.force !== undefined) body.forceMode = toMode(argv.force);
+    if (!Object.keys(body).length) throw new Error('Provide --default and/or --force.');
+    console.log(JSON.stringify(await messagingPut('/superadmin/focus-triage/platform', body), null, 2));
+  },
+};
+
+const platformCommand = {
+  command: 'platform <action>',
+  describe: 'Platform-wide triage mode',
+  builder: (y) => y.command(platformGet).command(platformSet).demandCommand(1).strict(),
+  handler: () => {},
+};
+
+const sitesCommand = {
+  command: 'sites',
+  describe: 'Every site with effective triage mode and source (force|site|default)',
+  builder: (y) => y,
+  handler: async () => console.log(JSON.stringify(await messagingGet('/superadmin/focus-triage/sites'), null, 2)),
+};
+
+const reportCommand = {
+  command: 'report',
+  describe: 'Triage Economy report; no --site = platform-wide with per-site breakdown',
+  builder: (y) => y
+    .option('site', { type: 'number' })
+    .option('days', { type: 'number', default: 30 })
+    .option('json', { type: 'boolean', default: false }),
+  handler: async (argv) => {
+    const qs = new URLSearchParams({ days: String(argv.days) });
+    if (argv.site != null) qs.set('siteId', String(argv.site));
+    const r = await messagingGet('/superadmin/focus-triage/report?' + qs);
+    console.log(argv.json ? JSON.stringify(r, null, 2) : renderTriageReport(r));
+  },
+};
+
+export const triageCommand = {
+  command: 'triage <subcommand>',
+  describe: 'Staff: Triage Economy platform mode, per-site modes, and savings report (Velaro Administrator)',
+  builder: (y) => y.command(platformCommand).command(sitesCommand).command(reportCommand).demandCommand(1).strict(),
+  handler: () => {},
+};

package/lib/report-explain.json

@@ -5,7 +5,7 @@
     "sources": "Work Schedules and presence, chat queue timing, missed chats, and CSAT from ticket replies and 1-5 survey ratings (questions tagged csat or star_rating).",
     "prerequisites": "Work Schedules for agents; a survey with a 1-5 CSAT or star question attached to post-chat or a workflow, or ticket CSAT requests turned on; chat traffic in range.",
     "interpret": "Weights: service level 30, adherence 25, CSAT 25, missed chats 20; a signal with no data drops out. CSAT needs 5+ responses to count. Response rate = rated survey submissions / all survey submissions. Actual agents below scheduled while missed chats rise = staffing gap.",
-    "whyZero": "CSAT empty: no CSAT survey configured; survey exists but nobody answered; answers came in with no 1-5 rating question; fewer than 5 responses; or the range predates the survey. If older chats were surveyed but never counted, ask Velaro support to run a CSAT backfill. Adherence empty: no Work Schedules. Sample data never mixes with real data.",
+    "whyZero": "CSAT empty: no CSAT survey configured; survey exists but nobody answered; answers came in with no 1-5 rating question; fewer than 5 responses; or the range predates the survey. Surveyed but unrated? Managers run the CSAT backfill (survey ratings only, not ticket CSAT): preview, then apply, via the report banner, `velaro report-backfill csat`, or MCP report_backfill. Adherence empty: no Work Schedules.",
     "fix": "Add a 1-5 star or CSAT question to the post-chat survey, enable ticket CSAT requests, widen the range, then fix the weakest component.",
     "related": "Schedule Adherence, Service Level, Missed Chats, Surveys & NPS, Sentiment, Agent Performance"
   },

package/lib/triage-report.test.js

@@ -0,0 +1,18 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { renderTriageReport } from './commands/focus.js';
+
+test('renderTriageReport shows dollars, hit rate, correction delta and skill note', () => {
+  const out = renderTriageReport({
+    siteId: 1032, days: 30, effectiveMode: 'economy', effectiveModeSource: 'site',
+    conversationsTriaged: 100, handledByRules: 60, handledByHaiku: 40, rulesHitRatePercent: 60,
+    haikuCallsAvoided: 60, estimatedUsdSaved: 1.5, avgHaikuCostUsd: 0.025,
+    rulesLatencyMs: 2, avgHaikuLatencyMs: 800,
+    quality: { rulesCorrections: 1, haikuCorrections: 2, rulesCorrectionRatePercent: 1.7, haikuCorrectionRatePercent: 5 },
+    skillSelectionImpact: 'none',
+  });
+  assert.match(out, /\$1\.50/);
+  assert.match(out, /Hit rate: 60%/);
+  assert.match(out, /rules 1\.7% .* vs Haiku 5%/);
+  assert.match(out, /Skill selection: none/);
+});

package/package.json

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