@velaro/cli 1.2.0 → 1.4.8

package/lib/api.js

@@ -1,52 +1,91 @@
-import { readConfig, writeConfig, getActiveEnv, setEnvCredentials, ENVS } from './config.js';
-import { refreshVelaroToken } from './oauth.js';
-
-const REFRESH_BUFFER_MS = 5 * 60 * 1000;
-
-export async function getCredentials(envOverride) {
-  const cfg = readConfig();
-  const env = envOverride || cfg.activeEnv || 'prod';
-  let creds = cfg.envs?.[env];
-
-  if (!creds?.velaroToken) {
-    throw new Error(`Not logged in to ${env}. Run: velaro login${env === 'staging' ? ' --staging' : ''}`);
-  }
-
-  if (Date.now() + REFRESH_BUFFER_MS >= new Date(creds.velaroExpires).getTime()) {
-    if (!creds.entraRefreshToken) {
-      throw new Error(`Session expired for ${env}. Run: velaro login${env === 'staging' ? ' --staging' : ''}`);
-    }
-    const refreshed = await refreshVelaroToken({ ...creds, apiBase: creds.adminApiBase });
-    const updated = { ...creds, ...refreshed };
-    setEnvCredentials(env, updated);
-    creds = updated;
-  }
-
-  return { ...creds, env };
-}
-
-export async function request(method, path, body, envOverride) {
-  const creds = await getCredentials(envOverride);
-
-  const res = await fetch(`${creds.adminApiBase}${path}`, {
-    method,
-    headers: {
-      Authorization:  `Bearer ${creds.velaroToken}`,
-      'Content-Type': 'application/json',
-    },
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
-
-  if (!res.ok) {
-    let msg = `${method} ${path} → ${res.status}`;
-    try { const t = await res.text(); if (t) msg += `: ${t}`; } catch { /* status already captured */ }
-    throw new Error(msg);
-  }
-
-  const text = await res.text();
-  return text ? JSON.parse(text) : null;
-}
-
-export const get  = (path)       => request('GET',    path);
-export const post = (path, body) => request('POST',   path, body);
-export const del  = (path)       => request('DELETE', path);
+import { readConfig, writeConfig, getActiveEnv, setEnvCredentials, ENVS } from './config.js';
+import { refreshVelaroToken } from './oauth.js';
+
+const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+
+export async function getCredentials(envOverride) {
+  const cfg = readConfig();
+  const env = envOverride || cfg.activeEnv || 'prod';
+  let creds = cfg.envs?.[env];
+
+  if (!creds?.velaroToken) {
+    throw new Error(`Not logged in to ${env}. Run: velaro login${env === 'staging' ? ' --staging' : ''}`);
+  }
+
+  if (Date.now() + REFRESH_BUFFER_MS >= new Date(creds.velaroExpires).getTime()) {
+    if (!creds.entraRefreshToken) {
+      throw new Error(`Session expired for ${env}. Run: velaro login${env === 'staging' ? ' --staging' : ''}`);
+    }
+    const refreshed = await refreshVelaroToken({ ...creds, apiBase: creds.adminApiBase });
+    const updated = { ...creds, ...refreshed };
+    setEnvCredentials(env, updated);
+    creds = updated;
+  }
+
+  return { ...creds, env };
+}
+
+function joinUrl(base, path) {
+  return `${base.replace(/\/+$/, '')}/${String(path).replace(/^\/+/, '')}`;
+}
+
+// Exported under a distinct name for unit testing only — request()/messagingRequest()
+// remain the real call sites, this is not part of the public CLI API surface.
+export const joinUrlForTest = joinUrl;
+
+export async function request(method, path, body, envOverride) {
+  const creds = await getCredentials(envOverride);
+
+  const res = await fetch(joinUrl(creds.adminApiBase, path), {
+    method,
+    headers: {
+      Authorization:  `Bearer ${creds.velaroToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  if (!res.ok) {
+    let msg = `${method} ${path} → ${res.status}`;
+    try { const t = await res.text(); if (t) msg += `: ${t}`; } catch { /* status already captured */ }
+    throw new Error(msg);
+  }
+
+  const text = await res.text();
+  return text ? JSON.parse(text) : null;
+}
+
+export const get  = (path)       => request('GET',    path);
+export const post = (path, body) => request('POST',   path, body);
+export const put  = (path, body) => request('PUT',    path, body);
+export const del  = (path)       => request('DELETE', path);
+
+export async function messagingRequest(method, path, body, envOverride) {
+  const creds = await getCredentials(envOverride);
+  const res = await fetch(joinUrl(creds.messagingApiBase, path), {
+    method,
+    headers: {
+      Authorization:  `Bearer ${creds.velaroToken}`,
+      'Content-Type': 'application/json',
+      // ClientControllerBase.SiteId reads this header but only honors it when it matches the
+      // JWT's own siteId claim, otherwise falling back to the token -- it's a hint, not a
+      // trust boundary override. Still required: every messaging* CLI command was silently
+      // 401ing with "missing_site_id" until this was added.
+      ...(creds.siteId ? { 'vmsg-siteId': String(creds.siteId) } : {}),
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    let msg = `${method} ${path} → ${res.status}`;
+    try { const t = await res.text(); if (t) msg += `: ${t}`; } catch { /* status already captured */ }
+    throw new Error(msg);
+  }
+  const text = await res.text();
+  return text ? JSON.parse(text) : null;
+}
+
+export const messagingGet   = (path)       => messagingRequest('GET',  path);
+export const messagingPost  = (path, body) => messagingRequest('POST', path, body);
+export const messagingPut   = (path, body) => messagingRequest('PUT',  path, body);
+export const messagingPatch = (path, body) => messagingRequest('PATCH', path, body);
+export const messagingDel   = (path)       => messagingRequest('DELETE', path);

package/lib/api.test.js

@@ -0,0 +1,46 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { joinUrlForTest as joinUrl } from './api.js';
+
+// Regression test for the bug where request()/messagingRequest() concatenated
+// adminApiBase/messagingApiBase directly with `path` (no separator). Config
+// stores the base with no trailing slash and every command file omits the
+// leading slash on its path (e.g. `Entitlements/${site}`), so the raw
+// concatenation produced `https://api-admin-us-east.velaro.comEntitlements/1032`
+// -- a malformed hostname that fails DNS resolution before the request is
+// ever sent. This broke every `velaro entitlement *` and `velaro
+// feature-discovery *` command in prod.
+
+test('joinUrl inserts exactly one slash when base has none and path has none', () => {
+  assert.equal(
+    joinUrl('https://api-admin-us-east.velaro.com', 'Entitlements/1032/override'),
+    'https://api-admin-us-east.velaro.com/Entitlements/1032/override'
+  );
+});
+
+test('joinUrl does not double the slash when base already has a trailing slash', () => {
+  assert.equal(
+    joinUrl('https://api-admin-us-east.velaro.com/', 'Entitlements/1032/override'),
+    'https://api-admin-us-east.velaro.com/Entitlements/1032/override'
+  );
+});
+
+test('joinUrl does not double the slash when path already has a leading slash', () => {
+  assert.equal(
+    joinUrl('https://api-admin-us-east.velaro.com', '/Entitlements/1032/override'),
+    'https://api-admin-us-east.velaro.com/Entitlements/1032/override'
+  );
+});
+
+test('joinUrl handles both a trailing and leading slash without doubling', () => {
+  assert.equal(
+    joinUrl('https://api-admin-us-east.velaro.com/', '/Entitlements/1032/override'),
+    'https://api-admin-us-east.velaro.com/Entitlements/1032/override'
+  );
+});
+
+test('joinUrl result is always a parseable, correctly-hosted URL', () => {
+  const url = new URL(joinUrl('https://api-admin-us-east.velaro.com', 'Entitlements/features'));
+  assert.equal(url.hostname, 'api-admin-us-east.velaro.com');
+  assert.equal(url.pathname, '/Entitlements/features');
+});

package/lib/banner.js

@@ -0,0 +1,76 @@
+import { readConfig, writeConfig } from './config.js';
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const CONFIG_FILE = join(homedir(), '.velaro', 'config.json');
+
+// True only when there's nothing on disk yet, OR what's on disk parses cleanly.
+// False when a config file exists but is corrupt/unreadable right now (e.g. a
+// concurrent `velaro` process mid-write) — in that case we must NOT let the
+// banner's writeConfig() clobber it with an empty {envs:{}}, which would wipe
+// the user's saved token/siteId.
+function configFileIsSafeToOverwrite() {
+  if (!existsSync(CONFIG_FILE)) return true;
+  try {
+    JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Pure ASCII (0-127) block-letter wordmark. Do not add box-drawing/unicode chars.
+const ART = [
+  " __      __  ______  __       ______   ______   ______  ",
+  "/\\ \\    /\\ \\/\\  ___\\/\\ \\     /\\  __ \\ /\\  == \\ /\\  __ \\ ",
+  "\\ \\ \\___\\ \\ \\ \\  __\\\\ \\ \\____\\ \\  __ \\\\ \\  __< \\ \\ \\/\\ \\",
+  " \\ \\_____\\ \\_\\ \\_____\\ \\_____\\\\ \\_\\ \\_\\\\ \\_\\ \\_\\\\ \\_____\\",
+  "  \\/_____/\\/_/\\/_____/\\/_____/ \\/_/\\/_/ \\/_/ /_/ \\/_____/",
+];
+
+const TAGLINE = 'AI-native customer engagement -- command line';
+
+function colorize(line) {
+  // Velaro brand blue/cyan (ANSI 256 color 39), reset after.
+  return `\x1b[38;5;39m${line}\x1b[0m`;
+}
+
+export function printBanner() {
+  // Non-TTY (piped/redirected output, e.g. `velaro ... | jq`) must stay
+  // completely silent on stdout — machine-readable command output (several
+  // commands emit JSON via console.log) must never be prefixed with banner
+  // text. Only decorate a real interactive terminal.
+  if (!process.stdout.isTTY) return;
+
+  console.log('');
+  for (const line of ART) {
+    console.log(colorize(line));
+  }
+  console.log(colorize(`  ${TAGLINE}`));
+  console.log('');
+}
+
+export function printBannerIfFirstRun() {
+  const cfg = readConfig();
+
+  if (cfg && cfg._bannerShown === true) {
+    return;
+  }
+
+  printBanner();
+
+  // Only persist the "shown" flag if the config file on disk is intact —
+  // readConfig() silently falls back to an empty {envs:{}} on ANY read/parse
+  // failure (corrupt file, concurrent writer), and blindly spreading that
+  // fallback back out via writeConfig() would permanently erase the user's
+  // saved token/siteId. If the file isn't safely readable right now, just
+  // let the banner show again next run instead of risking a destructive write.
+  if (configFileIsSafeToOverwrite()) {
+    try {
+      writeConfig({ ...cfg, _bannerShown: true });
+    } catch {
+      // Non-fatal — worst case the banner shows again next run.
+    }
+  }
+}

package/lib/commands/activity.js

@@ -0,0 +1,133 @@
+import { get, getCredentials } from '../api.js';
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+const RESET = '\x1b[0m';
+const DIM   = '\x1b[2m';
+const RED   = '\x1b[31m';
+const YEL   = '\x1b[33m';
+const CYN   = '\x1b[36m';
+
+function formatEntry(item) {
+  const ts    = new Date(item.createdAt).toISOString().replace('T', ' ').slice(0, 19);
+  const sev   = (item.severity ?? 'Info').padEnd(8);
+  const color = item.severity === 'Error' ? RED : item.severity === 'Warning' ? YEL : RESET;
+  const cat   = `${DIM}[${item.category ?? '?'}]${RESET}`;
+  const int   = item.integration ? `${CYN}${item.integration}${RESET}  ` : '';
+  const lines = [`${DIM}${ts}${RESET}  ${color}${sev}${RESET}  ${int}${cat}  ${item.message ?? ''}`];
+  if (item.additionalInfo) lines.push(`         ${DIM}${item.additionalInfo}${RESET}`);
+  if (item.suppressedCount > 0) lines.push(`         ${DIM}(+${item.suppressedCount} suppressed)${RESET}`);
+  return lines.join('\n');
+}
+
+function formatAuditEntry(e) {
+  const ts    = new Date(e.createdAt).toISOString().replace('T', ' ').slice(0, 19);
+  const actor = e.actorType === 'AI_Moshky'
+    ? `${CYN}Moshky${RESET} (on behalf of ${e.initiatedByEmail ?? 'unknown'})`
+    : `${e.actorType === 'HumanStaff' ? YEL : RESET}${e.actorType}${RESET} ${e.actorEmail ?? ''}`.trim();
+  const lines = [`${DIM}${ts}${RESET}  [${e.entityType}#${e.entityId}]  ${e.action}  ${DIM}by${RESET} ${actor}`];
+  if (e.oldValueJson) lines.push(`         ${DIM}before:${RESET} ${e.oldValueJson}`);
+  if (e.newValueJson) lines.push(`         ${DIM}after: ${RESET} ${e.newValueJson}`);
+  return lines.join('\n');
+}
+
+// ── audit-trail handler (distinct shape/endpoint from integration activity logs) ───
+
+async function auditTrailHandler(argv) {
+  await getCredentials();
+
+  const params = new URLSearchParams();
+  if (argv.entityType) params.set('entityType', argv.entityType);
+  if (argv.entityId)   params.set('entityId', argv.entityId);
+  params.set('take', String(Math.min(500, argv.take ?? 200)));
+
+  const qs   = params.toString();
+  const data = await get(`/AuditTrail${qs ? '?' + qs : ''}`);
+
+  if (!data?.entries?.length) {
+    console.log('\nNo audit trail entries.');
+    return;
+  }
+
+  console.log(`\n${data.entries.length} audit trail entries`);
+  if (!data.fullDetailAvailable) {
+    console.log(`${DIM}${data.complianceUpsellMessage ?? 'Upgrade to a Compliance package for full before/after detail.'}${RESET}`);
+  }
+  console.log('');
+
+  for (const e of data.entries) console.log(formatAuditEntry(e));
+  console.log('');
+}
+
+// ── integration activity handler ────────────────────────────────────────────────
+
+async function activityHandler(argv) {
+  await getCredentials(); // ensure logged in
+
+  if (argv.slug === 'audit-trail') return auditTrailHandler(argv);
+
+  // 'skills' is a convenience alias for AI tool logs
+  const isSkills = argv.slug === 'skills';
+  let path;
+  if (isSkills) {
+    path = '/Integration/Logs';
+    argv.category = 'AiTool';
+  } else if (argv.slug) {
+    path = `/Integration/Logs/${encodeURIComponent(argv.slug)}`;
+  } else {
+    path = '/Integration/Logs';
+  }
+
+  const params = new URLSearchParams();
+  if (argv.severity && argv.severity !== 'All') params.set('severity', argv.severity);
+  if (argv.category && argv.category !== 'All') params.set('category', argv.category);
+  if (argv.search)   params.set('search',   argv.search);
+  params.set('page',     String(Math.max(1, argv.page ?? 1)));
+  params.set('pageSize', String(Math.min(100, argv.pageSize ?? 25)));
+
+  const qs   = params.toString();
+  const data = await get(`${path}${qs ? '?' + qs : ''}`);
+
+  if (!data?.items?.length) {
+    console.log('\nNo activity log entries.');
+    return;
+  }
+
+  const label = isSkills ? 'AI skill calls' : argv.slug ? `${argv.slug} activity` : 'integration activity';
+  console.log(`\n${data.items.length} of ${data.total} ${label} entries\n`);
+
+  for (const item of data.items) console.log(formatEntry(item));
+
+  if (data.total > data.page * data.pageSize) {
+    console.log(`\n${DIM}More results — use --page ${data.page + 1}${RESET}`);
+  }
+
+  console.log('');
+}
+
+// ── command export ────────────────────────────────────────────────────────────
+
+export const activityCommand = {
+  command:  'activity [slug]',
+  describe: 'View integration activity logs, or "audit-trail" for who-changed-what settings history',
+  builder: y => y
+    .positional('slug', {
+      describe: 'Integration name (HubSpot, Square…), "skills" for AI tool logs, or "audit-trail" for settings change history',
+      type: 'string',
+    })
+    .option('severity', {
+      describe: 'Info, Warning, Error',
+      type: 'string',
+    })
+    .option('category', {
+      describe: 'Auth, Config, Request, Response, AiTool, Setup, Error',
+      type: 'string',
+    })
+    .option('search',   { describe: 'Message search',               type: 'string' })
+    .option('page',     { describe: 'Page number',    default: 1,   type: 'number' })
+    .option('pageSize', { describe: 'Results per page', default: 25, type: 'number' })
+    .option('entityType', { describe: '[audit-trail] Filter to one entity type, e.g. Workflow', type: 'string' })
+    .option('entityId',   { describe: '[audit-trail] Filter to one specific entity', type: 'string' })
+    .option('take',       { describe: '[audit-trail] Max results (default 200, max 500)', type: 'number' }),
+  handler: activityHandler,
+};

package/lib/commands/acuity.js

@@ -0,0 +1,66 @@
+import { request } from '../api.js';
+import { runCommand } from '../run.js';
+
+// ── velaro acuity ─────────────────────────────────────────────────────────────
+// Superadmin commands to configure Acuity Scheduling for any customer site.
+// Requires a Velaro admin JWT (site 1032).
+
+export const acuityCommand = {
+  command:  'acuity <subcommand>',
+  describe: 'Manage Acuity Scheduling integration for any site (Velaro admin only)',
+  builder:  yargs => yargs
+    .command({
+      command:  'status',
+      describe: 'Show Acuity 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', `/Acuity/superadmin/status?siteId=${argv.site}`);
+        if (!data.configured) {
+          console.log(`\nSite ${argv.site}: Acuity NOT configured.\n`);
+          return;
+        }
+        console.log(`\nSite ${argv.site}: Acuity configured ✓`);
+        console.log(`  Account:      ${data.accountName}`);
+        console.log(`  Display name: ${data.displayName || '(none)'}`);
+        console.log(`  Default type: ${data.defaultAppointmentTypeName || '(none)'}`);
+        console.log(`  Timezone:     ${data.timezone || '(none)'}\n`);
+      }),
+    })
+    .command({
+      command:  'configure',
+      describe: 'Set up or update Acuity for a site',
+      builder:  y => y
+        .option('site',        { type: 'number',  demandOption: true,                    describe: 'Site ID' })
+        .option('user-id',     { type: 'string',  demandOption: true,                    describe: 'Acuity user ID' })
+        .option('api-key',     { type: 'string',  demandOption: true,                    describe: 'Acuity API key' })
+        .option('label',       { type: 'string',  demandOption: false,                   describe: 'Display name' })
+        .option('type-id',     { type: 'number',  demandOption: false,                   describe: 'Default appointment type ID' })
+        .option('type-name',   { type: 'string',  demandOption: false,                   describe: 'Default appointment type name' })
+        .option('calendar-id', { type: 'number',  demandOption: false,                   describe: 'Default calendar ID' })
+        .option('timezone',    { type: 'string',  default: 'America/New_York',           describe: 'IANA timezone' }),
+      handler:  runCommand(async argv => {
+        const data = await request('POST', `/Acuity/superadmin/config?siteId=${argv.site}`, {
+          userId:                       argv['user-id'],
+          apiKey:                       argv['api-key'],
+          displayName:                  argv.label || '',
+          defaultAppointmentTypeId:     argv['type-id']     || null,
+          defaultAppointmentTypeName:   argv['type-name']   || '',
+          defaultCalendarId:            argv['calendar-id'] || null,
+          timezone:                     argv.timezone,
+        });
+        if (!data.success) throw new Error(data.error || 'Configure failed');
+        console.log(`\n✓ Acuity configured for site ${argv.site}`);
+        console.log(`  Account: ${data.accountName}\n`);
+      }),
+    })
+    .command({
+      command:  'disconnect',
+      describe: 'Remove Acuity config from a site',
+      builder:  y => y.option('site', { type: 'number', demandOption: true, describe: 'Site ID' }),
+      handler:  runCommand(async argv => {
+        await request('DELETE', `/Acuity/superadmin/config?siteId=${argv.site}`);
+        console.log(`\n✓ Acuity disconnected from site ${argv.site}\n`);
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: status | configure | disconnect'),
+};