@velaro/cli 1.2.0 → 1.4.8

package/lib/commands/report.js

@@ -0,0 +1,462 @@
+import { getCredentials, request, messagingRequest } from '../api.js';
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function fmtSeconds(sec) {
+  if (sec == null || sec === 0) return '—';
+  const m = Math.floor(sec / 60);
+  const s = Math.round(sec % 60);
+  if (m === 0) return `${s}s`;
+  return `${m}m ${s}s`;
+}
+
+function fmtPct(val) {
+  if (val == null) return '—';
+  return `${(val * 100).toFixed(1)}%`;
+}
+
+function fmtNum(val) {
+  if (val == null) return '—';
+  return String(val);
+}
+
+function fmtRow(label, value) {
+  console.log(`  ${label.padEnd(32)}${value}`);
+}
+
+function section(title) {
+  console.log(`\n\x1b[1m── ${title} ${'─'.repeat(Math.max(0, 55 - title.length))}\x1b[0m`);
+}
+
+function dateParams(argv) {
+  const params = [];
+  if (argv.start) params.push(`start=${encodeURIComponent(argv.start)}`);
+  if (argv.end)   params.push(`end=${encodeURIComponent(argv.end)}`);
+  return params.length ? `?${params.join('&')}` : '';
+}
+
+async function fetchReport(path) {
+  const res = await getCredentials();
+  const raw = await fetch(`${res.adminApiBase}${path}`, {
+    headers: {
+      Authorization:  `Bearer ${res.velaroToken}`,
+      'Content-Type': 'application/json',
+    },
+    signal: AbortSignal.timeout(30000),
+  });
+  if (raw.status === 402) {
+    console.error('This feature requires an Advanced Analytics subscription.');
+    process.exit(1);
+  }
+  if (!raw.ok) {
+    let msg = `GET ${path} → ${raw.status}`;
+    try { const t = await raw.text(); if (t) msg += `: ${t}`; } catch { /* captured above */ }
+    throw new Error(msg);
+  }
+  const text = await raw.text();
+  return text ? JSON.parse(text) : null;
+}
+
+// ── callcenter subcommands ────────────────────────────────────────────────────
+
+const callcenterTeamsCommand = {
+  command:  'teams',
+  describe: 'Team breakdown for the call center report',
+  builder:  (y) => y
+    .option('start',       { type: 'string', describe: 'Start date (YYYY-MM-DD)' })
+    .option('end',         { type: 'string', describe: 'End date (YYYY-MM-DD)' })
+    .option('sla',         { type: 'number', describe: 'SLA threshold in seconds (overrides server default)' }),
+  handler: async (argv) => {
+    const params = [];
+    if (argv.start) params.push(`start=${encodeURIComponent(argv.start)}`);
+    if (argv.end)   params.push(`end=${encodeURIComponent(argv.end)}`);
+    if (argv.sla)   params.push(`slaSeconds=${argv.sla}`);
+    const qs = params.length ? `?${params.join('&')}` : '';
+    const data = await fetchReport(`/CallCenterAnalytics/TeamBreakdown${qs}`);
+    const teams = Array.isArray(data) ? data : (data?.teams ?? []);
+
+    section('Call Center — Team Breakdown');
+    if (!teams.length) { console.log('  No data for the selected range.'); return; }
+
+    const COL = [28, 10, 10, 10, 10, 10, 12];
+    const header = ['Team', 'Volume', 'AHT', 'Wait', 'Abandon', 'SLA%', 'CSAT'];
+    console.log('\n  ' + header.map((h, i) => h.padEnd(COL[i])).join(''));
+    console.log('  ' + '─'.repeat(COL.reduce((a, b) => a + b, 0)));
+
+    for (const t of teams) {
+      const row = [
+        (t.teamName ?? t.name ?? '—').slice(0, 26),
+        fmtNum(t.totalConversations ?? t.volume),
+        fmtSeconds(t.avgHandleTimeSeconds ?? t.aht),
+        fmtSeconds(t.avgWaitTimeSeconds   ?? t.waitTime),
+        fmtPct(t.abandonRate),
+        fmtPct(t.slaComplianceRate ?? t.slaRate),
+        t.csat != null ? fmtPct(t.csat) : '—',
+      ];
+      console.log('  ' + row.map((v, i) => String(v).padEnd(COL[i])).join(''));
+    }
+    console.log('');
+  },
+};
+
+const callcenterChannelsCommand = {
+  command:  'channels',
+  describe: 'Channel breakdown for the call center report',
+  builder:  (y) => y
+    .option('start', { type: 'string', describe: 'Start date (YYYY-MM-DD)' })
+    .option('end',   { type: 'string', describe: 'End date (YYYY-MM-DD)' }),
+  handler: async (argv) => {
+    const data = await fetchReport(`/CallCenterAnalytics/ChannelBreakdown${dateParams(argv)}`);
+    const channels = Array.isArray(data) ? data : (data?.channels ?? []);
+
+    section('Call Center — Channel Breakdown');
+    if (!channels.length) { console.log('  No data for the selected range.'); return; }
+
+    const COL = [22, 10, 10, 10, 10, 12];
+    const header = ['Channel', 'Volume', 'AHT', 'Wait', 'Abandon', 'Bot%'];
+    console.log('\n  ' + header.map((h, i) => h.padEnd(COL[i])).join(''));
+    console.log('  ' + '─'.repeat(COL.reduce((a, b) => a + b, 0)));
+
+    for (const c of channels) {
+      const row = [
+        (c.channel ?? c.channelName ?? '—').slice(0, 20),
+        fmtNum(c.totalConversations ?? c.volume),
+        fmtSeconds(c.avgHandleTimeSeconds ?? c.aht),
+        fmtSeconds(c.avgWaitTimeSeconds   ?? c.waitTime),
+        fmtPct(c.abandonRate),
+        fmtPct(c.botContainmentRate ?? c.botRate),
+      ];
+      console.log('  ' + row.map((v, i) => String(v).padEnd(COL[i])).join(''));
+    }
+    console.log('');
+  },
+};
+
+const callcenterCommand = {
+  command:  'callcenter',
+  describe: 'Call center analytics report (volume, speed, abandon, bot metrics)',
+  builder:  (y) => y
+    .command(callcenterTeamsCommand)
+    .command(callcenterChannelsCommand)
+    .option('start', { type: 'string', describe: 'Start date (YYYY-MM-DD)' })
+    .option('end',   { type: 'string', describe: 'End date (YYYY-MM-DD)' }),
+  handler: async (argv) => {
+    const data = await fetchReport(`/CallCenterAnalytics/Report${dateParams(argv)}`);
+
+    section('Call Center Report');
+    if (!data) { console.log('  No data returned.'); return; }
+
+    if (argv.start || argv.end) {
+      const range = [argv.start, argv.end].filter(Boolean).join(' → ');
+      console.log(`  Period: ${range}`);
+    }
+
+    // Volume
+    section('Volume');
+    fmtRow('Total conversations',       fmtNum(data.totalConversations));
+    fmtRow('Bot-handled (no agent)',     fmtNum(data.botOnlyConversations));
+    fmtRow('Agent-handled',             fmtNum(data.agentConversations));
+    fmtRow('Missed / abandoned',        fmtNum(data.missedConversations ?? data.abandonedConversations));
+
+    // Speed
+    section('Speed');
+    fmtRow('Avg handle time (AHT)',      fmtSeconds(data.avgHandleTimeSeconds));
+    fmtRow('Avg first response time',    fmtSeconds(data.avgFirstResponseTimeSeconds));
+    fmtRow('Avg queue wait time',        fmtSeconds(data.avgQueueWaitTimeSeconds ?? data.avgWaitTimeSeconds));
+    fmtRow('Avg resolution time',        fmtSeconds(data.avgResolutionTimeSeconds));
+
+    // Abandon
+    section('Abandon');
+    fmtRow('Abandon rate',               fmtPct(data.abandonRate));
+    fmtRow('Avg wait before abandon',    fmtSeconds(data.avgWaitBeforeAbandonSeconds));
+
+    // Bot metrics
+    section('Bot Metrics');
+    fmtRow('Bot containment rate',       fmtPct(data.botContainmentRate));
+    fmtRow('Bot handoff rate',           fmtPct(data.botHandoffRate));
+    fmtRow('Bot conversations',          fmtNum(data.botConversations ?? data.botTotalConversations));
+
+    // Alerts / thresholds
+    if (data.alerts?.length) {
+      section('Threshold Alerts');
+      for (const a of data.alerts) {
+        console.log(`  \x1b[33m⚠\x1b[0m  ${a.metric ?? a.name}: ${a.message ?? a.detail}`);
+      }
+    }
+
+    console.log('');
+  },
+};
+
+// ── servicelevel command ──────────────────────────────────────────────────────
+
+const servicelevelCommand = {
+  command:  'servicelevel',
+  describe: 'Service level compliance report over time',
+  builder:  (y) => y
+    .option('start',       { type: 'string', describe: 'Start date (YYYY-MM-DD)' })
+    .option('end',         { type: 'string', describe: 'End date (YYYY-MM-DD)' })
+    .option('granularity', { type: 'string', choices: ['hour', 'day', 'week', 'month'], default: 'day', describe: 'Time bucket size' }),
+  handler: async (argv) => {
+    const params = [];
+    if (argv.start)       params.push(`start=${encodeURIComponent(argv.start)}`);
+    if (argv.end)         params.push(`end=${encodeURIComponent(argv.end)}`);
+    if (argv.granularity) params.push(`granularity=${argv.granularity}`);
+    const qs = params.length ? `?${params.join('&')}` : '';
+    const data = await fetchReport(`/ServiceLevel${qs}`);
+
+    section('Service Level Report');
+
+    // Summary row if present
+    if (data?.summary) {
+      const s = data.summary;
+      fmtRow('Overall SLA compliance',  fmtPct(s.complianceRate ?? s.slaRate));
+      fmtRow('SLA threshold',           s.thresholdSeconds != null ? fmtSeconds(s.thresholdSeconds) : '—');
+      fmtRow('Total conversations',     fmtNum(s.totalConversations));
+      fmtRow('Within SLA',              fmtNum(s.withinSla));
+      fmtRow('Breached SLA',            fmtNum(s.breachedSla));
+    }
+
+    const buckets = Array.isArray(data) ? data : (data?.buckets ?? data?.data ?? []);
+    if (buckets.length) {
+      console.log('');
+      const COL = [22, 12, 10, 10, 10];
+      const header = ['Period', 'SLA %', 'Total', 'Within', 'Breached'];
+      console.log('  ' + header.map((h, i) => h.padEnd(COL[i])).join(''));
+      console.log('  ' + '─'.repeat(COL.reduce((a, b) => a + b, 0)));
+      for (const b of buckets) {
+        const label = b.period ?? b.date ?? b.bucket ?? '—';
+        const row = [
+          String(label).slice(0, 20),
+          fmtPct(b.complianceRate ?? b.slaRate),
+          fmtNum(b.totalConversations ?? b.total),
+          fmtNum(b.withinSla),
+          fmtNum(b.breachedSla),
+        ];
+        console.log('  ' + row.map((v, i) => String(v).padEnd(COL[i])).join(''));
+      }
+    }
+    console.log('');
+  },
+};
+
+// ── conversations command ─────────────────────────────────────────────────────
+
+const conversationsCommand = {
+  command:  'conversations',
+  describe: 'Conversation volume report over time',
+  builder:  (y) => y
+    .option('start',       { type: 'string', describe: 'Start date (YYYY-MM-DD)' })
+    .option('end',         { type: 'string', describe: 'End date (YYYY-MM-DD)' })
+    .option('granularity', { type: 'string', choices: ['hour', 'day', 'week', 'month'], default: 'day', describe: 'Time bucket size' })
+    .option('channel',     { type: 'string', describe: 'Filter by channel (e.g. Web, TwilioSms, WhatsApp)' }),
+  handler: async (argv) => {
+    const params = [];
+    if (argv.start)       params.push(`start=${encodeURIComponent(argv.start)}`);
+    if (argv.end)         params.push(`end=${encodeURIComponent(argv.end)}`);
+    if (argv.granularity) params.push(`granularity=${argv.granularity}`);
+    if (argv.channel)     params.push(`channel=${encodeURIComponent(argv.channel)}`);
+    const qs = params.length ? `?${params.join('&')}` : '';
+    const data = await fetchReport(`/Conversations${qs}`);
+
+    section('Conversations Report');
+
+    if (data?.summary) {
+      const s = data.summary;
+      fmtRow('Total conversations',     fmtNum(s.total ?? s.totalConversations));
+      fmtRow('Resolved',                fmtNum(s.resolved));
+      fmtRow('Missed',                  fmtNum(s.missed));
+      fmtRow('Bot contained',           fmtNum(s.botContained));
+      fmtRow('Avg handle time',         fmtSeconds(s.avgHandleTimeSeconds));
+      fmtRow('CSAT',                    s.csat != null ? fmtPct(s.csat) : '—');
+      console.log('');
+    }
+
+    const buckets = Array.isArray(data) ? data : (data?.buckets ?? data?.data ?? []);
+    if (buckets.length) {
+      const COL = [22, 10, 10, 10, 10];
+      const header = ['Period', 'Total', 'Resolved', 'Missed', 'Bot'];
+      console.log('  ' + header.map((h, i) => h.padEnd(COL[i])).join(''));
+      console.log('  ' + '─'.repeat(COL.reduce((a, b) => a + b, 0)));
+      for (const b of buckets) {
+        const label = b.period ?? b.date ?? b.bucket ?? '—';
+        const row = [
+          String(label).slice(0, 20),
+          fmtNum(b.total ?? b.totalConversations),
+          fmtNum(b.resolved),
+          fmtNum(b.missed),
+          fmtNum(b.botContained ?? b.bot),
+        ];
+        console.log('  ' + row.map((v, i) => String(v).padEnd(COL[i])).join(''));
+      }
+    }
+    console.log('');
+  },
+};
+
+// ── callactivity command ───────────────────────────────────────────────────────
+// Unified call history across every origin: agent-dialed (CTI), inbound, IVR
+// outbound single calls, and auto-dialer campaigns. Merges velaro-messaging's
+// Voice/CallRecords/history with this repo's own campaign-call data (not yet
+// mirrored into CallRecord — see CallActivityController.cs) so a manager can
+// answer "how many calls did this agent really make?" from one command.
+const callactivityCommand = {
+  command:  'callactivity',
+  describe: 'Unified call history report (agent-dialed, inbound, IVR outbound, auto-dialer campaigns)',
+  builder:  (y) => y
+    .option('agentId',       { type: 'number', describe: 'Filter to a specific agent' })
+    .option('direction',     { type: 'string', choices: ['Inbound', 'Outbound'], describe: 'Filter by call direction' })
+    .option('origin',        { type: 'string', choices: ['CtiManual', 'InboundExternal', 'AutoDialerCampaign', 'IvrOutboundSingle'], describe: 'Filter by call origin' })
+    .option('providerSlug',  { type: 'string', describe: 'Filter by provider (e.g. Twilio, SkySwitch)' })
+    .option('dateRangeDays', { type: 'number', default: 30, describe: 'Lookback window in days (default 30)' })
+    .option('disposition',   { type: 'string', describe: 'Filter by disposition code' })
+    .option('page',          { type: 'number', default: 1 })
+    .option('pageSize',      { type: 'number', default: 50 }),
+  handler: async (argv) => {
+    const params = new URLSearchParams();
+    params.set('page', String(argv.page));
+    params.set('pageSize', String(argv.pageSize));
+    params.set('dateRangeDays', String(argv.dateRangeDays));
+    if (argv.agentId)      params.set('agentId', String(argv.agentId));
+    if (argv.direction)    params.set('direction', argv.direction);
+    if (argv.origin)       params.set('origin', argv.origin);
+    if (argv.providerSlug) params.set('providerSlug', argv.providerSlug);
+    if (argv.disposition)  params.set('disposition', argv.disposition);
+    const qs = params.toString();
+
+    let messagingItems = [];
+    let messagingErr = null;
+    try {
+      const r = await messagingRequest('GET', `/Voice/CallRecords/history?${qs}`);
+      messagingItems = Array.isArray(r?.items) ? r.items : [];
+    } catch (e) {
+      messagingErr = e;
+    }
+
+    let campaignItems = [];
+    let campaignErr = null;
+    if (!argv.origin || argv.origin === 'AutoDialerCampaign') {
+      try {
+        const r = await request('GET', `/CallActivity/CampaignCalls?${qs}`);
+        campaignItems = Array.isArray(r?.items) ? r.items : [];
+      } catch (e) {
+        campaignErr = e;
+      }
+    }
+
+    if (messagingErr && campaignErr) {
+      console.error(`Failed to load call activity from either source: ${messagingErr.message}`);
+      process.exit(1);
+    }
+    if (messagingErr) console.error(`\x1b[33m⚠\x1b[0m Live call history unavailable (${messagingErr.message}) — showing auto-dialer campaign calls only.`);
+    if (campaignErr)  console.error(`\x1b[33m⚠\x1b[0m Campaign call history unavailable (${campaignErr.message}).`);
+
+    const items = [...messagingItems, ...campaignItems]
+      .sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+
+    section(`Call Activity (${items.length} calls, last ${argv.dateRangeDays}d)`);
+    if (!items.length) { console.log('  No calls match the current filters.'); return; }
+
+    const ORIGIN_LABELS = {
+      CtiManual: 'Agent-Dialed',
+      InboundExternal: 'Inbound',
+      AutoDialerCampaign: 'Auto-Dialer Campaign',
+      IvrOutboundSingle: 'IVR Outbound',
+    };
+    for (const c of items) {
+      const originLabel = ORIGIN_LABELS[c.origin] ?? c.origin ?? 'Unknown';
+      console.log(`  [${originLabel}] ${c.startedAt ?? '—'} | ${c.agentName ?? 'Auto-Dialer'} | ${c.providerSlug ?? '—'} | ${c.fromNumber ?? '—'} → ${c.toNumber ?? '—'} | ${fmtSeconds(c.durationSeconds)} | ${c.disposition ?? '—'}${c.associationStatus ? ` | ${c.associationStatus}` : ''}`);
+    }
+    console.log('');
+  },
+};
+
+// -- worked-hours command --------------------------------------------------
+// Time Tracking: worked hours breakdown, entitlement-gated (EnableTimeTracking),
+// hard-capped server-side at MAX_WORKED_HOURS_RANGE_DAYS days per query -- validated
+// client-side too so we fail fast instead of round-tripping a guaranteed 400.
+const MAX_WORKED_HOURS_RANGE_DAYS = 90;
+
+const workedHoursCommand = {
+  command:  'worked-hours',
+  describe: `Worked hours breakdown report: site KPIs + per-agent/per-day detail (Time Tracking, max ${MAX_WORKED_HOURS_RANGE_DAYS}-day range per query)`,
+  builder:  (y) => y
+    .option('start', { type: 'string', demandOption: true, describe: 'Start date (ISO 8601 or YYYY-MM-DD)' })
+    .option('end',   { type: 'string', demandOption: true, describe: `End date (ISO 8601 or YYYY-MM-DD) -- must be at most ${MAX_WORKED_HOURS_RANGE_DAYS} days after --start` }),
+  handler: async (argv) => {
+    const start = new Date(argv.start);
+    const end   = new Date(argv.end);
+    if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) {
+      console.error('--start and --end must be valid dates (ISO 8601 or YYYY-MM-DD).');
+      process.exit(1);
+    }
+    const rangeDays = (end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24);
+    if (rangeDays > MAX_WORKED_HOURS_RANGE_DAYS) {
+      console.error(`Date range too large (${rangeDays.toFixed(1)} days). Worked Hours can be queried for at most ${MAX_WORKED_HOURS_RANGE_DAYS} days at a time.`);
+      process.exit(1);
+    }
+
+    let data;
+    try {
+      data = await messagingRequest('POST', '/Reports/worked-hours-breakdown', { Start: start.toISOString(), End: end.toISOString() });
+    } catch (err) {
+      if (/403/.test(err.message)) {
+        console.error('Time Tracking is not enabled for this account.');
+        process.exit(1);
+      }
+      if (/400/.test(err.message)) {
+        console.error(`Server rejected the request: ${err.message}`);
+        process.exit(1);
+      }
+      throw err;
+    }
+
+    section('Worked Hours Breakdown');
+    if (argv.start || argv.end) {
+      console.log(`  Period: ${argv.start} -> ${argv.end}`);
+    }
+
+    const k = data?.kpis ?? {};
+    fmtRow('Total worked hours',      fmtNum(k.totalWorkedHours));
+    fmtRow('Agent count',             fmtNum(k.agentCount));
+    fmtRow('Unworked absent days',    fmtNum(k.daysUnworkedAbsent));
+    fmtRow('Excused days',            fmtNum(k.excusedDays));
+
+    const agents = Array.isArray(data?.agentMetrics) ? data.agentMetrics : [];
+    if (!agents.length) {
+      console.log(`\n  ${data?.message ?? 'No agent data for the selected range (no WorkSchedules configured for this site).'}\n`);
+      return;
+    }
+
+    console.log('');
+    const COL = [28, 14, 18, 14];
+    const header = ['Agent', 'Worked Hrs', 'Unworked Absent', 'Excused'];
+    console.log('  ' + header.map((h, i) => h.padEnd(COL[i])).join(''));
+    console.log('  ' + '-'.repeat(COL.reduce((a, b) => a + b, 0)));
+    for (const a of agents) {
+      const row = [
+        (a.agentName ?? `Agent ${a.agentId}`).slice(0, 26),
+        fmtNum(a.workedHours),
+        fmtNum(a.unworkedAbsentDays),
+        fmtNum(a.excusedDays),
+      ];
+      console.log('  ' + row.map((v, i) => String(v).padEnd(COL[i])).join(''));
+    }
+    console.log('');
+  },
+};
+
+// ── top-level report command ──────────────────────────────────────────────────
+
+export const reportCommand = {
+  command:  'report',
+  describe: 'Analytics reports: call center, service level, conversations, call activity',
+  builder:  (y) => y
+    .command(callcenterCommand)
+    .command(servicelevelCommand)
+    .command(conversationsCommand)
+    .command(callactivityCommand)
+    .command(workedHoursCommand)
+    .demandCommand(1, 'Specify a report type. Run "velaro report --help" for options.'),
+  handler: () => {},
+};