@velaro/cli 0.7.0 → 1.4.8

package/lib/commands/calendly.js

@@ -0,0 +1,62 @@
+import { request } from '../api.js';
+import { runCommand } from '../run.js';
+
+// ── velaro calendly ───────────────────────────────────────────────────────────
+// Superadmin commands to configure Calendly for any customer site.
+// Requires a Velaro admin JWT (site 1032).
+
+export const calendlyCommand = {
+  command:  'calendly <subcommand>',
+  describe: 'Manage Calendly integration for any site (Velaro admin only)',
+  builder:  yargs => yargs
+    .command({
+      command:  'status',
+      describe: 'Show Calendly config for a site',
+      builder:  y => y.option('site', { type: 'number', demandOption: true, describe: 'Site ID' }),
+      handler:  runCommand(async argv => {
+        const data = await request('GET', `/Calendly/superadmin/status?siteId=${argv.site}`);
+        if (!data.configured) {
+          console.log(`\nSite ${argv.site}: Calendly NOT configured.\n`);
+          return;
+        }
+        console.log(`\nSite ${argv.site}: Calendly configured ✓`);
+        console.log(`  Account:      ${data.userName}`);
+        console.log(`  Default type: ${data.defaultEventTypeName || '(none)'}`);
+        console.log(`  Single-use:   ${data.useSingleUseLinks ? 'yes' : 'no'}\n`);
+      }),
+    })
+    .command({
+      command:  'configure',
+      describe: 'Set up or update Calendly for a site',
+      builder:  y => y
+        .option('site',        { type: 'number',  demandOption: true,  describe: 'Site ID' })
+        .option('token',       { type: 'string',  demandOption: true,  describe: 'Calendly Personal Access Token' })
+        .option('event-uri',   { type: 'string',  demandOption: false, describe: 'Default event type URI' })
+        .option('event-name',  { type: 'string',  demandOption: false, describe: 'Default event type display name' })
+        .option('label',       { type: 'string',  demandOption: false, describe: 'Display label (e.g. "Acme Demo Booking")' })
+        .option('single-use',  { type: 'boolean', default: true,       describe: 'Use single-use scheduling links' }),
+      handler:  runCommand(async argv => {
+        const data = await request('POST', `/Calendly/superadmin/config?siteId=${argv.site}`, {
+          accessToken:          argv.token,
+          displayName:          argv.label || '',
+          defaultEventTypeUri:  argv['event-uri']  || '',
+          defaultEventTypeName: argv['event-name'] || '',
+          useSingleUseLinks:    argv['single-use'],
+        });
+        if (!data.success) throw new Error(data.error || 'Configure failed');
+        console.log(`\n✓ Calendly configured for site ${argv.site}`);
+        console.log(`  Account: ${data.userName}`);
+        console.log(`  Org:     ${data.organizationUri}\n`);
+      }),
+    })
+    .command({
+      command:  'disconnect',
+      describe: 'Remove Calendly config from a site',
+      builder:  y => y.option('site', { type: 'number', demandOption: true, describe: 'Site ID' }),
+      handler:  runCommand(async argv => {
+        await request('DELETE', `/Calendly/superadmin/config?siteId=${argv.site}`);
+        console.log(`\n✓ Calendly disconnected from site ${argv.site}\n`);
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: status | configure | disconnect'),
+};

package/lib/commands/callback.js

@@ -0,0 +1,125 @@
+import { messagingGet } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro callback report -----------------------------------------------------
+// CLI surface for the Callback Scheduling supervisor report (Stage 5 UI /
+// Stage 8 MCP tool `callback_scheduling_report`). Endpoint lives in
+// velaro-messaging at GET CallbackScheduling/report and applies the caller's
+// siteId from the vmsg-siteId header (see api.js messagingRequest) -- never
+// from CLI args, same IDOR pattern as every other messaging* command here.
+//
+// Backend contract: server/Velaro.Messaging/Controllers/CallbackSchedulingReportController.cs
+// Response shape: { summary: { requested, completed, missed, overdue, rescheduled,
+// byFulfillmentMode }, total, page, pageSize, items[] }. The endpoint never throws --
+// a query failure degrades to an empty/zeroed report, so this command has nothing
+// special to do for that case beyond printing whatever comes back.
+
+const DIM  = '\x1b[2m';
+const RED  = '\x1b[31m';
+const YEL  = '\x1b[33m';
+const GRN  = '\x1b[32m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+function statusColor(status) {
+  switch (status) {
+    case 'Fulfilled': return GRN;
+    case 'Failed':    return RED;
+    case 'Pending':
+    case 'Scheduled': return YEL;
+    default:          return RST;
+  }
+}
+
+function fmtDate(d) {
+  return d ? new Date(d).toISOString().replace('T', ' ').slice(0, 19) : '-';
+}
+
+function printSummary(summary) {
+  console.log(`\n${BOLD}Callback Scheduling Report${RST}`);
+  console.log(`  Requested:   ${summary?.requested ?? 0}`);
+  console.log(`  Completed:   ${GRN}${summary?.completed ?? 0}${RST}`);
+  console.log(`  Missed:      ${RED}${summary?.missed ?? 0}${RST}`);
+  console.log(`  Overdue:     ${YEL}${summary?.overdue ?? 0}${RST}`);
+  console.log(`  Rescheduled: ${summary?.rescheduled ?? 0}`);
+
+  const byMode = summary?.byFulfillmentMode ?? {};
+  const modes = Object.keys(byMode);
+  if (modes.length) {
+    console.log(`  By fulfillment mode:`);
+    for (const mode of modes) console.log(`    ${mode.padEnd(16)} ${byMode[mode]}`);
+  }
+}
+
+function printRows(data) {
+  const items = data?.items ?? [];
+  if (!items.length) {
+    console.log('\n  No callback requests match this filter.\n');
+    return;
+  }
+
+  console.log(`\n  ${data.items.length} of ${data.total} requests (page ${data.page}, pageSize ${data.pageSize})\n`);
+
+  const COL = [8, 12, 16, 12, 20, 20, 18];
+  const header = ['Id', 'Source', 'Mode', 'Status', 'Requested For', 'Created', 'Caller'];
+  console.log('  ' + header.map((h, i) => h.padEnd(COL[i])).join(''));
+  console.log('  ' + '-'.repeat(COL.reduce((a, b) => a + b, 0)));
+
+  for (const r of items) {
+    const color = statusColor(r.status);
+    const caller = [r.callerName, r.callerPhone].filter(Boolean).join(' / ') || '-';
+    const padded = [
+      String(r.id ?? '-').padEnd(COL[0]),
+      String(r.source ?? '-').padEnd(COL[1]),
+      String(r.fulfillmentMode ?? '-').padEnd(COL[2]),
+      `${color}${String(r.status ?? '-').padEnd(COL[3])}${RST}`,
+      fmtDate(r.requestedForUtc).padEnd(COL[4]),
+      fmtDate(r.createdAtUtc).padEnd(COL[5]),
+      caller,
+    ];
+    console.log('  ' + padded.join(''));
+    if (r.failureReason) console.log(`    ${DIM}Failure: ${r.failureReason}${RST}`);
+  }
+
+  if (data.total > data.page * data.pageSize) {
+    console.log(`\n  ${DIM}More results -- use --page ${data.page + 1}${RST}`);
+  }
+
+  console.log('');
+}
+
+async function reportHandler(argv) {
+  const qs = new URLSearchParams();
+  if (argv.status)         qs.set('status', argv.status);
+  if (argv.mode)           qs.set('fulfillmentMode', argv.mode);
+  if (argv.days)           qs.set('dateRangeDays', String(argv.days));
+  qs.set('page',     String(Math.max(1, argv.page ?? 1)));
+  qs.set('pageSize', String(Math.min(200, argv.pageSize ?? 50)));
+
+  const data = await messagingGet(`/CallbackScheduling/report?${qs.toString()}`);
+
+  printSummary(data?.summary);
+  printRows(data);
+}
+
+const reportCommand = {
+  command:  'report',
+  describe: 'Callback Scheduling supervisor report -- summary counts + drill-down rows',
+  builder:  (y) => y
+    .option('status',   { describe: 'Filter: Pending, Scheduled, Fulfilled, Failed', type: 'string' })
+    .option('mode',     { describe: 'Filter by fulfillment mode (e.g. AiCallback, AgentCallback)', type: 'string' })
+    .option('days',     { describe: 'Date range lookback in days, 1-365 (default 30)', type: 'number', default: 30 })
+    .option('page',     { describe: 'Page number', type: 'number', default: 1 })
+    .option('pageSize', { describe: 'Results per page, max 200 (default 50)', type: 'number', default: 50 }),
+  handler: runCommand(reportHandler),
+};
+
+export const callbackCommand = {
+  command:  'callback <subcommand>',
+  describe: 'Callback Scheduling reporting',
+  builder: (y) => y
+    .command(reportCommand)
+    .demandCommand(1, 'Specify a callback subcommand.')
+    .strict(),
+  handler: () => {},
+};

package/lib/commands/callrail.js

@@ -0,0 +1,88 @@
+/**
+ * velaro callrail - CallRail call-source marketing attribution
+ *
+ *   velaro callrail attributions    List recent call attribution records
+ *   velaro callrail logs            View integration activity logs
+ */
+
+import { request } from '../api.js';
+
+const GRN  = '\x1b[32m';
+const RED  = '\x1b[31m';
+const CYN  = '\x1b[36m';
+const DIM  = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+// -- attributions ----------------------------------------------------------------
+
+async function attributionsHandler(argv) {
+  const limit = Math.min(100, argv.limit ?? 25);
+  const rows = await request('GET', '/CallRail/attributions');
+  if (!Array.isArray(rows) || rows.length === 0) {
+    console.log('\nNo call attribution records found. Connect CallRail under Integrations, then add a webhook in your CallRail account.\n');
+    return;
+  }
+  const trimmed = rows.slice(0, limit);
+  console.log(`\n${BOLD}${trimmed.length} of ${rows.length} call attribution record(s)${RST}\n`);
+  for (const r of trimmed) {
+    const provider = r.ProviderSlug ?? r.Provider ?? 'CallRail';
+    const ts = (r.ReceivedAtUtc ?? '').slice(0, 19).replace('T', ' ');
+    console.log(`  ${DIM}${ts}${RST}  ${CYN}${r.PhoneNumberNormalized}${RST}  [${provider}]`);
+    console.log(`       ${r.Source ?? '(unknown source)'} / ${r.Campaign ?? '(no campaign)'} / ${r.Medium ?? '(no medium)'}`);
+    if (r.RecordingUrl) console.log(`       ${DIM}recording: ${r.RecordingUrl}${RST}`);
+  }
+  console.log('');
+}
+
+// -- logs --------------------------------------------------------------------------
+
+async function logsHandler(argv) {
+  const params = new URLSearchParams();
+  if (argv.severity) params.set('severity', argv.severity);
+  if (argv.search)   params.set('search', argv.search);
+  params.set('pageSize', String(Math.min(100, argv.pageSize ?? 25)));
+  const data = await request('GET', `/Integration/Logs/CallRail?${params}`);
+  const items = data?.items ?? [];
+  if (items.length === 0) {
+    console.log('\nNo CallRail activity log entries found.\n');
+    return;
+  }
+  console.log(`\n${BOLD}${items.length} of ${data.total} CallRail activity entries${RST}\n`);
+  for (const item of items) {
+    const ts  = new Date(item.createdAt).toISOString().replace('T', ' ').slice(0, 19);
+    const sev = item.severity === 'Error'   ? `${RED}${item.severity}${RST}  ` :
+                item.severity === 'Warning' ? `${'\x1b[33m'}${item.severity}${RST}` :
+                `${DIM}${item.severity}${RST}  `;
+    console.log(`  ${DIM}${ts}${RST}  ${sev}  [${item.category ?? '?'}]  ${item.message ?? ''}`);
+    if (item.additionalInfo) console.log(`           ${DIM}${item.additionalInfo}${RST}`);
+  }
+  if (data.total > items.length) console.log(`\n  ${DIM}${data.total - items.length} more, use --page-size to see more${RST}`);
+  console.log('');
+}
+
+// -- command export ------------------------------------------------------------------
+
+export const callrailCommand = {
+  command:  'callrail <subcommand>',
+  describe: 'CallRail call-source marketing attribution',
+  builder: y => y
+    .command({
+      command:  'attributions',
+      describe: 'List recent call attribution records',
+      builder: yy => yy
+        .option('limit', { describe: 'Max results (default: 25)', type: 'number', default: 25 }),
+      handler: attributionsHandler,
+    })
+    .command({
+      command:  'logs',
+      describe: 'View CallRail integration activity logs',
+      builder: yy => yy
+        .option('severity',  { describe: 'Filter: Info, Warning, Error', type: 'string' })
+        .option('search',    { describe: 'Text to search for in messages', type: 'string' })
+        .option('page-size', { describe: 'Results per page (default: 25)', type: 'number', default: 25 }),
+      handler: logsHandler,
+    })
+    .demandCommand(1, 'Specify a subcommand. Try: velaro callrail --help'),
+  handler: () => {},
+};

package/lib/commands/campaigns.js

@@ -0,0 +1,44 @@
+/**
+ * velaro campaigns - Email campaign reporting
+ *
+ *   velaro campaigns benchmarks    Your broadcast open/click rate vs. the Velaro average
+ */
+
+import { request } from '../api.js';
+import { runCommand } from '../run.js';
+
+const GRN  = '\x1b[32m';
+const CYN  = '\x1b[36m';
+const DIM  = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+// -- benchmarks ------------------------------------------------------------------
+
+async function benchmarksHandler() {
+  const r = await request('GET', '/EmailCampaigns/Benchmarks');
+  console.log(`\n${BOLD}Broadcast Email Benchmarks (last ${r.windowDays} days)${RST}\n`);
+  console.log(`  You:  open ${CYN}${r.yourOpenRate}%${RST}  |  click ${CYN}${r.yourClickRate}%${RST}  (${r.yourSentCount} sent)`);
+  if (r.benchmarkAvailable) {
+    console.log(`  Velaro average:  open ${GRN}${r.benchmarkOpenRate}%${RST}  |  click ${GRN}${r.benchmarkClickRate}%${RST}  (${r.benchmarkSampleSize} contributing sites)`);
+  } else {
+    console.log(`  ${DIM}Velaro average not published yet — not enough participating sites.${RST}`);
+  }
+  console.log(`\n  ${DIM}${r.note}${RST}\n`);
+}
+
+// -- command export ------------------------------------------------------------------
+
+export const campaignsCommand = {
+  command:  'campaigns <subcommand>',
+  describe: 'Email campaign reporting',
+  builder: y => y
+    .command({
+      command:  'benchmarks',
+      describe: 'Your broadcast email open/click rate vs. the all-Velaro-customer average',
+      handler: runCommand(benchmarksHandler),
+    })
+    .demandCommand(1, 'Specify a subcommand. Try: velaro campaigns --help')
+    .strict(),
+  handler: () => {},
+};

package/lib/commands/case.js

@@ -0,0 +1,102 @@
+import { messagingGet, messagingPost, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+
+// -- velaro case ------------------------------------------------------------
+// CLI surface for Case Management (per-site configurable "Case Type" stages +
+// custom fields, layered on ticketing). Backend lives in velaro-messaging:
+//   CaseTypesController.cs  -> GET/POST/PUT/DELETE CaseTypes
+//   CasesController.cs      -> GET Cases/board/{caseTypeId}, POST Cases, PUT Cases/{id}/stage
+// SiteId is always applied server-side from the caller's auth context -- never
+// passed as a CLI arg, same IDOR pattern as every other messaging* command here.
+
+const BOLD = '\x1b[1m';
+const DIM  = '\x1b[2m';
+const RST  = '\x1b[0m';
+
+async function typesHandler() {
+  const types = await messagingGet('/CaseTypes');
+  if (!Array.isArray(types) || types.length === 0) {
+    console.log('\n  No case types configured for this site.\n');
+    return;
+  }
+  console.log(`\n${BOLD}Case Types${RST}`);
+  for (const t of types) {
+    console.log(`  #${t.id}  ${t.name}  ${DIM}(${t.stages?.length ?? 0} stages, ${t.fields?.length ?? 0} fields, prefix ${t.caseNumberPrefix})${RST}`);
+  }
+  console.log('');
+}
+
+async function boardHandler(argv) {
+  const data = await messagingGet(`/Cases/board/${argv.caseTypeId}`);
+  const stages = data?.caseType?.stages ?? [];
+  const cases = data?.cases ?? [];
+  console.log(`\n${BOLD}${data?.caseType?.name ?? 'Case'} Board${RST}`);
+  for (const s of stages) {
+    const inStage = cases.filter((c) => c.stage === s.key);
+    console.log(`\n  ${BOLD}${s.label}${RST} (${inStage.length})`);
+    for (const c of inStage) {
+      console.log(`    ${c.caseNumber}  ${DIM}${c.subject ?? ''}${RST}`);
+    }
+  }
+  console.log('');
+}
+
+async function moveHandler(argv) {
+  const result = await messagingPut(`/Cases/${argv.caseId}/stage`, { stage: argv.stage });
+  console.log(`\n  Case ${result?.caseNumber ?? argv.caseId} moved to stage "${result?.stage ?? argv.stage}".\n`);
+}
+
+async function createTypeHandler(argv) {
+  const stages = argv.stages.split(',').map((label, i) => ({
+    key: label.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_'),
+    label: label.trim(),
+  }));
+  const result = await messagingPost('/CaseTypes', {
+    name: argv.name,
+    caseNumberPrefix: argv.prefix,
+    stages,
+    fields: [],
+  });
+  console.log(`\n  Created case type "${result.name}" (id ${result.id}).\n`);
+}
+
+const typesCommand = {
+  command: 'types',
+  describe: 'List this site\'s configured case types',
+  handler: runCommand(typesHandler),
+};
+
+const createTypeCommand = {
+  command: 'create-type',
+  describe: 'Create a new case type (stage pipeline)',
+  builder: (y) => y
+    .option('name', { describe: 'Case type name', type: 'string', demandOption: true })
+    .option('prefix', { describe: 'Case number prefix, e.g. UI or COL', type: 'string', default: 'CASE' })
+    .option('stages', { describe: 'Comma-separated stage labels, e.g. "New,In Review,Resolved"', type: 'string', demandOption: true }),
+  handler: runCommand(createTypeHandler),
+};
+
+const boardCommand = {
+  command: 'board <caseTypeId>',
+  describe: 'Show a case type\'s board grouped by stage',
+  handler: runCommand(boardHandler),
+};
+
+const moveCommand = {
+  command: 'move <caseId> <stage>',
+  describe: 'Move a case to a different stage (the same mutation the Kanban board drag performs)',
+  handler: runCommand(moveHandler),
+};
+
+export const caseCommand = {
+  command: 'case <subcommand>',
+  describe: 'Case Management -- configurable case types + board',
+  builder: (y) => y
+    .command(typesCommand)
+    .command(createTypeCommand)
+    .command(boardCommand)
+    .command(moveCommand)
+    .demandCommand(1, 'Specify a case subcommand.')
+    .strict(),
+  handler: () => {},
+};