@velaro/cli 1.4.102 → 1.4.103

package/lib/commands/site-builder.js

@@ -0,0 +1,30 @@
+import { messagingGet } from '../api.js';
+import { runCommand } from '../run.js';
+
+// velaro site-builder connect-info
+// Backend: velaro-messaging SiteBuilderConnectController (PR #1874)
+//   GET /integrations/site-builder/connect-info -> signed-in caller's own site id + chat snippet
+// The same data is available from the Velaro MCP tool site_connect_info.
+
+async function connectInfoHandler(argv) {
+  const info = await messagingGet('/integrations/site-builder/connect-info');
+  if (argv.json) { console.log(JSON.stringify(info, null, 2)); return; }
+  for (const [k, v] of Object.entries(info ?? {})) {
+    console.log(`${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`);
+  }
+}
+
+export const siteBuilderCommand = {
+  command:  'site-builder <subcommand>',
+  describe: 'Website builder connection (site ID and chat snippet)',
+  builder:  (y) => y
+    .command({
+      command:  'connect-info',
+      describe: 'Show your site ID and chat snippet for pasting into a site builder',
+      builder:  (y2) => y2.option('json', { describe: 'Print raw JSON', type: 'boolean' }),
+      handler:  runCommand(connectInfoHandler),
+    })
+    .demandCommand(1, 'Specify a subcommand: connect-info')
+    .strict(),
+  handler: () => {},
+};

package/lib/commands/support.js

@@ -106,6 +106,23 @@ async function agentLookup(args) {
   console.log(JSON.stringify(result, null, 2));
 }
 
+async function siteAuthMode(args) {
+  // Wraps the existing staff endpoints DatabaseTool/AuthMode/{siteId} (GET/PUT). No new backend.
+  const site = Number(args.site);
+  if (!Number.isInteger(site) || site <= 0) { console.error('site must be a positive integer.'); process.exit(1); }
+  try {
+    if (args.mode) {
+      const allowLocalLogin = args.allowLocalLogin === undefined ? true : (args.allowLocalLogin === true || args.allowLocalLogin === 'true');
+      await request('PUT', `DatabaseTool/AuthMode/${site}`, { authMode: args.mode, allowLocalLogin });
+    }
+    const r = await request('GET', `DatabaseTool/AuthMode/${site}`);
+    console.log(JSON.stringify({ siteId: r.siteId, authMode: r.authMode, allowLocalLogin: r.allowLocalLogin, hasConfig: r.hasConfig }));
+  } catch (e) {
+    console.error(`site-auth-mode failed: ${e.message}`);
+    process.exit(1);
+  }
+}
+
 async function addSiteUser(args) {
   // Password via --password or VELARO_NEW_USER_PASSWORD env (preferred; keeps it out of shell history). Never printed.
   const password = args.password || process.env.VELARO_NEW_USER_PASSWORD;
@@ -206,6 +223,11 @@ export function supportCommand(yargs) {
       .option('firstName', { type: 'string' })
       .option('lastName',  { type: 'string' })
     , a => addSiteUser(a))
+    .command('site-auth-mode', 'Show or set a site messaging-app auth mode (V10|Dual|EntraId) and AllowLocalLogin (staff only)', y => y
+      .option('site',            { type: 'number', demandOption: true, desc: 'Target site ID' })
+      .option('mode',            { type: 'string', choices: ['V10', 'Dual', 'EntraId'], desc: 'Set this auth mode (omit to just show)' })
+      .option('allow-local-login', { type: 'string', desc: 'true|false (default true when setting)' })
+    , a => siteAuthMode({ ...a, allowLocalLogin: a['allow-local-login'] }))
     .command('toggle-flag', 'Toggle a single legacy Subscription.cs feature flag on a site (superadmin only, allowlisted flags)', y => y
       .option('site',    { type: 'number',  demandOption: true, desc: 'Site ID' })
       .option('flag',    { type: 'string',  demandOption: true, desc: 'Flag name, e.g. EnableScraperBotIndexing (must be on SupportToolsController.AllowedFeatureFlags)' })

package/lib/commands/teams.js

@@ -191,13 +191,23 @@ export const teamsCommand = {
             .option('enabled', { type: 'boolean', describe: 'Turn Teams Channel on/off' })
             .option('welcome-message', { type: 'string', describe: 'Sent when a Teams user opens a new conversation. Use {{user.name}} for their name.' })
             .option('team-id', { type: 'number', describe: 'Route new conversations to this team id' })
-            .option('clear-team-id', { type: 'boolean', describe: 'Clear the team override and use the site default team' }),
+            .option('clear-team-id', { type: 'boolean', describe: 'Clear the team override and use the site default team' })
+            .option('prechat', { type: 'boolean', describe: 'Ask prechat questions before a conversation opens' })
+            .option('prechat-fields', { type: 'string', describe: 'JSON array of {key,label,required}; replaces the prechat questions (max 6)' })
+            .option('quick-reply', { type: 'array', string: true, describe: 'Quick-reply button label (repeatable, max 6); pass --quick-reply "" to clear' })
+            .option('post-chat', { type: 'boolean', describe: 'Send the post-chat message when an agent closes the conversation' })
+            .option('post-chat-message', { type: 'string', describe: 'Post-chat text ({{user.name}} = first name); empty string clears it' }),
         async (argv) => {
           const body = {};
           if (argv.enabled !== undefined) body.enabled = argv.enabled;
           if (argv.welcomeMessage !== undefined) body.welcomeMessage = argv.welcomeMessage;
           if (argv.teamId !== undefined) body.teamId = argv.teamId;
           if (argv.clearTeamId) body.clearTeamId = true;
+          if (argv.prechat !== undefined) body.prechatEnabled = argv.prechat;
+          if (argv.prechatFields !== undefined) body.prechatFields = JSON.parse(argv.prechatFields);
+          if (argv.quickReply !== undefined) body.quickReplies = argv.quickReply.filter((r) => r !== '');
+          if (argv.postChat !== undefined) body.postChatEnabled = argv.postChat;
+          if (argv.postChatMessage !== undefined) body.postChatMessage = argv.postChatMessage;
           const result = Object.keys(body).length
             ? await request('PUT', '/TeamsBot/ChannelConfig', body)
             : await request('GET', '/TeamsBot/ChannelConfig');

package/lib/commands/workflow.js

@@ -14,6 +14,7 @@ export const workflowCommand = {
       .command(workflowCreateCommand)
       .command(workflowEnableCommand)
       .command(workflowDisableCommand)
+      .command(workflowRunCommand)
       .command(workflowNodeOptionsCommand)
       .command(workflowIntegrityScanCommand)
       .command(workflowAiFollowupsCommand)
@@ -117,6 +118,38 @@ const workflowCreateCommand = {
 
 // ── enable / disable ──────────────────────────────────────────────────────────
 
+// ── run ────────────────────────────────────────────────────────────────────────
+
+const workflowRunCommand = {
+  command:  'run <id>',
+  describe: 'Queue a published workflow now, optionally seeding it with a JSON context file',
+  builder:  (y) => y
+    .positional('id', { type: 'number', describe: 'Workflow ID' })
+    .option('context', { type: 'string', describe: 'Path to a JSON file with a shallow object of context values (max 50 keys, 4KB)' }),
+  handler:  runCommand(async (argv) => {
+    await requireFeature('enableAutomation', 'Workflows');
+
+    let body = {};
+    if (argv.context) {
+      let parsed;
+      try {
+        parsed = JSON.parse(fs.readFileSync(argv.context, 'utf8'));
+      } catch (e) {
+        console.error(`Could not read ${argv.context} as JSON: ${e.message}`);
+        process.exit(1);
+      }
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        console.error('Context file must contain a JSON object, like {"customerId":"123"}.');
+        process.exit(1);
+      }
+      body = { contextOverride: parsed };
+    }
+
+    const result = await messagingPost(`/Workflows/${argv.id}/run-now`, body);
+    console.log(`Workflow ${argv.id} queued${result?.jobId ? ` (job #${result.jobId})` : ''}.`);
+  }),
+};
+
 const workflowEnableCommand = {
   command:  'enable <id>',
   describe: 'Enable a workflow',

package/lib/commands/zoom-phone.js

@@ -48,11 +48,26 @@ async function setHandler(argv) {
   await statusHandler();
 }
 
+async function numbersHandler() {
+  const r = await messagingGet('/ZoomPhoneCti/numbers');
+  const list = r?.phoneNumbers || [];
+  if (!list.length) {
+    console.log(`\n${YEL}Zoom returned no assigned phone numbers for this account.${RST}\n`);
+    return;
+  }
+  console.log(`\n${BOLD}Zoom Phone numbers (assigned)${RST}`);
+  for (const n of list) {
+    console.log(`  ${n.number || '(no number)'}  ${DIM}${n.displayName || ''}  status=${n.status || '?'}  assignee=${n.assigneeType || '?'} ext=${n.assigneeExtension || '-'}${RST}`);
+  }
+  console.log('');
+}
+
 export const zoomPhoneCommand = {
   command: 'zoom-phone <subcommand>',
   describe: 'Zoom Phone screen-pop configuration (account_id + webhook secret)',
   builder: y => y
     .command({ command: 'status', describe: 'Show the Zoom Phone configuration for this site', builder: yy => yy, handler: statusHandler })
+    .command({ command: 'numbers', describe: 'List the Zoom Phone numbers on the connected account (which number fires call events)', builder: yy => yy, handler: numbersHandler })
     .command({
       command: 'set',
       describe: 'Save the Zoom account_id and/or webhook secret (apply-if-present)',

package/lib/enterprise-reports.test.js

@@ -5,7 +5,7 @@ import { enterpriseReportsCommand } from './commands/enterprise-reports.js';
 import { yearInReviewBody, lastTwelveWholeMonthsKeys } from './year-in-review-range.js';
 
 test('describe lists the five novel reports and the promise dismiss action', () => {
-  for (const r of ['repeat-contact', 'demand-coverage', 'bot-containment', 'effort-index', 'promise-ledger', 'promise-dismiss']) {
+  for (const r of ['repeat-contact', 'demand-coverage', 'bot-containment', 'effort-index', 'promise-ledger', 'promise-dismiss', 'new-agent-ramp']) {
     assert.ok(enterpriseReportsCommand.describe.includes(r), `${r} missing from describe`);
   }
 });

package/lib/entitlement-report-packages.test.js

@@ -0,0 +1,47 @@
+// `velaro entitlement report-packages` must stay wired to GET Entitlements/report-packages and render the five category packages.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { formatReportPackages } from './commands/entitlement.js';
+
+const sample = (siteId, enabled) => ({
+  siteId,
+  defaultOff: true,
+  plan: 'plan.enterprise-internal',
+  top: { slug: 'enterprise-reports', name: 'Enterprise Reports', tagline: 'Includes all five category packages.', enabled, reportCount: 2 },
+  categories: [
+    {
+      slug: 'reports-conversations-channels', name: 'Conversations & Channels', category: 'Conversations & Channels', tagline: 'Know what is coming in.', audience: 'Teams',
+      enabled, enabledCount: enabled ? 2 : 0, reportCount: 2,
+      reports: [
+        { id: 'conversations', name: 'Conversations', packageSlug: 'report-conversations', packageKey: 'EnableReportConversations', enabled },
+        { id: 'missed', name: 'Missed Chats', packageSlug: 'report-missed', packageKey: 'EnableReportMissed', enabled },
+      ],
+    },
+  ],
+});
+
+test('without a site the output lists the package and every report with no on/off marks', () => {
+  const out = formatReportPackages(sample(null, false));
+  assert.match(out, /Enterprise Reports \(enterprise-reports\) - plan plan\.enterprise-internal, default OFF/);
+  assert.match(out, /Conversations & Channels \(reports-conversations-channels\) 2 reports/);
+  assert.match(out, /Missed Chats \(missed\) - package report-missed, key EnableReportMissed/);
+  assert.doesNotMatch(out, /\[ON \]|\[off\]/);
+});
+
+test('with a site each report and category shows its on/off state', () => {
+  const on = formatReportPackages(sample(1032, true));
+  assert.match(on, /site 1032 \[ALL ON\]/);
+  assert.match(on, /\[ON \] 2\/2 reports/);
+  assert.match(on, /\[ON \] Conversations/);
+  const off = formatReportPackages(sample(40001, false));
+  assert.match(off, /\[off\] 0\/2 reports/);
+  assert.match(off, /\[off\] Missed Chats/);
+});
+
+test('the command calls the admin route and is registered in the usage line', () => {
+  const src = fs.readFileSync(new URL('./commands/entitlement.js', import.meta.url), 'utf8');
+  assert.ok(src.includes("`Entitlements/report-packages${q}`"));
+  assert.ok(src.includes(".command('report-packages'"));
+  assert.ok(src.includes('enterprise-reports | report-packages'));
+});

package/lib/logs-insights.test.js

@@ -0,0 +1,146 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  parseWindowMs, parseWhen, qs, commonParams, windowParams, parseExpiry, ptTime, trendText,
+  sparkline, clean, formatGroups, formatRegression, formatTrace, formatAnomalies, formatSites,
+  formatMutes, formatSensitive, logsInsightsCommand, INSIGHTS_BASE, INSIGHTS_META,
+  scoped, anomalyLevel, CALL_TIMEOUT_MS, BRIEF_TIMEOUT_MS, MAX_WINDOW_MS,
+} from './commands/logs-insights.js';
+
+const NOW = new Date('2026-10-12T12:00:00Z');
+const strip = s => s.replace(/\x1b\[[0-9;]*m/g, '');
+
+test('parseWindowMs handles m/h/d, falls back only when missing, throws on junk', () => {
+  assert.equal(parseWindowMs('30m'), 30 * 60_000);
+  assert.equal(parseWindowMs('6h'), 6 * 3_600_000);
+  assert.equal(parseWindowMs('2d'), 2 * 86_400_000);
+  assert.equal(parseWindowMs(undefined, 7), 7);
+  assert.equal(parseWindowMs('', 7), 7);
+  assert.throws(() => parseWindowMs('6hrs'), /Invalid duration/);
+  assert.throws(() => parseWindowMs('soon', 5), /Invalid duration/);
+});
+
+test('parseWhen: relative means "ago", ISO passes through, junk is null', () => {
+  assert.equal(parseWhen('2h', NOW).toISOString(), '2026-10-12T10:00:00.000Z');
+  assert.equal(parseWhen('2026-10-12T09:00:00Z', NOW).toISOString(), '2026-10-12T09:00:00.000Z');
+  assert.equal(parseWhen('banana', NOW), null);
+  assert.equal(parseWhen('', NOW), null);
+});
+
+test('parseExpiry: never/undefined -> undefined, duration is from now, junk throws', () => {
+  assert.equal(parseExpiry('never', NOW), undefined);
+  assert.equal(parseExpiry(undefined, NOW), undefined);
+  assert.equal(parseExpiry('7d', NOW), '2026-10-19T12:00:00.000Z');
+  assert.equal(parseExpiry('2026-12-01T00:00:00Z', NOW), '2026-12-01T00:00:00.000Z');
+  assert.throws(() => parseExpiry('someday', NOW), /--expires/);
+});
+
+test('qs skips empties and encodes', () => {
+  assert.equal(qs({ a: 'x y', b: '', c: undefined, d: 0, e: null }), '?a=x+y&d=0');
+  assert.equal(qs({}), '');
+});
+
+test('commonParams uppercases level and maps --site to siteId', () => {
+  assert.deepEqual(commonParams({ level: 'error', platform: 'v20', environment: 'Staging', site: 5 }),
+    { level: 'ERROR', platform: 'v20', environment: 'Staging', siteId: 5 });
+});
+
+test('windowParams spans --last ending now', () => {
+  const w = windowParams({ last: '6h' }, '24h', NOW);
+  assert.equal(w.from, '2026-10-12T06:00:00.000Z');
+  assert.equal(w.to, '2026-10-12T12:00:00.000Z');
+  assert.equal(windowParams({}, '24h', NOW).from, '2026-10-11T12:00:00.000Z');
+});
+
+test('routes target the messaging insights base', () => {
+  assert.equal(INSIGHTS_BASE, 'superadmin/logs/insights');
+  assert.equal(INSIGHTS_META, 'superadmin/logs/meta/insights');
+});
+
+test('trendText uses words, handles null', () => {
+  assert.equal(trendText(25), 'up 25%');
+  assert.equal(trendText(-12.34), 'down 12.3%');
+  assert.equal(trendText(0.3), 'flat');
+  assert.equal(trendText(null), 'n/a');
+});
+
+test('sparkline scales and tolerates empty / zeros', () => {
+  assert.equal(sparkline([]), '');
+  assert.equal(sparkline([0, 0]).length, 2);
+  const s = sparkline([0, 10]);
+  assert.equal(s[0], '▁');
+  assert.equal(s[1], '█');
+});
+
+test('clean strips control characters (terminal injection)', () => {
+  assert.equal(clean('a\x1b[31mb\x07c'), 'a[31mbc');
+});
+
+test('ptTime renders Pacific', () => {
+  assert.match(ptTime('2026-10-12T20:00:00Z'), /1:00.*PT$/);
+  assert.equal(ptTime(null), '-');
+});
+
+test('formatGroups shows servedFrom, truncation, new/muted flags and never emits raw escapes from messages', () => {
+  const out = strip(formatGroups({
+    servedFrom: 'Staging', truncated: true, scanned: 100,
+    groups: [{ fingerprint: 'fp', sampleMessage: 'boom \x1b[2J gone', logger: 'A.B', count: 3, sparkline: [1, 2, 3], isNew: true, muted: false, sitesCount: 2, firstSeen: '2026-10-12T10:00:00Z', lastSeen: '2026-10-12T11:00:00Z' }],
+  }));
+  assert.match(out, /Showing Staging logs/);
+  assert.match(out, /Results capped after scanning 100/);
+  assert.match(out, /\[new\]/);
+  assert.doesNotMatch(out, /\x1b/);
+  assert.equal(strip(formatGroups({ groups: [] })), 'No error groups.');
+});
+
+test('other formatters render and survive empty responses', () => {
+  assert.match(strip(formatRegression({ before: { total: 5, errors: 1 }, after: { total: 9, errors: 4 }, newGroups: [], increased: [{ before: 1, after: 5, ratio: 5, sampleMessage: 'x' }, { before: 0, after: 2, ratio: null, sampleMessage: 'y' }], gone: [] })), /from zero/);
+  assert.match(strip(formatTrace({ events: [{ deltaMs: 12, lane: 'v20', level: 'ERROR', message: 'bad' }], platformsSeen: ['v20'], durationMs: 12, errorCount: 1 })), /\+ {4}12ms v20 +ERROR bad/);
+  assert.match(strip(formatAnomalies({ buckets: [{ hourUtc: '2026-10-12T20:00:00Z', count: 9, z: 7, isAnomaly: true, lowConfidence: true }], anomalies: [{}] })), /ANOMALY z=7.0.*low confidence/);
+  assert.equal(formatAnomalies({ buckets: [] }), 'No hourly data.');
+  assert.match(strip(formatSites({ sites: [{ siteId: 9, total: 10, errors: 5, errorRate: 0.5, trendPct: 20, topGroups: [{ count: 2, sampleMessage: 'm' }] }], unattributed: 4 })), /50\.0%.*up 20%[\s\S]*4 events had no site id/);
+  assert.equal(formatSites({ sites: [] }), 'No site-attributed events.');
+  assert.match(strip(formatMutes({ mutes: [{ fingerprint: 'f', reason: 'r', expiresAt: null }] })), /never expires/);
+  assert.equal(formatMutes({ mutes: [] }), 'No active mutes.');
+  assert.match(strip(formatSensitive({ findings: [{ type: 'email', count: 2, sampleRedacted: '[REDACTED:email]', logger: 'L' }], truncated: true })), /email[\s\S]*Results capped/);
+});
+
+test('command tree exposes every insights subcommand', () => {
+  const seen = [];
+  const fake = { command(c) { seen.push(c.command.split(' ')[0]); return fake; }, demandCommand() { return fake; } };
+  logsInsightsCommand.builder(fake);
+  assert.deepEqual(seen, ['groups', 'new', 'regression', 'trace', 'anomalies', 'sites', 'mutes', 'mute', 'unmute', 'sensitive', 'brief']);
+});
+
+test('scoped drops the filters an endpoint does not accept', () => {
+  const argv = { level: 'warn', platform: 'v10', environment: 'Staging', site: 9 };
+  assert.deepEqual(scoped(argv), { level: 'WARN', platform: 'v10', environment: 'Staging', siteId: 9 });
+  assert.equal(scoped(argv, { site: false }).siteId, undefined);
+  const r = scoped(argv, { site: false, level: false });
+  assert.equal('siteId' in r, false);
+  assert.equal('level' in r, false);
+  assert.equal(r.environment, 'Staging');
+});
+
+test('anomalyLevel allows only ERROR or WARN', () => {
+  assert.equal(anomalyLevel(undefined), 'ERROR');
+  assert.equal(anomalyLevel('warn'), 'WARN');
+  assert.throws(() => anomalyLevel('info'), /ERROR or WARN/);
+});
+
+test('timeouts and window cap constants', () => {
+  assert.equal(CALL_TIMEOUT_MS, 90_000);
+  assert.equal(BRIEF_TIMEOUT_MS, 120_000);
+  assert.equal(MAX_WINDOW_MS, 24 * 3_600_000);
+});
+
+test('help text no longer advertises a 7d window for from/to commands', () => {
+  const opts = {};
+  const y = { option(k, o) { opts[k] = o; return y; }, positional() { return y; }, command() { return y; }, demandCommand() { return y; } };
+  const tree = [];
+  logsInsightsCommand.builder({ command(c) { tree.push(c); return this; }, demandCommand() { return this; } });
+  const groups = tree.find(c => c.command === 'groups');
+  groups.builder(y);
+  assert.doesNotMatch(opts.last.describe, /7d/);
+  assert.match(opts.last.describe, /24h/);
+});

package/lib/mcp-key.test.js

@@ -1,6 +1,17 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { normalizeMcpKeysResponse } from './commands/mcp-key.js';
+import { describeExchangeFailure } from './oauth.js';
+
+test('CLI login surfaces the plan-gate message instead of a raw 403 body', () => {
+  const body = JSON.stringify({ error: 'cli_not_entitled', message: 'Professional plan and above.' });
+  assert.equal(describeExchangeFailure(403, body), 'Professional plan and above.');
+});
+
+test('CLI login keeps the generic message for other failures', () => {
+  assert.match(describeExchangeFailure(500, 'boom'), /token exchange failed \(500\): boom/);
+  assert.match(describeExchangeFailure(403, 'not json'), /token exchange failed \(403\)/);
+});
 
 test('MCP key list reads the current API response shape', () => {
   const keys = [{ id: 1, label: 'Staff', keyPrefix: 'vel_live_example' }];

package/lib/messaging-routes.test.js

@@ -9,7 +9,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const dir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'commands');
-const MESSAGING_ONLY = ['/Teams/List', '/Deployment', '/Users/List', '/Workflows/List', '/Rules', '/Ticket/knowledge-overrides', '/UserStatus/admin', '/api/ivr/config', '/WooCommerce/billing', '/WooCommerce/auth', '/diagnostics/test-magento', '/voice/admin', '/api/enterprise-reports', '/avatar/groups', '/avatar/workflows', '/avatar/group-overrides', '/Recruiting'];
+const MESSAGING_ONLY = ['/Teams/List', '/Deployment', '/Users/List', '/Workflows/List', '/Rules', '/Ticket/knowledge-overrides', '/UserStatus/admin', '/api/ivr/config', '/WooCommerce/billing', '/WooCommerce/auth', '/diagnostics/test-magento', '/voice/admin', '/api/enterprise-reports', '/avatar/groups', '/avatar/workflows', '/avatar/group-overrides', '/Recruiting', '/superadmin/logs/insights', '/ApplePayConfig'];
 
 test('messaging-only routes are never called through the admin api helpers', () => {
   const offenders = [];
@@ -26,3 +26,12 @@ test('messaging-only routes are never called through the admin api helpers', ()
   }
   assert.deepEqual(offenders, [], `messaging-only routes called via the admin api:\n${offenders.join('\n')}`);
 });
+
+// The logger-insights routes (superadmin/logs/insights/*, meta/insights) exist only on the messaging
+// api. logs-insights.js must reach them through messagingRequest and never the admin helpers.
+test('logs-insights.js uses the messaging helper only', () => {
+  const src = fs.readFileSync(path.join(dir, 'logs-insights.js'), 'utf8');
+  assert.match(src, /messagingRequest/);
+  assert.doesNotMatch(src, /import\s*\{[^}]*\b(get|post|del)\b[^}]*\}\s*from '\.\.\/api\.js'/);
+  assert.match(src, /superadmin\/logs\/insights/);
+});

package/lib/oauth.js

@@ -100,16 +100,28 @@ export async function pollForToken(deviceCode, intervalSeconds) {
   }
 }
 
+/** Turns a failed token-exchange response into a user-facing message (plan gate gets its own wording). */
+export function describeExchangeFailure(status, body) {
+  if (status === 403) {
+    try {
+      const j = JSON.parse(body);
+      if (j?.error === 'cli_not_entitled') return j.message || 'The Velaro CLI is included with the Professional plan and above.';
+    } catch { /* not JSON -- fall through to the generic message */ }
+  }
+  return `Velaro token exchange failed (${status}): ${body}`;
+}
+
 export async function exchangeForVelaroToken(entraAccessToken, apiBase) {
   const res = await fetch(`${apiBase}/auth/entra/token`, {
     method:  'POST',
-    headers: { Authorization: `Bearer ${entraAccessToken}` },
+    // X-Velaro-Client lets the server enforce the plan gate: the CLI is Professional+ only.
+    headers: { Authorization: `Bearer ${entraAccessToken}`, 'X-Velaro-Client': 'cli' },
     signal:  AbortSignal.timeout(FETCH_TIMEOUT),
   });
 
   if (!res.ok) {
     const body = await res.text().catch(() => res.status.toString());
-    throw new Error(`Velaro token exchange failed (${res.status}): ${body}`);
+    throw new Error(describeExchangeFailure(res.status, body));
   }
 
   return res.json(); // { token: { token, expires }, profile: { siteId, userName, ... } } -- camelCase, matches ASP.NET Core's default JSON casing

package/lib/report-range.js

@@ -0,0 +1,21 @@
+// The server treats every report End as EXCLUSIVE (velaro-messaging PR #1457): rows with
+// timestamp < End. A date-only end (YYYY-MM-DD) means "through the end of that day" to a human,
+// so send the start of the NEXT day; otherwise the whole last day is silently dropped. A full ISO
+// datetime is an exact instant and is sent unchanged. `parsed` is the already-validated Date.
+const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function toExclusiveEnd(raw, parsed) {
+  return DATE_ONLY_RE.test(String(raw).trim())
+    ? new Date(parsed.getTime() + 24 * 60 * 60 * 1000)
+    : parsed;
+}
+
+// Value to send for a report `end` query/body param. A plain YYYY-MM-DD becomes the start of the
+// next day (UTC ISO instant) so the whole last day is included; anything else (full datetime,
+// missing, unparseable) is returned unchanged so the server keeps its own validation.
+export function exclusiveEndParam(raw) {
+  if (raw == null || raw === '') return raw;
+  const parsed = new Date(raw);
+  if (Number.isNaN(parsed.getTime())) return raw;
+  return DATE_ONLY_RE.test(String(raw).trim()) ? toExclusiveEnd(raw, parsed).toISOString() : raw;
+}

package/lib/report-range.test.js

@@ -0,0 +1,38 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { toExclusiveEnd, exclusiveEndParam } from './report-range.js';
+
+test('exclusiveEndParam: date-only -> next-day ISO instant', () => {
+  assert.equal(exclusiveEndParam('2026-09-25'), '2026-09-26T00:00:00.000Z');
+});
+test('exclusiveEndParam: datetime, empty and invalid pass through unchanged', () => {
+  assert.equal(exclusiveEndParam('2026-09-25T17:30:00Z'), '2026-09-25T17:30:00Z');
+  assert.equal(exclusiveEndParam(undefined), undefined);
+  assert.equal(exclusiveEndParam('garbage'), 'garbage');
+});
+
+test('date-only end includes the whole last day (start of next day, exclusive)', () => {
+  const end = toExclusiveEnd('2026-09-25', new Date('2026-09-25'));
+  assert.equal(end.toISOString(), '2026-09-26T00:00:00.000Z');
+});
+
+// Call-site wiring guard: CLI report commands must route end through the helper, and
+// servicelevel/conversations must use the startDate/endDate names + route the server binds
+// (they were silently ignored before).
+import { readFileSync } from 'node:fs';
+const reportSrc = readFileSync(new URL('./commands/report.js', import.meta.url), 'utf8');
+
+test('report.js never sends a raw argv.end for callcenter/servicelevel/conversations', () => {
+  assert.equal(reportSrc.match(/`end(Date)?=\$\{encodeURIComponent\(argv\.end\)\}`/g), null);
+  assert.ok((reportSrc.match(/exclusiveEndParam\(argv\.end\)/g) || []).length >= 4);
+});
+
+test('servicelevel and conversations use the server-bound startDate/endDate and route', () => {
+  assert.match(reportSrc, /`endDate=\$\{encodeURIComponent\(exclusiveEndParam\(argv\.end\)\)\}`/);
+  assert.match(reportSrc, /fetchReport\(`\/ConversationsReport\$\{qs\}`\)/);
+});
+
+test('full ISO datetime end is passed through unchanged', () => {
+  const parsed = new Date('2026-09-25T17:30:00Z');
+  assert.equal(toExclusiveEnd('2026-09-25T17:30:00Z', parsed).toISOString(), '2026-09-25T17:30:00.000Z');
+});

package/lib/shopify-write-policy.test.js

@@ -0,0 +1,34 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildWritePolicyBody, parseCap } from './commands/shopify.js';
+
+const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+test('parseCap handles numbers, default and invalid', () => {
+  assert.equal(parseCap(undefined, 'x'), undefined);
+  assert.equal(parseCap('default', 'x'), null);
+  assert.equal(parseCap('12.5', 'x'), 12.5);
+  assert.throws(() => parseCap('abc', 'x'));
+  assert.throws(() => parseCap('-1', 'x'));
+});
+
+test('buildWritePolicyBody is partial and maps default to null', () => {
+  assert.deepEqual(buildWritePolicyBody({ enableShopifyWrite: false }), { enableShopifyWrite: false });
+  assert.deepEqual(buildWritePolicyBody({ maxRefundAmount: '100', maxDiscountPercent: 'default' }), { maxRefundAmount: 100, maxDiscountPercent: null });
+  assert.throws(() => buildWritePolicyBody({}));
+});
+
+test('CLI and MCP expose the write-policy surface and it is registered', () => {
+  const cli = fs.readFileSync(path.join(root, 'cli/bin/velaro.js'), 'utf8');
+  assert.match(cli, /\.command\(shopifyCommand\)/);
+  const mcp = fs.readFileSync(path.join(root, 'mcp/server.js'), 'utf8');
+  for (const t of ['shopify_get_write_policy', 'shopify_set_write_policy']) {
+    assert.match(mcp, new RegExp(`name: '${t}'`));
+    assert.match(mcp, new RegExp(`case '${t}'`));
+  }
+  assert.match(mcp, /messagingPut\('\/Shopify\/WritePolicy'/);
+  assert.match(mcp, /messagingGet\('\/Shopify\/WritePolicy'/);
+});

package/lib/signature-policy.js

@@ -0,0 +1,70 @@
+// Pure helpers for `velaro signature policy` (and mirrored in mcp/server.js signature_policy_set).
+// The messaging endpoint PUT Signatures/policy REPLACES the row for a team, and silently turns an unknown mode
+// into "follow the company-wide value", so we validate here and merge onto the current row before sending.
+
+const MODES = {
+  'locked': 'admin_locked',
+  'admin-locked': 'admin_locked',
+  'admin_locked': 'admin_locked',
+  'company-default': 'company_default',
+  'company_default': 'company_default',
+  'personal-only': 'personal_only',
+  'personal_only': 'personal_only',
+};
+
+// Returns undefined when not supplied, null for "follow the company-wide setting", else the API value.
+export function parseMode(value) {
+  if (value === undefined) return undefined;
+  const v = String(value).trim().toLowerCase();
+  if (v === 'default' || v === 'inherit' || v === '') return null;
+  const mode = MODES[v];
+  if (!mode) throw new Error('mode must be locked, company-default, personal-only or default');
+  return mode;
+}
+
+export function parseTeamId(value) {
+  if (value === undefined || value === null || value === '') return 0;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) throw new Error('teamId must be 0 (company-wide) or a team id');
+  return n;
+}
+
+// current: the matching row from GET Signatures/policy (or undefined). opts: only the fields being changed.
+// A field left out keeps its current value; null clears it back to "follow the company-wide setting".
+export function buildPolicyBody(current, opts = {}) {
+  const cur = current ?? {};
+  const body = {
+    teamId: parseTeamId(opts.teamId ?? cur.teamId),
+    mode: cur.mode ?? null,
+    corporateSignature: cur.corporateSignature || null,
+    disclaimerEnabled: cur.disclaimerEnabled ?? null,
+    disclaimerText: cur.disclaimerText || null,
+  };
+  const mode = parseMode(opts.mode);
+  if (mode !== undefined) body.mode = mode;
+  if (opts.corporateSignature !== undefined) body.corporateSignature = opts.corporateSignature || null;
+  if (opts.disclaimerEnabled !== undefined) {
+    if (opts.disclaimerEnabled !== null && typeof opts.disclaimerEnabled !== 'boolean') {
+      throw new Error('disclaimerEnabled must be true, false or null');
+    }
+    body.disclaimerEnabled = opts.disclaimerEnabled;
+  }
+  if (opts.disclaimerText !== undefined) body.disclaimerText = opts.disclaimerText || null;
+  if (body.corporateSignature && body.corporateSignature.length > 4000) throw new Error('corporateSignature is limited to 4000 characters');
+  if (body.disclaimerText && body.disclaimerText.length > 2000) throw new Error('disclaimerText is limited to 2000 characters');
+  return body;
+}
+
+export function findPolicy(policies, teamId) {
+  const id = parseTeamId(teamId);
+  return (Array.isArray(policies) ? policies : []).find((p) => p.teamId === id);
+}
+
+export function describeMode(mode) {
+  switch (mode) {
+    case 'admin_locked': return 'locked (company signature only)';
+    case 'company_default': return 'company default (personal signatures allowed)';
+    case 'personal_only': return 'personal only';
+    default: return 'follows company-wide setting (personal only if none set)';
+  }
+}