@velaro/cli 1.4.54 → 1.4.55

package/lib/commands/outbound-activity.js

@@ -0,0 +1,124 @@
+/**
+ * velaro outbound-activity - Unified Outbound Activity (Klaviyo-parity Gap 6)
+ *
+ * The one feed across ALL THREE of this product's independent email-send tracking systems:
+ * transactional (EmailDeliveryStatus, velaro-messaging), sequence/drip (EmailSend), and
+ * broadcast (BroadcastRecipient). Until this existed you had to check three separate screens
+ * to answer "what did we send this customer".
+ *
+ *   velaro outbound-activity list                     Site-wide feed, newest first
+ *   velaro outbound-activity contact <email>          Everything sent to ONE address
+ *
+ * Site scoping is enforced SERVER-side from the authenticated session — there is deliberately
+ * no --site flag here.
+ */
+
+import { request } from '../api.js';
+
+const GRN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YEL = '\x1b[33m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST = '\x1b[0m';
+
+const SOURCE_LABEL = { Transactional: 'Transactional', Campaign: 'Sequence', Broadcast: 'Broadcast' };
+
+function statusColor(status) {
+  const s = String(status || '').toLowerCase();
+  if (s === 'sent') return GRN;
+  if (s === 'failed') return RED;
+  if (s === 'pending') return YEL;
+  return DIM;
+}
+
+function buildQuery(argv) {
+  const qs = new URLSearchParams();
+  qs.set('take', String(argv.take ?? 25));
+  qs.set('skip', String(argv.skip ?? 0));
+  if (argv.source) qs.set('source', argv.source);
+  if (argv.status) qs.set('status', argv.status);
+  if (argv.search) qs.set('search', argv.search);
+  return qs.toString();
+}
+
+function render(data, heading) {
+  const items = data?.items ?? [];
+  const degraded = data?.degradedSources ?? [];
+
+  console.log(`\n${BOLD}${heading}${RST}\n`);
+
+  // A partial feed is never printed as if it were complete.
+  if (degraded.length) {
+    console.log(`${YEL}  ! Incomplete: ${degraded.map(s => SOURCE_LABEL[s] ?? s).join(', ')} sends could not be loaded.${RST}\n`);
+  }
+
+  if (!items.length) {
+    console.log(`  ${DIM}No outbound activity matched.${RST}\n`);
+    return;
+  }
+
+  for (const i of items) {
+    const when = i.sentAt ? new Date(i.sentAt).toISOString() : `${DIM}not sent${RST}`;
+    const src = SOURCE_LABEL[i.source] ?? i.source;
+    console.log(`  ${statusColor(i.status)}${String(i.status).padEnd(13)}${RST} ${String(src).padEnd(14)} ${when}`);
+    console.log(`    to ${i.toEmail ?? '(none)'}  ${DIM}${i.subject ?? ''}${RST}`);
+    const meta = [];
+    if (i.campaignOrBroadcastName) meta.push(`campaign: ${i.campaignOrBroadcastName}`);
+    if (i.tag) meta.push(`tag: ${i.tag}`);
+    if (i.channel && i.channel !== 'email') meta.push(`channel: ${i.channel}`);
+    if (i.source !== 'Transactional') meta.push(`opens: ${i.openCount}, clicks: ${i.clickCount}`);
+    if (i.resendableId != null) meta.push('resendable');
+    if (meta.length) console.log(`    ${DIM}${meta.join('  |  ')}${RST}`);
+    console.log(`    ${DIM}id ${i.id}${RST}`);
+  }
+
+  const approx = data?.totalCountIsApproximate ? 'about ' : '';
+  console.log(`\n  ${DIM}${items.length} shown of ${approx}${data?.totalCount ?? items.length} total.${RST}\n`);
+}
+
+async function listHandler(argv) {
+  const data = await request('GET', `/Marketing/OutboundActivity?${buildQuery(argv)}`);
+  render(data, 'Outbound activity');
+}
+
+async function contactHandler(argv) {
+  const email = String(argv.email || '').trim();
+  // The scoping identifier is required, never optional — an omitted email must never silently
+  // widen this into a site-wide listing.
+  if (!email) {
+    console.error('A contact email address is required. Try: velaro outbound-activity contact bob@example.com');
+    process.exitCode = 1;
+    return;
+  }
+  const data = await request('GET', `/Marketing/Contacts/${encodeURIComponent(email)}/OutboundActivity?${buildQuery(argv)}`);
+  render(data, `Outbound activity for ${email}`);
+}
+
+const sharedOptions = yy => yy
+  .option('take', { describe: 'Page size (1-100)', type: 'number', default: 25 })
+  .option('skip', { describe: 'Rows to skip', type: 'number', default: 0 })
+  .option('source', { describe: 'Transactional | Campaign | Broadcast', type: 'string' })
+  .option('status', { describe: 'Sent | Pending | Failed | Unsubscribed | Skipped', type: 'string' });
+
+export const outboundActivityCommand = {
+  command: 'outbound-activity <subcommand>',
+  describe: 'Unified outbound email activity across transactional, sequence and broadcast sends',
+  builder: y => y
+    .command({
+      command: 'list',
+      describe: 'Site-wide unified outbound feed, newest first',
+      builder: yy => sharedOptions(yy)
+        .option('search', { describe: 'Match recipient or subject', type: 'string' }),
+      handler: listHandler,
+    })
+    .command({
+      command: 'contact <email>',
+      describe: 'Every email sent to ONE address, across all three send systems',
+      builder: yy => sharedOptions(yy)
+        .positional('email', { describe: 'Exact recipient email address', type: 'string' }),
+      handler: contactHandler,
+    })
+    .demandCommand(1, 'Specify a subcommand. Try: velaro outbound-activity --help'),
+  handler: () => {},
+};

package/lib/commands/subscription.js

@@ -1,7 +1,8 @@
 // velaro subscription — apply/diff SubscriptionPackage packages on a site (superadmin only)
 // Wraps SuperAdminController.ApplyPackageToSiteAsync / GetPackageDiffAsync in velaro-messaging,
 // the same reflection-copy service the SuperAdmin browser UI uses -- never hand-toggles flags.
-import { messagingPost, messagingGet } from '../api.js';
+import { messagingPost, messagingGet, messagingPut } from '../api.js';
+import { planChanges, parseFlagList, diffRows, verifyOnlyIntendedChanged } from '../site-flags.js';
 
 async function applyPackage(args) {
   if (!args.site || !args.package) {
@@ -27,6 +28,56 @@ async function packageDiff(args) {
   console.log(JSON.stringify(result, null, 2));
 }
 
+// Flip Enable* entitlement flags on exactly ONE site. Reads, prints the diff, PUTs only the
+// changed flags, re-reads, prints before/after and the rollback snapshot id. The server
+// snapshots before every PUT (SuperAdminController.UpdateSubscriptionAsync).
+async function setFlags(args) {
+  const site = args.site;
+  if (!Number.isInteger(site) || site <= 0) {
+    console.error('set-flags takes exactly one --site <id> per call.');
+    process.exit(1);
+  }
+  const enable = parseFlagList(args.enable);
+  const disable = parseFlagList(args.disable);
+  const before = await messagingGet(`SuperAdmin/subscription/${site}`);
+  const plan = planChanges(before, enable, disable);
+  if (!plan.ok) { plan.errors.forEach(e => console.error(`x ${e}`)); process.exit(1); }
+
+  console.log(`\nSite ${site}: intended changes`);
+  for (const c of plan.changes) console.log(`  ${c.key}: ${c.before} -> ${c.after}${c.before === c.after ? '  (already set, no-op)' : ''}`);
+  const real = plan.changes.filter(c => c.before !== c.after);
+  if (real.length === 0) { console.log('\nNothing to change.'); return; }
+  if (args['dry-run']) { console.log('\nDry run: no changes made.'); return; }
+  if (!args.yes) { console.log('\nAdd --yes to apply (or --dry-run to preview only). No changes made.'); return; }
+
+  const body = {};
+  for (const c of real) body[c.flag] = c.after;
+  const result = await messagingPut(`SuperAdmin/subscription/${site}`, body);
+  if (result && result.success === false) { console.error(`x Server rejected the update: ${result.error}`); process.exit(1); }
+
+  const after = await messagingGet(`SuperAdmin/subscription/${site}`);
+  console.log('\nAfter (re-read from server):');
+  for (const d of diffRows(before, after)) console.log(`  ${d.key}: ${JSON.stringify(d.before)} -> ${JSON.stringify(d.after)}`);
+
+  const history = await messagingGet(`SuperAdmin/subscription/${site}/history`);
+  const snap = Array.isArray(history) ? (history.find(h => /before-update/i.test(h.reason ?? h.Reason ?? '')) ?? history[0]) : null;
+  const snapId = snap ? (snap.id ?? snap.Id) : null;
+  console.log(snapId != null
+    ? `\nRollback snapshot id: ${snapId}  (POST SuperAdmin/subscription/${site}/rollback/${snapId})`
+    : '\nWarning: no snapshot found in history; check SuperAdmin history before relying on rollback.');
+
+  if (args.verify) {
+    const v = verifyOnlyIntendedChanged(before, after, real);
+    if (!v.ok) {
+      console.error('\nx VERIFY FAILED');
+      v.missing.forEach(m => console.error(`  not applied: ${m.key}`));
+      v.unexpected.forEach(u => console.error(`  unexpected change: ${u.key} ${JSON.stringify(u.before)} -> ${JSON.stringify(u.after)}`));
+      process.exit(2);
+    }
+    console.log('\nVerify OK: only the requested flags changed.');
+  }
+}
+
 export function subscriptionCommand(yargs) {
   return yargs
     .command('apply-package', 'Apply a SubscriptionPackage to a site (superadmin only) -- correct reflection-copy path, never hand-toggles flags', y => y
@@ -39,5 +90,13 @@ export function subscriptionCommand(yargs) {
     .command('package-diff', 'Show what would change if the site\'s current package were re-applied (read-only)', y => y
       .option('site', { type: 'number', demandOption: true, desc: 'Target site ID' })
     , a => packageDiff(a))
-    .demandCommand(1, 'Specify a subcommand: apply-package | package-diff');
+    .command('set-flags', 'Flip Enable* entitlement flags on ONE site (superadmin only). Allowlisted flags only: never billing, package or limit fields', y => y
+      .option('site',    { type: 'number', demandOption: true, desc: 'Exactly one target site ID' })
+      .option('enable',  { type: 'string', desc: 'Comma-separated Enable* flags to turn ON, e.g. EnableAgentDashboard,EnableCustomDashboards' })
+      .option('disable', { type: 'string', desc: 'Comma-separated Enable* flags to turn OFF' })
+      .option('dry-run', { type: 'boolean', desc: 'Print the intended diff and stop' })
+      .option('yes',     { type: 'boolean', desc: 'Apply. Without it (or with --dry-run) nothing is written' })
+      .option('verify',  { type: 'boolean', desc: 'After applying, confirm ONLY the requested flags changed (exit 2 otherwise)' })
+    , a => setFlags(a))
+    .demandCommand(1, 'Specify a subcommand: apply-package | package-diff | set-flags');
 }

package/lib/commands/support.js

@@ -91,8 +91,26 @@ async function agentLookup(args) {
   console.log(JSON.stringify(result, null, 2));
 }
 
+async function listDeployments(args) {
+  const result = await request('GET', `SupportTools/sites/${args.site}/deployments`);
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Site ${result.siteId}: ${result.deployments.length} active widget deployment(s)`);
+  for (const d of result.deployments) {
+    console.log(`  ${d.deploymentId || '—'}  ${d.displayName || '(unnamed)'}  team ${d.teamId}  database ID ${d.id}`);
+    console.log(`     surveys: pre-chat ${d.preChatSurveyId ?? '—'}, post-chat ${d.postChatSurveyId ?? '—'}, unavailable ${d.unavailableSurveyId ?? '—'}`);
+  }
+  console.log('Use the embed key as test-frame.html?siteId=<site>&deploymentId=<embed-key>.');
+}
+
 export function supportCommand(yargs) {
   return yargs
+    .command('deployments', 'List a site’s widget embed keys and survey assignments (Velaro staff, read-only)', y => y
+      .option('site', { type: 'number', demandOption: true, desc: 'Target site ID' })
+      .option('json', { type: 'boolean', default: false, desc: 'Print the complete JSON response' })
+    , a => listDeployments(a))
     .command('impersonate', 'Start a 15-minute impersonation session for any site (SuperAdmin only, fully audit-logged to the customer\'s own activity log and a management email)', y => y
       .option('site', { type: 'number', demandOption: true, desc: 'Target site ID to impersonate' })
     , a => impersonate(a))
@@ -124,5 +142,5 @@ export function supportCommand(yargs) {
       .option('channel',         { type: 'string', desc: 'Conversation source, e.g. Web, TwilioSms (default Web)' })
       .option('overrideIndexes', { type: 'string', desc: 'Comma-separated index names to override the config\'s own IndexName for this query' })
     , a => chatQuery(a))
-    .demandCommand(1, 'Specify a subcommand: impersonate | agent-lookup | toggle-flag | scraper-create-job | chat-query | send-email');
+    .demandCommand(1, 'Specify a subcommand: deployments | impersonate | agent-lookup | toggle-flag | scraper-create-job | chat-query | send-email');
 }

package/lib/commands/teams.js

@@ -101,6 +101,54 @@ export const teamsCommand = {
           else { console.error(`Send failed: ${result?.message || 'unknown error'}`); process.exit(1); }
         }
       )
-      .demandCommand(1, 'Specify a subcommand: notify, notify-card, create, list'),
+      .command(
+        'push-settings',
+        'Show or change which alerts the Velaro Bot pushes into Teams (per-alert switches + daily cap). Only flags you pass are changed.',
+        (y) =>
+          y
+            .option('new-chat', { type: 'boolean', describe: 'New chat alerts on/off' })
+            .option('missed', { type: 'boolean', describe: 'Missed chat alerts on/off' })
+            .option('ticket-created', { type: 'boolean', describe: 'Ticket created alerts on/off' })
+            .option('ticket-assigned', { type: 'boolean', describe: 'Ticket assigned alerts on/off' })
+            .option('daily-digest', { type: 'boolean', describe: 'Daily digest on/off' })
+            .option('daily-cap', { type: 'number', describe: 'Max alerts per day for this account' })
+            .option('reset-daily-cap', { type: 'boolean', describe: 'Clear the account cap and use the platform default' }),
+        async (argv) => {
+          const body = {};
+          if (argv.newChat !== undefined) body.pushNewChat = argv.newChat;
+          if (argv.missed !== undefined) body.pushMissed = argv.missed;
+          if (argv.ticketCreated !== undefined) body.pushTicketCreated = argv.ticketCreated;
+          if (argv.ticketAssigned !== undefined) body.pushTicketAssigned = argv.ticketAssigned;
+          if (argv.dailyDigest !== undefined) body.pushDailyDigest = argv.dailyDigest;
+          if (argv.dailyCap !== undefined) body.dailyPushCap = argv.dailyCap;
+          if (argv.resetDailyCap) body.resetDailyPushCap = true;
+          const result = Object.keys(body).length
+            ? await request('PUT', '/TeamsBot/PushSettings', body)
+            : await request('GET', '/TeamsBot/PushSettings');
+          console.log(JSON.stringify(result, null, 2));
+        }
+      )
+      .command(
+        'channel-config',
+        'Show or change Teams Channel (customer chat) settings: enabled, welcome message, team routing. Only flags you pass are changed.',
+        (y) =>
+          y
+            .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' }),
+        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;
+          const result = Object.keys(body).length
+            ? await request('PUT', '/TeamsBot/ChannelConfig', body)
+            : await request('GET', '/TeamsBot/ChannelConfig');
+          console.log(JSON.stringify(result, null, 2));
+        }
+      )
+      .demandCommand(1, 'Specify a subcommand: notify, notify-card, create, list, push-settings, channel-config'),
   handler: () => {},
 };

package/lib/config.js

@@ -41,10 +41,28 @@ function migrate(raw) {
   };
 }
 
+// adminApiBase/messagingApiBase are never a per-session value -- always re-derived from the
+// canonical ENVS table on every read, for every env key present on disk, regardless of what's
+// actually stored there. This is the single point that heals every caller, not just ones that
+// route through setEnvCredentials()/getCredentials() -- several command files (ops, logs,
+// status, diagnostics, ai-models) read `cfg.envs[env]` directly. Without this, a URL that got
+// persisted wrong once (e.g. `staging`'s adminApiBase set to `prod`'s canonical Admin API URL,
+// the real incident that prompted this) would keep silently sending every "staging" call to
+// production forever, since refreshVelaroToken() round-trips whatever it was given straight
+// back out with no chance to correct it.
+function normalizeApiBases(cfg) {
+  for (const env of Object.keys(cfg.envs || {})) {
+    if (!ENVS[env]) continue; // unknown env key, leave untouched
+    cfg.envs[env].adminApiBase = ENVS[env].adminApiBase;
+    cfg.envs[env].messagingApiBase = ENVS[env].messagingApiBase;
+  }
+  return cfg;
+}
+
 export function readConfig() {
   try {
     const raw = JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
-    return migrate(raw);
+    return normalizeApiBases(migrate(raw));
   } catch {
     return { activeEnv: 'prod', envs: {} };
   }
@@ -75,7 +93,11 @@ export function setEnvCredentials(env, creds) {
   if (!ENVS[env]) throw new Error(`Unknown environment "${env}". Use: prod, staging`);
   const cfg = readConfig();
   cfg.envs = cfg.envs || {};
-  cfg.envs[env] = { ...ENVS[env], ...creds };
+  // ENVS[env] spread last and always wins for adminApiBase/messagingApiBase -- belt-and-braces
+  // alongside normalizeApiBases() above, which is what actually heals a config that's already
+  // on disk. There is no longer a legitimate caller that needs to persist a custom
+  // adminApiBase (that's VELARO_ADMIN_API_STAGING/_PROD's job, which ENVS itself reads).
+  cfg.envs[env] = { ...creds, ...ENVS[env] };
   cfg.activeEnv = cfg.activeEnv || env;
   writeConfig(cfg);
 }

package/lib/config.test.js

@@ -0,0 +1,94 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Regression coverage for the bug where a wrong adminApiBase/messagingApiBase persisted under
+// an env key would self-perpetuate forever: refreshVelaroToken() round-trips the entire
+// credentials object it was given (including adminApiBase) straight back out, and the old
+// setEnvCredentials(env, creds) implementation did `{ ...ENVS[env], ...creds }` -- creds'
+// (possibly stale/wrong) infra URLs always won over the canonical ENVS table on every write,
+// so a corrupted value never healed. Real incident: a machine's ~/.velaro/config.json had
+// `staging` pointed at prod's Admin API host, so every "staging" CLI call silently hit
+// production (a real but misleading 404 for a route not yet deployed to prod, not the CLI
+// bug it actually was).
+//
+// HOME is redirected to a scratch dir so this never touches the real ~/.velaro/config.json.
+const scratchHome = mkdtempSync(join(tmpdir(), 'velaro-cli-config-test-'));
+process.env.HOME = scratchHome;
+process.env.USERPROFILE = scratchHome; // os.homedir() on Windows reads this first
+
+const configModule = await import('./config.js');
+const { setEnvCredentials, getEnvCredentials, readConfig, ENVS } = configModule;
+const CONFIG_FILE = join(scratchHome, '.velaro', 'config.json');
+
+test('setEnvCredentials always re-derives adminApiBase/messagingApiBase from ENVS, even if creds carries a wrong value', () => {
+  setEnvCredentials('staging', {
+    velaroToken: 'tok',
+    siteId: 1032,
+    userName: 'alex@velaro.com',
+    // Simulates a corrupted/carried-forward value -- must never survive the write.
+    adminApiBase: ENVS.prod.adminApiBase,
+    messagingApiBase: ENVS.prod.messagingApiBase,
+  });
+
+  const creds = getEnvCredentials('staging');
+  assert.equal(creds.adminApiBase, ENVS.staging.adminApiBase);
+  assert.equal(creds.messagingApiBase, ENVS.staging.messagingApiBase);
+  // Mutable per-session fields still come through untouched.
+  assert.equal(creds.velaroToken, 'tok');
+  assert.equal(creds.siteId, 1032);
+});
+
+test('setEnvCredentials keeps prod and staging URLs distinct from each other', () => {
+  setEnvCredentials('prod', { velaroToken: 'prod-tok' });
+  setEnvCredentials('staging', { velaroToken: 'staging-tok' });
+
+  assert.equal(getEnvCredentials('prod').adminApiBase, ENVS.prod.adminApiBase);
+  assert.equal(getEnvCredentials('staging').adminApiBase, ENVS.staging.adminApiBase);
+  assert.notEqual(getEnvCredentials('prod').adminApiBase, getEnvCredentials('staging').adminApiBase);
+});
+
+test('readConfig heals a config.json that is ALREADY poisoned on disk, not just fresh writes -- the actual real-world scenario', () => {
+  // Every command file that reads `cfg.envs[env]` directly (ops, logs, status, diagnostics,
+  // ai-models -- none of which route through setEnvCredentials) needs this, not just the
+  // getCredentials()/refresh path.
+  mkdirSync(join(scratchHome, '.velaro'), { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify({
+    activeEnv: 'staging',
+    envs: {
+      staging: {
+        adminApiBase: ENVS.prod.adminApiBase, // poisoned: staging pointed at prod
+        messagingApiBase: ENVS.prod.messagingApiBase,
+        velaroToken: 'stale-tok',
+        siteId: 1032,
+      },
+    },
+  }));
+
+  const cfg = readConfig();
+  assert.equal(cfg.envs.staging.adminApiBase, ENVS.staging.adminApiBase);
+  assert.equal(cfg.envs.staging.messagingApiBase, ENVS.staging.messagingApiBase);
+  // Untouched, unrelated fields still read back correctly.
+  assert.equal(cfg.envs.staging.velaroToken, 'stale-tok');
+  assert.equal(getEnvCredentials('staging').adminApiBase, ENVS.staging.adminApiBase);
+});
+
+test('readConfig leaves an unrecognized env key untouched (forward-compat, does not throw)', () => {
+  writeFileSync(CONFIG_FILE, JSON.stringify({
+    activeEnv: 'staging',
+    envs: { futureEnv: { adminApiBase: 'https://something-not-yet-known.example.com', velaroToken: 'x' } },
+  }));
+
+  const cfg = readConfig();
+  assert.equal(cfg.envs.futureEnv.adminApiBase, 'https://something-not-yet-known.example.com');
+});
+
+test('setEnvCredentials rejects an unknown environment name', () => {
+  assert.throws(() => setEnvCredentials('nope', {}), /Unknown environment/);
+});
+
+test.after(() => {
+  rmSync(scratchHome, { recursive: true, force: true });
+});