@velaro/cli 1.2.0 → 1.4.9

package/lib/commands/automation-draft.js

@@ -0,0 +1,134 @@
+import { messagingGet, messagingPost, messagingPut } from '../api.js';
+
+// helpers
+
+const RESET = '\x1b[0m';
+const BOLD  = '\x1b[1m';
+const DIM   = '\x1b[2m';
+const CYN   = '\x1b[36m';
+const YEL   = '\x1b[33m';
+const GRN   = '\x1b[32m';
+const RED   = '\x1b[31m';
+
+function fmtDate(iso) {
+  if (!iso) return '-';
+  return new Date(iso).toLocaleString('en-US', { timeZone: 'America/Los_Angeles', dateStyle: 'short', timeStyle: 'short' });
+}
+
+const STATUS_NAMES = { 0: 'pending', 1: 'approved', 2: 'dismissed', 3: 'autosent' };
+const STATUS_VALUES = { pending: 0, approved: 1, dismissed: 2, autosent: 3 };
+const SOURCE_TYPE_NAMES = { 0: 'WorkflowComposedEmail', 1: 'FocusSuggestedReply', 2: 'CrmFieldUpdate' };
+
+const STATUS_COLORS = {
+  pending:  YEL,
+  approved: GRN,
+  dismissed: DIM,
+  autosent: CYN,
+};
+
+function statusLabel(status) {
+  const name = typeof status === 'number' ? (STATUS_NAMES[status] ?? String(status)) : String(status ?? '-');
+  const color = STATUS_COLORS[name] ?? RESET;
+  return color + name + RESET;
+}
+
+// list
+
+const listCommand = {
+  command:  'list',
+  describe: 'List AI-composed drafts awaiting review (workflow-composed emails, Focus suggested replies, CRM field updates)',
+  builder:  (y) => y
+    .option('status', {
+      type: 'string',
+      choices: ['pending', 'approved', 'dismissed', 'autosent'],
+      default: 'pending',
+      describe: 'Filter by draft status (default: pending)',
+    }),
+  handler: async (argv) => {
+    const statusNum = STATUS_VALUES[argv.status] ?? 0;
+    const data = await messagingGet(`/AutomationDrafts?status=${statusNum}`);
+    const drafts = Array.isArray(data?.drafts) ? data.drafts : [];
+
+    console.log(`\n${BOLD}-- Automation Drafts (${argv.status}) --------------------------------------${RESET}`);
+    if (!drafts.length) {
+      console.log(`  ${DIM}No ${argv.status} drafts.${RESET}\n`);
+      return;
+    }
+
+    for (const d of drafts) {
+      const source = SOURCE_TYPE_NAMES[d.sourceType] ?? d.sourceType;
+      const confidence = d.confidenceScore != null ? `${Math.round(d.confidenceScore * 100)}%` : '-';
+      console.log(
+        `  ${CYN}#${d.id}${RESET}  ${statusLabel(d.status)}  ${DIM}${source}${RESET}  confidence: ${confidence}  ${DIM}${fmtDate(d.createdAt)}${RESET}`
+      );
+      if (d.recipientEmail || d.subject) {
+        console.log(`       To: ${d.recipientEmail ?? '-'}   Subject: ${d.subject ?? '-'}`);
+      }
+      const preview = (d.editedContent ?? d.originalContent ?? '').replace(/\s+/g, ' ').slice(0, 140);
+      console.log(`       ${DIM}${preview}${preview.length === 140 ? '...' : ''}${RESET}`);
+    }
+    console.log();
+  },
+};
+
+// edit
+
+const editCommand = {
+  command:  'edit <id> <content>',
+  describe: 'Edit the content of a pending automation draft before approving it',
+  builder:  (y) => y
+    .positional('id',      { type: 'number', describe: 'Draft ID' })
+    .positional('content', { type: 'string', describe: 'New draft content' }),
+  handler: async (argv) => {
+    await messagingPut(`/AutomationDrafts/${argv.id}/edit`, { EditedContent: argv.content });
+    console.log(`\n  ${GRN}OK${RESET} Draft #${argv.id} updated.\n`);
+  },
+};
+
+// approve
+
+const approveCommand = {
+  command:  'approve <id>',
+  describe: 'Approve a pending automation draft (sends the email now for workflow-composed emails)',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Draft ID' }),
+  handler: async (argv) => {
+    try {
+      await messagingPost(`/AutomationDrafts/${argv.id}/approve`);
+      console.log(`\n  ${GRN}OK${RESET} Draft #${argv.id} approved.\n`);
+    } catch (err) {
+      if (/503/.test(err.message)) {
+        console.log(`\n  ${YEL}Email send temporarily suppressed. Try approve again shortly.${RESET}\n`);
+        return;
+      }
+      console.error(`  ${RED}FAIL${RESET} ${err.message}`);
+      process.exit(1);
+    }
+  },
+};
+
+// dismiss
+
+const dismissCommand = {
+  command:  'dismiss <id>',
+  describe: 'Dismiss a pending automation draft without sending/applying it',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Draft ID' }),
+  handler: async (argv) => {
+    await messagingPost(`/AutomationDrafts/${argv.id}/dismiss`);
+    console.log(`\n  ${GRN}OK${RESET} Draft #${argv.id} dismissed.\n`);
+  },
+};
+
+// top-level automation-draft command
+
+export const automationDraftCommand = {
+  command:  'automation-draft <subcommand>',
+  describe: 'Review AI-composed drafts: workflow-composed emails, Focus suggested replies, CRM field updates (requires AiComposedEmails subscription)',
+  builder:  (y) => y
+    .command(listCommand)
+    .command(editCommand)
+    .command(approveCommand)
+    .command(dismissCommand)
+    .demandCommand(1, 'Specify an automation-draft subcommand.')
+    .strict(),
+  handler:  () => {},
+};

package/lib/commands/avatar.js

@@ -0,0 +1,75 @@
+import { request } from '../api.js';
+import { runCommand } from '../run.js';
+
+// ── velaro avatar ─────────────────────────────────────────────────────────────
+// Superadmin commands to inspect/configure the AI Video Avatar (Simli/D-ID/HeyGen)
+// for any customer site. Requires a Velaro admin JWT (site 1032).
+//
+// The customer-facing endpoints (GET/POST velaro-messaging /avatar/config) are
+// JWT-scoped to the caller's own site only — these hit velaro-admin's own
+// Avatar/superadmin/* endpoints instead, which can target any siteId.
+
+export const avatarCommand = {
+  command:  'avatar <subcommand>',
+  describe: 'Manage the AI Video Avatar for any site (Velaro admin only)',
+  builder:  yargs => yargs
+    .command({
+      command:  'get',
+      describe: 'Show AI Video Avatar 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', `/Avatar/superadmin/status?siteId=${argv.site}`);
+        if (!data.configured) {
+          console.log(`\nSite ${argv.site}: AI Video Avatar NOT configured (no saved config).\n`);
+          return;
+        }
+        console.log(`\nSite ${argv.site}: AI Video Avatar ${data.enabled ? 'ENABLED ✓' : 'configured but DISABLED'}`);
+        console.log(`  Provider:      ${data.providerSlug}`);
+        console.log(`  Avatar ID:     ${data.avatarId || '(provider default)'}`);
+        console.log(`  Voice ID:      ${data.voiceId || '(site default)'}`);
+        console.log(`  Enabled:       ${data.enabled ? 'yes' : 'no'}`);
+        console.log(`  "Call me":     ${data.showCallMeOption ? 'yes' : 'no'}`);
+        console.log(`  Callback window: ${data.callbackConfirmWindowMinutes} min\n`);
+      }),
+    })
+    .command({
+      command:  'enable',
+      describe: 'Turn on (or update) the AI Video Avatar for a site',
+      builder:  y => y
+        .option('site',     { type: 'number', demandOption: true, describe: 'Site ID' })
+        .option('provider', { type: 'string', describe: 'Avatar provider slug (simli, d-id, heygen). Default on first setup: simli. Omit on a re-run to leave the existing provider untouched.' })
+        .option('bot',      { type: 'string', describe: 'Reserved for a future per-bot override (not yet implemented on this endpoint)' })
+        .option('avatar-id',{ type: 'string', describe: 'Provider-specific avatar/face ID. Omit for provider default.' })
+        .option('voice',    { type: 'string', describe: 'ElevenLabs voice ID override' })
+        .option('call-me',  { type: 'boolean', describe: 'Show the "Call me instead" option. Omit on a re-run to leave it untouched.' }),
+      handler:  runCommand(async argv => {
+        if (argv.bot) {
+          console.log(`\nNote: --bot is not yet supported by this endpoint — this sets the SITE-level avatar config only. Use the admin UI's per-bot override toggle for bot-specific control.\n`);
+        }
+        // Partial update: only send fields the caller actually passed, so re-running `enable`
+        // to change one field (e.g. just --voice) never silently resets provider/call-me back
+        // to a hardcoded default on an existing config.
+        const body = { enabled: true };
+        body.providerSlug = argv.provider ?? 'simli';
+        if (argv['avatar-id'] !== undefined) body.avatarId = argv['avatar-id'];
+        if (argv.voice !== undefined) body.voiceId = argv.voice;
+        if (argv['call-me'] !== undefined) body.showCallMeOption = argv['call-me'];
+        const data = await request('POST', `/Avatar/superadmin/config?siteId=${argv.site}`, body);
+        if (!data.success) throw new Error(data.error || 'Configure failed');
+        console.log(`\n✓ AI Video Avatar enabled for site ${argv.site}`);
+        console.log(`  Provider:  ${data.providerSlug}`);
+        console.log(`  Avatar ID: ${data.avatarId || '(provider default)'}\n`);
+      }),
+    })
+    .command({
+      command:  'disable',
+      describe: 'Turn off the AI Video Avatar for a site (keeps the saved config)',
+      builder:  y => y.option('site', { type: 'number', demandOption: true, describe: 'Site ID' }),
+      handler:  runCommand(async argv => {
+        const data = await request('POST', `/Avatar/superadmin/config?siteId=${argv.site}`, { enabled: false });
+        if (!data.success) throw new Error(data.error || 'Update failed');
+        console.log(`\n✓ AI Video Avatar disabled for site ${argv.site}\n`);
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: get | enable | disable'),
+};

package/lib/commands/bigcommerce.js

@@ -0,0 +1,50 @@
+/**
+ * velaro bigcommerce — BigCommerce store management
+ *
+ *   velaro bigcommerce refund-check <siteId> <orderId>  Check whether an order is refundable
+ */
+
+import { messagingGet } from '../api.js';
+
+const GRN  = '\x1b[32m';
+const RED  = '\x1b[31m';
+const DIM  = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+// ── refund-check ──────────────────────────────────────────────────────────────
+
+async function refundCheckHandler(argv) {
+  try {
+    const data = await messagingGet(`/SupportTools/sites/${argv.siteId}/bigcommerce/refund-check/${argv.orderId}`);
+
+    if (data.refundable) {
+      const method = data.methods?.[0];
+      console.log(`\n${GRN}${BOLD}REFUNDABLE${RST} via ${BOLD}${method?.providerId ?? 'unknown'}${RST} (offline: ${method?.offline ? 'true' : 'false'})\n`);
+    } else {
+      console.log(`\n${RED}${BOLD}NOT REFUNDABLE${RST} — ${data.message ?? data.error ?? 'unknown reason'}.`);
+      console.log(`${DIM}Recreate this order using an offline/manual payment method or the BigCommerce Test Payment Gateway (Settings > Payments), then re-check.${RST}\n`);
+    }
+  } catch (e) {
+    console.error(`\n${RED}✗ Refund check failed: ${e.message}${RST}\n`);
+    process.exitCode = 1;
+  }
+}
+
+// ── command export ────────────────────────────────────────────────────────────
+
+export const bigcommerceCommand = {
+  command:  'bigcommerce <subcommand>',
+  describe: 'BigCommerce store management',
+  builder: y => y
+    .command({
+      command:  'refund-check <siteId> <orderId>',
+      describe: 'Check whether a BigCommerce order currently has a refundable payment record',
+      builder: yy => yy
+        .positional('siteId',  { describe: 'Site ID', type: 'number' })
+        .positional('orderId', { describe: 'BigCommerce order ID', type: 'number' }),
+      handler: refundCheckHandler,
+    })
+    .demandCommand(1, 'Specify a subcommand. Run "velaro bigcommerce --help" for options.'),
+  handler: () => {},
+};

package/lib/commands/billing-contacts.js

@@ -0,0 +1,62 @@
+// velaro billing-contacts — manage per-site billing contacts (CC on contracts)
+import { request } from '../api.js';
+
+async function listContacts() {
+  const contacts = await request('GET', '/BillingContacts');
+  if (!Array.isArray(contacts) || contacts.length === 0) {
+    console.log('No billing contacts on file.');
+    return;
+  }
+  console.log(`\nBilling Contacts (${contacts.length})\n${'─'.repeat(50)}`);
+  for (const c of contacts) {
+    const cc = c.ccOnContracts ? ' [CC on contracts]' : '';
+    console.log(`  [${c.id}] ${c.name} <${c.email}>  ${c.role}${c.title ? ' · ' + c.title : ''}${cc}`);
+    if (c.phone) console.log(`       ${c.phone}`);
+  }
+  console.log('');
+}
+
+async function addContact(args) {
+  if (!args.name || !args.email) {
+    console.error('Usage: velaro billing-contacts add --name "Jane Smith" --email jane@company.com [--role Billing] [--title CFO] [--phone "+1 555 000 0000"] [--no-cc]');
+    process.exit(1);
+  }
+  const body = {
+    name:          args.name,
+    email:         args.email,
+    role:          args.role ?? 'Billing',
+    title:         args.title,
+    phone:         args.phone,
+    ccOnContracts: args.cc !== false,
+  };
+  const result = await request('POST', '/BillingContacts', body);
+  console.log(`✅ Added: ${result.name} <${result.email}> (${result.role}) ID=${result.id}`);
+}
+
+async function removeContact(id) {
+  if (!id) {
+    console.error('Usage: velaro billing-contacts remove <id>');
+    process.exit(1);
+  }
+  await request('DELETE', `/BillingContacts/${id}`);
+  console.log(`✅ Billing contact ${id} removed.`);
+}
+
+export const billingContactsCommand = {
+  command: 'billing-contacts <subcommand>',
+  describe: 'Manage billing contacts (people CC\'d on contracts)',
+  builder: (yargs) =>
+    yargs
+      .command('list', 'List billing contacts', {}, () => listContacts())
+      .command('add', 'Add a billing contact', {
+        name:  { type: 'string', describe: 'Full name', demandOption: true },
+        email: { type: 'string', describe: 'Email address', demandOption: true },
+        role:  { type: 'string', describe: 'Primary | Billing | Technical | Legal', default: 'Billing' },
+        title: { type: 'string', describe: 'Job title' },
+        phone: { type: 'string', describe: 'Phone number' },
+        cc:    { type: 'boolean', describe: 'CC on contract emails', default: true },
+      }, (args) => addContact(args))
+      .command('remove <id>', 'Remove a billing contact by ID', {}, (args) => removeContact(args.id))
+      .demandCommand(1, 'Specify a subcommand: list | add | remove'),
+  handler: () => {},
+};

package/lib/commands/billing-email-preference.js

@@ -0,0 +1,64 @@
+// velaro billing-email-preference — governed billing-notification email-type preferences
+// (BillingEmailPreferenceController). Data model + UX only — no command here sends, or can send,
+// a real customer email. Every type defaults OFF; see the "New feature requested by Alex"
+// section of project_unified_billing_system_2026_08_30.md.
+import { request } from '../api.js';
+
+async function listPreferences(args) {
+  const url = args.siteId ? `/BillingEmailPreference?siteId=${args.siteId}` : '/BillingEmailPreference';
+  const result = await request('GET', url);
+
+  console.log(`\nLive today (informational — not governed here)\n${'-'.repeat(70)}`);
+  for (const s of result.liveToday) {
+    console.log(`  ${s.displayName}`);
+    console.log(`    ${s.description}`);
+    console.log(`    source: ${s.sourceLocation}`);
+  }
+
+  console.log(`\nGoverned types${args.siteId ? ` (site ${args.siteId})` : ' (system defaults)'}\n${'-'.repeat(70)}`);
+  for (const t of result.governed) {
+    const reach = t.isCurrentlyReachable ? '' : '  [not built yet — no event exists to trigger this]';
+    const setBy = args.siteId ? `  effective=${t.effective} (set by ${t.setBy})` : `  systemDefault=${t.systemDefault}`;
+    console.log(`  [${t.notificationType}] ${t.displayName}${reach}${setBy}`);
+  }
+  console.log('');
+}
+
+async function setPreference(notificationType, args) {
+  if (!args.siteId || args.enabled == null) {
+    console.error('Usage: velaro billing-email-preference set <notificationType> --site-id 100150 --enabled true|false');
+    process.exit(1);
+  }
+  const result = await request('PUT', `/BillingEmailPreference/${notificationType}?siteId=${args.siteId}`, {
+    isEnabled: args.enabled === 'true' || args.enabled === true,
+  });
+  console.log(`Site ${args.siteId} override for ${result.notificationType}: ${result.siteOverride}`);
+}
+
+async function resetPreference(notificationType, args) {
+  if (!args.siteId) {
+    console.error('Usage: velaro billing-email-preference reset <notificationType> --site-id 100150');
+    process.exit(1);
+  }
+  const result = await request('DELETE', `/BillingEmailPreference/${notificationType}?siteId=${args.siteId}`);
+  console.log(result.reset ? `Site ${args.siteId} override for ${notificationType} reset to system default.` : `No override existed for ${notificationType}.`);
+}
+
+export const billingEmailPreferenceCommand = {
+  command: 'billing-email-preference <subcommand>',
+  describe: 'View and set billing email-notification-type preferences (data model + UX only — no real email is ever sent by this command)',
+  builder: (yargs) =>
+    yargs
+      .command('list', 'List live-today senders + governed types (with effective value if --site-id given)', {
+        'site-id': { type: 'number', desc: 'View effective value + override state for this site instead of system defaults only' },
+      }, (args) => listPreferences(args))
+      .command('set <notificationType>', 'Set a site-level override for one governed type', {
+        'site-id': { type: 'number' },
+        enabled: { type: 'string', desc: 'true or false' },
+      }, (args) => setPreference(args.notificationType, args))
+      .command('reset <notificationType>', "Reset a site's override back to the system default", {
+        'site-id': { type: 'number' },
+      }, (args) => resetPreference(args.notificationType, args))
+      .demandCommand(1, 'Specify a subcommand: list | set | reset'),
+  handler: () => {},
+};

package/lib/commands/billing-subscription.js

@@ -0,0 +1,265 @@
+// velaro billing-subscription — standalone, entitlement-decoupled recurring billing subscriptions
+// (BillingSubscriptionController). See project_billing_subscription_target_decoupling.md — these
+// records do not require a v20 SiteId and work for any product (v10/v20/none).
+import { request } from '../api.js';
+
+function money(cents) {
+  return `$${(cents / 100).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+async function createSubscription(args) {
+  if (!args.customer || !args.start || !args.end) {
+    console.error('Usage: velaro billing-subscription create --customer "Liberty Mutual" --start 2026-11-17 --end 2027-11-16 [--po 4500175509] [--cadence annual] [--payment-method cash] [--total-cents 7357397] [--net-terms 30] [--lead-days 30] [--enable-billing] [--stripe-customer-id cus_...]');
+    process.exit(1);
+  }
+  const body = {
+    customerName: args.customer,
+    poNumber: args.po,
+    targetSystem: args.target,
+    targetAccountId: args.targetAccountId,
+    billingCadence: args.cadence ?? 'annual',
+    paymentMethod: args.paymentMethod ?? 'cash',
+    billingEnabled: !!args.enableBilling,
+    contractSignedDate: args.signed,
+    serviceStartDate: args.start,
+    serviceEndDate: args.end,
+    nextBillDate: args.nextBillDate,
+    invoiceLeadDays: args.leadDays ?? 30,
+    netTermsDays: args.netTerms ?? 30,
+    cancellationNoticeDays: args.cancellationNoticeDays ?? 30,
+    totalContractValueCents: args.totalCents ?? 0,
+    stripeCustomerId: args.stripeCustomerId,
+    notes: args.notes,
+  };
+  const result = await request('POST', '/api/BillingSubscription', body);
+  console.log(`Subscription created: ID=${result.id}`);
+}
+
+async function attachStripeCustomer(id, args) {
+  if (!args.email && !args.stripeCustomerId) {
+    console.error('Usage: velaro billing-subscription attach-stripe-customer <id> --email billing@customer.com   (looks up or creates a Stripe customer by email)');
+    console.error('   or: velaro billing-subscription attach-stripe-customer <id> --stripe-customer-id cus_xxx    (attach a known Stripe customer ID directly)');
+    process.exit(1);
+  }
+  const body = { email: args.email, stripeCustomerId: args.stripeCustomerId };
+  const result = await request('POST', `/api/BillingSubscription/${id}/stripe-customer`, body);
+  console.log(`Subscription ${result.id} attached to Stripe customer ${result.stripeCustomerId}`);
+}
+
+async function listSubscriptions() {
+  const rows = await request('GET', '/api/BillingSubscription');
+  if (!Array.isArray(rows) || rows.length === 0) {
+    console.log('No billing subscriptions on file.');
+    return;
+  }
+  console.log(`\nBilling Subscriptions (${rows.length})\n${'-'.repeat(60)}`);
+  for (const s of rows) {
+    console.log(`  [${s.id}] ${s.customerName}  PO=${s.poNumber ?? '(none)'}  ${s.billingCadence}/${s.paymentMethod}  billingEnabled=${s.billingEnabled}  stripeCustomerId=${s.stripeCustomerId ?? '(none)'}`);
+    console.log(`       ${s.serviceStartDate?.slice(0, 10)} .. ${s.serviceEndDate?.slice(0, 10)}`);
+  }
+  console.log('');
+}
+
+function daysFromNow(dateStr) {
+  const target = new Date(dateStr + 'T00:00:00Z');
+  const today = new Date(new Date().toISOString().slice(0, 10) + 'T00:00:00Z');
+  return Math.round((target - today) / 86400000);
+}
+
+async function renewalsReport(args) {
+  const withinDays = args.withinDays ?? 9999;
+  const rows = await request('GET', '/api/BillingSubscription');
+  if (!Array.isArray(rows) || rows.length === 0) {
+    console.log('No billing subscriptions on file.');
+    return;
+  }
+  const report = rows.map(s => {
+    const end = s.serviceEndDate?.slice(0, 10);
+    const daysToRenewal = end ? daysFromNow(end) : null;
+    const cancelDeadline = end ? new Date(new Date(end + 'T00:00:00Z').getTime() - s.cancellationNoticeDays * 86400000).toISOString().slice(0, 10) : null;
+    const daysToCancelDeadline = cancelDeadline ? daysFromNow(cancelDeadline) : null;
+    return { ...s, end, daysToRenewal, cancelDeadline, daysToCancelDeadline };
+  })
+  .filter(r => r.daysToRenewal == null || r.daysToRenewal <= withinDays)
+  .sort((a, b) => (a.daysToRenewal ?? Infinity) - (b.daysToRenewal ?? Infinity));
+
+  console.log(`\nRenewal Report${args.withinDays ? ` (within ${withinDays} days)` : ''}\n${'-'.repeat(90)}`);
+  for (const r of report) {
+    const canStillCancel = r.daysToCancelDeadline != null && r.daysToCancelDeadline >= 0;
+    const status = r.daysToCancelDeadline == null
+      ? 'no end date on file'
+      : canStillCancel
+        ? `can still cancel — ${r.daysToCancelDeadline}d left to give notice`
+        : `PAST cancellation window — will auto-renew (deadline was ${r.cancelDeadline})`;
+    console.log(`  [${r.id}] ${r.customerName}  renews ${r.end} (${r.daysToRenewal}d)  ${status}`);
+  }
+  console.log('');
+}
+
+async function getSubscription(id) {
+  const sub = await request('GET', `/api/BillingSubscription/${id}`);
+  console.log(JSON.stringify(sub, null, 2));
+}
+
+async function generateInvoice(id, args) {
+  if (!args.lineDescription || args.amountCents == null) {
+    console.error('Usage: velaro billing-subscription invoice <id> --line-description "Annual" --amount-cents 7357397 [--pre-generate] [--po ...] [--invoice-date YYYY-MM-DD] [--due-date YYYY-MM-DD] [--service-start YYYY-MM-DD] [--service-end YYYY-MM-DD] [--notes ...]');
+    process.exit(1);
+  }
+  const body = {
+    poNumber: args.po,
+    servicePeriodStart: args.serviceStart,
+    servicePeriodEnd: args.serviceEnd,
+    invoiceDate: args.invoiceDate,
+    dueDate: args.dueDate,
+    isPreGenerated: !!args.preGenerate,
+    internalNotes: args.notes,
+    lineItems: [{ description: args.lineDescription, amountCents: Number(args.amountCents) }],
+  };
+  const invoice = await request('POST', `/api/BillingSubscription/${id}/invoice`, body);
+  console.log(`Invoice ${invoice.invoiceNumberFormatted} (id=${invoice.id}) — ${money(invoice.totalCents)}, status=${invoice.status}`);
+}
+
+async function recordPayment(invoiceId, args) {
+  if (args.amountCents == null) {
+    console.error('Usage: velaro billing-subscription payment <invoiceId> --amount-cents 7357397 [--method cash|check|ach|wire|card] [--date YYYY-MM-DD] [--reference "..."] [--note "..."]');
+    process.exit(1);
+  }
+  const body = {
+    amountCents: Number(args.amountCents),
+    method: args.method ?? 'cash',
+    paymentDate: args.date,
+    reference: args.reference,
+    note: args.note,
+  };
+  const payment = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/payment`, body);
+  console.log(`Payment recorded: id=${payment.id}, amount=${money(payment.amountCents)}, method=${payment.method}`);
+}
+
+async function listPayments(invoiceId) {
+  const result = await request('GET', `/api/BillingSubscription/invoice/${invoiceId}/payments`);
+  console.log(`\nPayments for invoice ${invoiceId}\n${'-'.repeat(50)}`);
+  for (const p of result.payments) {
+    console.log(`  [${p.id}] ${money(p.amountCents)}  ${p.method}  ${p.paymentDate?.slice(0, 10)}  ref=${p.reference ?? '(none)'}`);
+  }
+  console.log(`\nBalance: applied ${money(result.balance.appliedCents)} / total ${money(result.balance.totalCents)} — remaining ${money(result.balance.remainingCents)} — paidInFull=${result.balance.paidInFull}\n`);
+}
+
+async function qboStatus(invoiceId) {
+  const result = await request('GET', `/api/BillingSubscription/invoice/${invoiceId}/qbo-sync-status`);
+  console.log(`Invoice ${result.invoice.invoiceNumberFormatted}: QBO status = ${result.invoice.qboSyncStatus ?? '(none)'}`);
+  for (const p of result.payments) {
+    console.log(`  Payment ${p.id}: QBO status = ${p.qboSyncStatus ?? '(none)'}, syncedAt = ${p.qboSyncedAt ?? '(never)'}`);
+  }
+}
+
+async function provisionPlaceholderSite(id, args) {
+  if (!args.tier) {
+    console.error('Usage: velaro billing-subscription provision-placeholder-site <id> --tier Professional [--admin-email placeholder+staxbill-123@velaro.com] [--preview]');
+    process.exit(1);
+  }
+  const body = {
+    subscriptionTier: args.tier,
+    adminEmailOverride: args.adminEmail,
+    preview: !!args.preview,
+  };
+  const result = await request('POST', `/api/BillingSubscription/${id}/provision-placeholder-site`, body);
+
+  if (args.preview) {
+    console.log(`\nPreview: provision-placeholder-site for subscription ${result.subscriptionId}\n${'-'.repeat(60)}`);
+    console.log(`  Company:  ${result.companyName}`);
+    console.log(`  Admin:    ${result.adminEmail}`);
+    console.log(`  Tier:     ${result.subscriptionTier}`);
+    if (result.existingSiteId != null) {
+      console.log(`  SiteId:   ${result.existingSiteId} (already allocated -- would be REUSED, not re-allocated)`);
+    } else {
+      console.log(`  SiteId:   (would allocate a new placeholder id -- not shown here, preview never consumes a sequence value)`);
+    }
+    console.log('  No writes made (--preview).\n');
+    return;
+  }
+
+  if (result.provisioningSucceeded) {
+    console.log(`\x1b[32mOK: placeholder site ${result.siteId} provisioned for subscription ${result.subscriptionId}\x1b[0m`);
+    console.log(`  Company: ${result.companyName}`);
+    console.log(`  Admin:   ${result.adminEmail}`);
+    console.log(`  Tier:    ${result.subscriptionTier}`);
+    if (result.wasAlreadyAllocated) console.log(`  (SiteId was already allocated by a prior call -- resumed, not re-allocated.)`);
+  } else {
+    console.error(`\x1b[31mSiteId ${result.siteId} is allocated but provisioning FAILED: ${result.provisioningError}\x1b[0m`);
+    console.error(`  Check site ${result.siteId} manually, or retry this same command -- it will resume against the same SiteId, not allocate a new one.`);
+    process.exit(1);
+  }
+}
+
+async function recognitionSchedule(invoiceId) {
+  const rows = await request('GET', `/api/BillingSubscription/invoice/${invoiceId}/recognition-schedule`);
+  console.log(`\nRevenue recognition schedule for invoice ${invoiceId}\n${'-'.repeat(50)}`);
+  for (const r of rows) {
+    console.log(`  ${r.recognitionMonth.slice(0, 7)}  ${money(r.amountCents)}  [${r.status}]`);
+  }
+  console.log(`\nTotal: ${money(rows.reduce((sum, r) => sum + r.amountCents, 0))}\n`);
+}
+
+export const billingSubscriptionCommand = {
+  command: 'billing-subscription <subcommand>',
+  describe: 'Manage standalone billing subscriptions, invoices, payments, and QBO dry-run sync status',
+  builder: (yargs) =>
+    yargs
+      .command('list', 'List all billing subscriptions', {}, () => listSubscriptions())
+      .command('get <id>', 'Get a subscription by ID (with invoices)', {}, (args) => getSubscription(args.id))
+      .command('create', 'Create a new billing subscription', {
+        customer:         { type: 'string' },
+        po:               { type: 'string' },
+        target:           { type: 'string' },
+        'target-account-id': { type: 'string' },
+        cadence:          { type: 'string', default: 'annual' },
+        'payment-method': { type: 'string', default: 'cash' },
+        signed:           { type: 'string' },
+        start:            { type: 'string' },
+        end:              { type: 'string' },
+        'next-bill-date': { type: 'string' },
+        'lead-days':      { type: 'number' },
+        'net-terms':      { type: 'number' },
+        'cancellation-notice-days': { type: 'number' },
+        'total-cents':    { type: 'number' },
+        notes:            { type: 'string' },
+        'enable-billing': { type: 'boolean', default: false },
+        'stripe-customer-id': { type: 'string' },
+      }, (args) => createSubscription(args))
+      .command('attach-stripe-customer <id>', 'Look up (by email) or create a Stripe customer and permanently attach it to a subscription', {
+        email:                { type: 'string' },
+        'stripe-customer-id': { type: 'string' },
+      }, (args) => attachStripeCustomer(args.id, args))
+      .command('invoice <id>', 'Generate (or pre-generate) an invoice for a subscription', {
+        'line-description': { type: 'string' },
+        'amount-cents':     { type: 'number' },
+        po:                 { type: 'string' },
+        'invoice-date':     { type: 'string' },
+        'due-date':         { type: 'string' },
+        'service-start':    { type: 'string' },
+        'service-end':      { type: 'string' },
+        'pre-generate':     { type: 'boolean', default: false },
+        notes:              { type: 'string' },
+      }, (args) => generateInvoice(args.id, args))
+      .command('provision-placeholder-site <id>', 'Allocate (or resume) a placeholder v20 SiteId and provision a real placeholder site under it via messaging', {
+        tier:          { type: 'string', describe: 'Subscription tier (required, no default -- e.g. Starter, Professional, Enterprise)' },
+        'admin-email': { type: 'string', describe: 'Override the default placeholder+staxbill-<id>@velaro.com admin email' },
+        preview:       { type: 'boolean', default: false, describe: 'Show what would happen without allocating or calling messaging' },
+      }, (args) => provisionPlaceholderSite(args.id, args))
+      .command('recognition-schedule <invoiceId>', 'Show the monthly revenue-recognition schedule for an invoice', {}, (args) => recognitionSchedule(args.invoiceId))
+      .command('payment <invoiceId>', 'Record a payment against an invoice', {
+        'amount-cents': { type: 'number' },
+        method:         { type: 'string', default: 'cash' },
+        date:           { type: 'string' },
+        reference:      { type: 'string' },
+        note:           { type: 'string' },
+      }, (args) => recordPayment(args.invoiceId, args))
+      .command('payments <invoiceId>', 'List payments + balance for an invoice', {}, (args) => listPayments(args.invoiceId))
+      .command('qbo-status <invoiceId>', 'Show QBO dry-run sync status for an invoice and its payments', {}, (args) => qboStatus(args.invoiceId))
+      .command('renewals', 'List subscriptions by upcoming renewal date, flagging who is still cancellable vs past their cancellation-notice deadline', {
+        'within-days': { type: 'number', desc: 'Only show renewals within this many days (default: all)' },
+      }, (args) => renewalsReport(args))
+      .demandCommand(1, 'Specify a subcommand: list | get | create | attach-stripe-customer | invoice | provision-placeholder-site | recognition-schedule | payment | payments | qbo-status | renewals'),
+  handler: () => {},
+};