@velaro/cli 1.4.54 → 1.4.55

package/lib/commands/billing-subscription.js

@@ -1,7 +1,9 @@
 // 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 path from 'node:path';
 import { request } from '../api.js';
+import { generateBillingDocument } from '../pdf/billing-document.js';
 
 function money(cents) {
   return `$${(cents / 100).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
@@ -9,7 +11,7 @@ function money(cents) {
 
 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_...]');
+    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_...] [--force]');
     process.exit(1);
   }
   const body = {
@@ -28,13 +30,43 @@ async function createSubscription(args) {
     netTermsDays: args.netTerms ?? 30,
     cancellationNoticeDays: args.cancellationNoticeDays ?? 30,
     totalContractValueCents: args.totalCents ?? 0,
+    recurringAmountCents: args.recurringAmountCents,
     stripeCustomerId: args.stripeCustomerId,
     notes: args.notes,
+    force: !!args.force,
   };
   const result = await request('POST', '/api/BillingSubscription', body);
   console.log(`Subscription created: ID=${result.id}`);
 }
 
+async function deleteSubscription(id, args) {
+  const sub = await request('GET', `/api/BillingSubscription/${id}`);
+  const invoices = Array.isArray(sub.invoices) ? sub.invoices : [];
+  console.log(`\nAbout to permanently delete BillingSubscription ${id}\n${'-'.repeat(60)}`);
+  console.log(`  Customer: ${sub.customerName}`);
+  console.log(`  Period:   ${sub.serviceStartDate?.slice(0, 10)} .. ${sub.serviceEndDate?.slice(0, 10)}`);
+  console.log(`  Invoices to be cascade-deleted (${invoices.length}):`);
+  for (const inv of invoices) {
+    console.log(`    - ${inv.invoiceNumberFormatted}  ${money(inv.totalCents)}  status=${inv.status}`);
+  }
+  if (!args.confirm) {
+    console.log('\nAdd --confirm to actually delete this subscription. No changes made.\n');
+    return;
+  }
+  const result = await request('DELETE', `/api/BillingSubscription/${id}`);
+  console.log(`\n\x1b[32mDeleted subscription ${result.subscriptionId} (${result.customerName}) and ${result.deletedInvoiceCount} invoice(s).\x1b[0m\n`);
+}
+
+async function deleteInvoice(invoiceId, args) {
+  if (!args.confirm) {
+    console.log(`\nAdd --confirm to permanently delete invoice ${invoiceId}. No changes made.`);
+    console.log('(Delete is refused server-side if the invoice has a recorded payment or has already been sent/paid/voided.)\n');
+    return;
+  }
+  const result = await request('DELETE', `/api/BillingSubscription/invoice/${invoiceId}`);
+  console.log(`\x1b[32mDeleted invoice ${result.invoiceNumberFormatted} (id=${result.invoiceId}) from subscription ${result.subscriptionId}.\x1b[0m`);
+}
+
 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)');
@@ -103,7 +135,7 @@ async function getSubscription(id) {
 
 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 ...]');
+    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 ...] [--number-mode sequential|random-jitter] [--number-max-jitter 10] [--invoice-number 50042]');
     process.exit(1);
   }
   const body = {
@@ -115,6 +147,9 @@ async function generateInvoice(id, args) {
     isPreGenerated: !!args.preGenerate,
     internalNotes: args.notes,
     lineItems: [{ description: args.lineDescription, amountCents: Number(args.amountCents) }],
+    numberMode: args.numberMode ?? 'sequential',
+    numberMaxJitter: args.numberMaxJitter ?? 10,
+    manualInvoiceNumber: args.invoiceNumber != null ? Number(args.invoiceNumber) : undefined,
   };
   const invoice = await request('POST', `/api/BillingSubscription/${id}/invoice`, body);
   console.log(`Invoice ${invoice.invoiceNumberFormatted} (id=${invoice.id}) — ${money(invoice.totalCents)}, status=${invoice.status}`);
@@ -134,6 +169,76 @@ async function recordPayment(invoiceId, args) {
   };
   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}`);
+  // The server-side shared payment-applied handler has already run (RecordPaymentAsync); show the
+  // resulting billing clock so the operator sees what the payment did.
+  try {
+    printExpiry(await request('GET', `/api/BillingSubscription/invoice/${invoiceId}/expiry`));
+  } catch (e) {
+    console.log(`(paid-through lookup failed: ${e.message})`);
+  }
+}
+
+function printExpiry(e) {
+  const d = (v) => (v ? String(v).slice(0, 10) : '(none)');
+  console.log(`Subscription ${e.subscriptionId} (${e.customerName}): paid-through=${d(e.paidThroughAt)}, policy=${e.expiryPolicy}, grace=${e.gracePeriodDays}d, ` +
+    `effective-expiry=${e.expiryPolicy === 'NeverExpire' ? 'never' : d(e.effectiveExpiresAt)}` +
+    (e.overrideActive ? `, OVERRIDE until ${d(e.expiryOverrideUntil)} (${e.expiryOverrideReason ?? 'no reason'})` : ''));
+}
+
+async function showExpiry(id) {
+  printExpiry(await request('GET', `/api/BillingSubscription/${id}/expiry`));
+}
+
+async function setExpiryPolicy(id, args) {
+  if (!args.policy || !args.reason) {
+    console.error('Usage: velaro billing-subscription set-expiry-policy <id> --policy Default|CustomGrace|NeverExpire [--grace-days N] --reason "..."');
+    process.exit(1);
+  }
+  printExpiry(await request('POST', `/api/BillingSubscription/${id}/expiry-policy`, {
+    expiryPolicy: args.policy,
+    gracePeriodDays: args.graceDays != null ? Number(args.graceDays) : undefined,
+    reason: args.reason,
+  }));
+}
+
+async function sendInvoice(invoiceId, args) {
+  const res = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/send${args.force ? '?force=true' : ''}`, {});
+  if (res.alreadySent) console.log(`Invoice ${invoiceId} was already sent ${res.sentAt}; nothing sent (use --force to resend).`);
+  else console.log(`Invoice ${invoiceId} sent to ${res.recipient} at ${res.sentAt}${res.payLinkIncluded ? ' (pay link included)' : ' (no pay link)'}.`);
+}
+
+function printReminders(v) {
+  console.log(`Subscription ${v.id} (${v.customerName}): reminders ${v.enabled ? 'ON' : 'OFF'}`);
+  console.log(`  cadence (days from due): ${v.cadence}${v.cadenceIsDefault ? ' (default)' : ''}`);
+  console.log(`  contact email: ${v.contactEmail ?? '(none)'}; resolved recipient: ${v.resolvedRecipient ?? '(none, sends will fail)'}`);
+  console.log(`  expiry policy: ${v.expiryPolicy}; effective expiry: ${v.effectiveExpiry ?? 'never'}`);
+  for (const i of v.openInvoices || []) {
+    console.log(`  invoice ${i.id} ${i.invoiceNumberFormatted} due ${i.dueDate} sent ${i.sentAt ?? 'NO'} reminders ${i.reminderCount} last ${i.lastReminderSentAt ?? '-'}`);
+  }
+}
+
+async function reminders(id, args) {
+  const change = args.on || args.off || args.cadence != null || args.email != null;
+  if (args.on && args.off) { console.error('Use only one of --on / --off.'); process.exit(1); }
+  if (!change) return printReminders(await request('GET', `/api/BillingSubscription/${id}/reminders`));
+  const body = {};
+  if (args.on) body.enabled = true;
+  if (args.off) body.enabled = false;
+  if (args.cadence != null) body.cadence = String(args.cadence);
+  if (args.email != null) body.contactEmail = String(args.email);
+  printReminders(await request('POST', `/api/BillingSubscription/${id}/reminders`, body));
+}
+
+async function pushExpiry(id, args) {
+  if (!args.reason || (!args.clear && !args.until)) {
+    console.error('Usage: velaro billing-subscription push-expiry <id> --until YYYY-MM-DD --reason "..."   (or --clear --reason "...")');
+    process.exit(1);
+  }
+  printExpiry(await request('POST', `/api/BillingSubscription/${id}/expiry-override`, {
+    until: args.until ? new Date(args.until).toISOString() : undefined,
+    reason: args.reason,
+    clear: !!args.clear,
+  }));
 }
 
 async function listPayments(invoiceId) {
@@ -153,6 +258,21 @@ async function qboStatus(invoiceId) {
   }
 }
 
+async function invoiceSendLog(invoiceId) {
+  const result = await request('GET', `/api/BillingSubscription/invoice/${invoiceId}/send-log`);
+  const inv = result.invoice;
+  console.log(`Invoice ${inv.invoiceNumberFormatted}: SentAt = ${inv.sentAt ?? '(never)'}, failures = ${inv.sendFailureCount}${inv.lastSendError ? `, lastError = ${inv.lastSendError}` : ''}`);
+  if (result.log.length === 0) {
+    console.log('  No send attempts recorded.');
+    return;
+  }
+  for (const l of result.log) {
+    const statusUpdate = l.statusUpdatedAtUtc ? ` (updated ${l.statusUpdatedAtUtc})` : '';
+    const detail = l.statusDetail ? ` -- ${l.statusDetail}` : '';
+    console.log(`  [${l.sentAtUtc}] ${l.recipientRole} ${l.recipientEmail}: ${l.status}${statusUpdate}${detail} (acsMessageId=${l.acsMessageId ?? 'none'})`);
+  }
+}
+
 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]');
@@ -211,6 +331,40 @@ async function setAutoRenew(id, args) {
   console.log(`Subscription ${result.id}: AutoRenew = ${result.autoRenew}`);
 }
 
+async function cancelSub(id, args) {
+  if (!args.mode) {
+    console.error('Usage: velaro billing-subscription cancel <id> --mode bill_more_periods|shutdown_accelerate|shutdown_keep_recognizing|shutdown_after_covered [--extra-periods N] [--effective-date YYYY-MM-DD] [--reason "..."]');
+    process.exit(1);
+  }
+  const r = await request('POST', `/api/BillingSubscription/${id}/cancel`, {
+    mode: args.mode, extraPeriods: args.extraPeriods, effectiveDate: args.effectiveDate, reason: args.reason,
+  });
+  console.log(`Subscription ${r.subscriptionId}: ${r.mode}, service ends ${r.serviceEndDate}, accelerated cents ${r.acceleratedCents}`);
+}
+
+async function oneTimeInvoice(id, args) {
+  if (!args.description || args.amountCents == null) {
+    console.error('Usage: velaro billing-subscription one-time-invoice <id> --description "..." --amount-cents N [--date YYYY-MM-DD] [--po X]');
+    process.exit(1);
+  }
+  const r = await request('POST', `/api/BillingSubscription/${id}/one-time-invoice`, {
+    invoiceDate: args.date, poNumber: args.po,
+    lineItems: [{ description: args.description, amountCents: args.amountCents }],
+  });
+  console.log(`One-time invoice ${r.invoiceNumber} (id ${r.id}) total ${money(r.totalCents)} status ${r.status}`);
+}
+
+async function midTermUpgrade(id, args) {
+  if (args.newAmountCents == null) {
+    console.error('Usage: velaro billing-subscription mid-term-upgrade <id> --new-amount-cents N [--effective-date YYYY-MM-DD] [--reason "..."]');
+    process.exit(1);
+  }
+  const r = await request('POST', `/api/BillingSubscription/${id}/mid-term-upgrade`, {
+    newRecurringAmountCents: args.newAmountCents, effectiveDate: args.effectiveDate, reason: args.reason,
+  });
+  console.log(`Subscription ${r.subscriptionId}: ${money(r.oldRecurringAmountCents)} -> ${money(r.newRecurringAmountCents)}, proration ${money(r.prorationCents)} co-terminous to ${r.coTermEnd}`);
+}
+
 async function scheduleCadenceChange(id, args) {
   if (args.cadence && !args.effectiveAt) {
     console.error('Usage: velaro billing-subscription schedule-cadence-change <id> --cadence annual|monthly|quarterly --effective-at YYYY-MM-DD');
@@ -228,6 +382,334 @@ async function scheduleCadenceChange(id, args) {
   }
 }
 
+async function correctPayment(paymentId, args) {
+  if (!args.field || args.reason == null) {
+    console.error('Usage: velaro billing-subscription payment-correct <paymentId> --field date|amount-cents|method|reference|note --value <v> --reason "..."');
+    process.exit(1);
+  }
+  const body = { field: args.field, value: args.value != null ? String(args.value) : undefined, reason: args.reason };
+  const result = await request('POST', `/api/BillingSubscription/payment/${paymentId}/correct`, body);
+  console.log(`Payment ${result.id} corrected: ${args.field} -> ${args.value}`);
+}
+
+async function paymentHistory(paymentId) {
+  const result = await request('GET', `/api/BillingSubscription/payment/${paymentId}/history`);
+  console.log(`\nPayment ${paymentId} -- live value\n${'-'.repeat(60)}`);
+  console.log(`  Amount:    ${money(result.payment.amountCents)}`);
+  console.log(`  Date:      ${result.payment.paymentDate?.slice(0, 10)}`);
+  console.log(`  Method:    ${result.payment.method}`);
+  console.log(`  Reference: ${result.payment.reference ?? '(none)'}`);
+  console.log(`  Note:      ${result.payment.note ?? '(none)'}`);
+  console.log(`\nCorrection history (${result.corrections.length})\n${'-'.repeat(60)}`);
+  for (const c of result.corrections) {
+    console.log(`  [${c.correctedAt?.slice(0, 19)}] ${c.fieldName}: "${c.oldValue}" -> "${c.newValue}"  (by ${c.correctedBy}: ${c.reason})`);
+  }
+  console.log('');
+}
+
+async function correctInvoice(invoiceId, args) {
+  if (!args.field || args.reason == null) {
+    console.error('Usage: velaro billing-subscription invoice-correct <invoiceId> --field po-number|invoice-date|due-date|total-cents|internal-notes|service-period-start|service-period-end --value <v> --reason "..."');
+    process.exit(1);
+  }
+  const body = { field: args.field, value: args.value != null ? String(args.value) : undefined, reason: args.reason };
+  const result = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/correct`, body);
+  console.log(`Invoice ${result.invoiceNumberFormatted} (id=${result.id}) corrected: ${args.field} -> ${args.value}`);
+}
+
+async function invoiceHistory(invoiceId) {
+  const result = await request('GET', `/api/BillingSubscription/invoice/${invoiceId}/history`);
+  console.log(`\nInvoice ${result.invoice.invoiceNumberFormatted} -- live value\n${'-'.repeat(60)}`);
+  console.log(`  Total:    ${money(result.invoice.totalCents)}`);
+  console.log(`  PO:       ${result.invoice.poNumber ?? '(none)'}`);
+  console.log(`  Invoice date / due date: ${result.invoice.invoiceDate?.slice(0, 10)} / ${result.invoice.dueDate?.slice(0, 10)}`);
+  console.log(`\nCorrection history (${result.corrections.length})\n${'-'.repeat(60)}`);
+  for (const c of result.corrections) {
+    console.log(`  [${c.correctedAt?.slice(0, 19)}] ${c.fieldName}: "${c.oldValue}" -> "${c.newValue}"  (by ${c.correctedBy}: ${c.reason})`);
+  }
+  console.log('');
+}
+
+async function correctSubscription(subscriptionId, args) {
+  if (!args.field || !args.reason) {
+    console.error('Usage: velaro billing-subscription subscription-correct <id> --field service-start-date|service-end-date|next-bill-date|po-number|notes|recurring-amount-cents|target-system|target-account-id|parallel-billing-mode|billing-cutover-date|external-billing-system|external-billing-account-id|auto-charge-enabled|invoice-delivery-action|invoice-recipient-emails|invoice-cc-emails|invoice-bcc-emails|contract-id|grace-period-days|auto-expire-after-grace-period|exclude-from-entitlement-sync|exclude-from-bulk-price-import --value <v> --reason "..." [--clear] [--force]');
+    process.exit(1);
+  }
+  const body = {
+    field: args.field,
+    value: args.value != null ? String(args.value) : undefined,
+    reason: args.reason,
+    clear: !!args.clear,
+    force: !!args.force,
+  };
+  const result = await request('POST', `/api/BillingSubscription/${subscriptionId}/correct`, body);
+  const sub = result.subscription;
+  const shownValue = args.clear ? '(cleared)' : (args.value ?? '(cleared/none)');
+  console.log(`Subscription ${sub.id} (${sub.customerName}) corrected: ${args.field} -> ${shownValue}`);
+  if (result.invoicesNeedingReconciliation && result.invoicesNeedingReconciliation.length > 0) {
+    console.log(`\n\x1b[33mWARNING\x1b[0m: ${result.invoicesNeedingReconciliation.length} existing invoice(s) on this subscription were NOT updated: ids ${result.invoicesNeedingReconciliation.join(', ')}.`);
+    console.log(`  Reconcile each with: velaro billing-subscription invoice-correct <invoiceId> --field service-period-start|service-period-end --value <v> --reason "..."`);
+  }
+}
+
+async function subscriptionHistory(subscriptionId) {
+  const result = await request('GET', `/api/BillingSubscription/${subscriptionId}/history`);
+  const sub = result.subscription;
+  console.log(`\nSubscription ${sub.id} (${sub.customerName}) -- live value\n${'-'.repeat(60)}`);
+  console.log(`  Service period: ${sub.serviceStartDate?.slice(0, 10)} -- ${sub.serviceEndDate?.slice(0, 10)}`);
+  console.log(`  Next bill date: ${sub.nextBillDate?.slice(0, 10) ?? '(none)'}`);
+  console.log(`  PO:             ${sub.poNumber ?? '(none)'}`);
+  console.log(`\nCorrection history (${result.corrections.length})\n${'-'.repeat(60)}`);
+  for (const c of result.corrections) {
+    console.log(`  [${c.correctedAt?.slice(0, 19)}] ${c.fieldName}: "${c.oldValue}" -> "${c.newValue}"  (by ${c.correctedBy}: ${c.reason})`);
+  }
+  console.log('');
+}
+
+async function reissueInvoice(invoiceId, args) {
+  if (!args.reason) {
+    console.error('Usage: velaro billing-subscription invoice-reissue <invoiceId> --reason "..." [--service-period-start <date>] [--service-period-end <date>] [--po-number <v>]');
+    process.exit(1);
+  }
+  const body = {
+    reason: args.reason,
+    servicePeriodStart: args.servicePeriodStart,
+    servicePeriodEnd: args.servicePeriodEnd,
+    poNumber: args.poNumber,
+    internalNotes: args.internalNotes,
+  };
+  const result = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/reissue`, body);
+  console.log(`Invoice ${invoiceId} superseded. New invoice: ${result.invoiceNumberFormatted} (id=${result.id}).`);
+}
+
+async function releaseInvoice(invoiceId) {
+  const r = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/release`, {});
+  console.log(`Invoice ${invoiceId} released: status ${r.status}, sends at ${r.readyToSendAt?.slice(0, 10)}.`);
+}
+
+async function testFireInvoice(invoiceId) {
+  const r = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/test-fire`, {});
+  console.log(`Test-fire sent to internal recipients only: ${(r.recipients || []).join(', ')}`);
+}
+
+async function issueNow(id, args) {
+  const path = args.subscription
+    ? `/api/BillingSubscription/${id}/issue-now`
+    : `/api/BillingSubscription/invoice/${id}/issue-now`;
+  const r = await request('POST', path, {});
+  console.log(`Issued now: ${r.invoiceNumberFormatted} (id=${r.id}), dated ${r.invoiceDate?.slice(0, 10)}, status ${r.status}.`);
+}
+
+async function regenerateInvoice(invoiceId) {
+  const r = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/regenerate`, {});
+  console.log(`Regenerated: ${r.invoiceNumberFormatted} (id=${r.id}), total ${money(r.totalCents)}.`);
+}
+
+async function materializeInvoice(subscriptionId) {
+  const r = await request('POST', `/api/BillingSubscription/${subscriptionId}/materialize`, {});
+  console.log(`Materialized ${r.invoiceNumberFormatted} (id=${r.id}), status ${r.status}.`);
+}
+
+async function upcomingInvoices(args) {
+  const rows = await request('GET', `/api/BillingSubscription/upcoming?days=${args.days || 30}`);
+  if (!rows.length) { console.log('No upcoming invoices.'); return; }
+  for (const u of rows) {
+    console.log(`  [${u.kind}] sub ${u.subscriptionId} ${u.customerName} ${u.servicePeriodStart?.slice(0, 10)}..${u.servicePeriodEnd?.slice(0, 10)} sends ${u.sendAt?.slice(0, 10)} ${money(u.amountCents)} ${u.status || ''}${u.invoiceId ? ' (invoice ' + u.invoiceId + ')' : ''}${u.willSend ? '' : ' [WILL NOT SEND]'}`);
+  }
+}
+
+async function copyInvoice(invoiceId, args) {
+  const body = {
+    servicePeriodStart: args.servicePeriodStart,
+    servicePeriodEnd: args.servicePeriodEnd,
+    invoiceDate: args.invoiceDate,
+    poNumber: args.poNumber,
+  };
+  const r = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/copy`, body);
+  console.log(`Invoice ${invoiceId} copied to DRAFT ${r.invoiceNumberFormatted} (id=${r.id}), total ${money(r.totalCents)}. Edit with invoice-correct, then finalize.`);
+}
+
+async function copySubscription(id, args) {
+  if (!args.name) {
+    console.error('Usage: velaro billing-subscription subscription-copy <id> --name "New customer name" [--service-start-date <date>] [--service-end-date <date>]');
+    process.exit(1);
+  }
+  const body = { newCustomerName: args.name, serviceStartDate: args.serviceStartDate, serviceEndDate: args.serviceEndDate };
+  const r = await request('POST', `/api/BillingSubscription/${id}/copy`, body);
+  console.log(`Subscription ${id} copied to inactive draft id=${r.id} ("${r.customerName}"). BillingEnabled=false, AutoCharge=false, no NextBillDate.`);
+}
+
+async function pauseBilling(id, args) {
+  const body = { resumeDate: args.resumeDate, invoiceBehavior: args.invoiceBehavior, reason: args.reason };
+  const r = await request('POST', `/api/BillingSubscription/${id}/pause`, body);
+  console.log(`Billing paused for subscription ${id} (behavior=${r.pauseInvoiceBehavior}, resume=${r.billingResumeDate || 'manual'}).`);
+}
+
+async function resumeBilling(id) {
+  const r = await request('POST', `/api/BillingSubscription/${id}/resume`, {});
+  console.log(`Billing resumed for subscription ${id}. Next bill date: ${r.nextBillDate || 'none'}.`);
+}
+
+async function voidInvoice(invoiceId, args) {
+  if (!args.reason) {
+    console.error('Usage: velaro billing-subscription invoice-void <invoiceId> --reason "..."');
+    process.exit(1);
+  }
+  const r = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/void`, { reason: args.reason });
+  console.log(`Invoice ${r.invoiceNumberFormatted} voided.`);
+}
+
+async function creditNote(invoiceId, args) {
+  if (!args.reason || (args.amountCents === undefined && !args.lines)) {
+    console.error('Usage: velaro billing-subscription credit-note <invoiceId> --reason "..." (--amount-cents <n> | --lines "<lineItemId>:<cents>,<lineItemId>:<cents>")');
+    process.exit(1);
+  }
+  const body = { reason: args.reason };
+  if (args.lines) {
+    body.lines = String(args.lines).split(',').map((p) => {
+      const [id, cents] = p.split(':');
+      return { lineItemId: parseInt(id, 10), amountCents: parseInt(cents, 10) };
+    });
+  } else {
+    body.amountCents = Number(args.amountCents);
+  }
+  const r = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/credit-note`, body);
+  const due = await request('GET', `/api/BillingSubscription/invoice/${invoiceId}/amount-due`);
+  console.log(`Credit note ${r.creditNoteNumber} (id=${r.id}) for ${money(r.amountCents)} issued. Amount due now: ${money(due.amountDueCents)}.`);
+}
+
+async function creditNoteVoid(creditNoteId, args) {
+  const r = await request('POST', `/api/BillingSubscription/credit-note/${creditNoteId}/void`, { reason: args.reason });
+  console.log(`Credit note ${r.creditNoteNumber} voided.`);
+}
+
+async function creditNotes(invoiceId) {
+  const rows = await request('GET', `/api/BillingSubscription/invoice/${invoiceId}/credit-notes`);
+  if (!rows.length) { console.log('No credit notes.'); return; }
+  for (const r of rows) console.log(`${r.id}\t${r.creditNoteNumber}\t${money(r.amountCents)}\t${r.status}\t${r.reason}`);
+}
+
+async function runRenewalSweep() {
+  const result = await request('POST', '/api/BillingSubscription/renewal-sweep/run', {});
+  console.log(result.message || 'Renewal sweep triggered.');
+}
+
+async function runDunningReport() {
+  const report = await request('POST', '/api/BillingSubscription/dunning-report/run', {});
+  if (report.length === 0) {
+    console.log('No past-due invoices.');
+    return;
+  }
+  console.log(`\n${report.length} past-due invoice(s):\n${'-'.repeat(80)}`);
+  for (const r of report) {
+    let flag = r.willAutoExpire ? '\x1b[31mAUTO-EXPIRING\x1b[0m' : (r.pastGracePeriod ? '\x1b[33mPAST GRACE PERIOD\x1b[0m' : 'within grace period');
+    if (r.expiryPolicy === 'NeverExpire') flag += ' NEVER-EXPIRE';
+    if (r.overrideActive) flag += ` OVERRIDE until ${String(r.overrideUntil).slice(0, 10)}`;
+    console.log(`  Sub ${r.subscriptionId} (${r.customerName}) -- ${r.invoiceNumberFormatted}: ${money(r.amountOwedCents)} owed, ${r.daysPastDue}d past due (grace ${r.gracePeriodDays}d) [${flag}]`);
+  }
+  console.log('');
+}
+
+async function revenueReport(args) {
+  const params = new URLSearchParams();
+  if (args.fromMonth) params.set('fromMonth', args.fromMonth);
+  if (args.throughMonth) params.set('throughMonth', args.throughMonth);
+  const qs = params.toString() ? `?${params.toString()}` : '';
+  const rows = await request('GET', `/api/BillingSubscription/reports/revenue-recognition${qs}`);
+  if (rows.length === 0) {
+    console.log('No recognized revenue rows in range.');
+    return;
+  }
+  console.log(`\nRecognized revenue by month (excludes voided/superseded schedule rows)\n${'-'.repeat(60)}`);
+  for (const r of rows) {
+    console.log(`  ${r.recognitionMonth.slice(0, 7)}  ${money(r.totalCents)}  (${r.rowCount} row${r.rowCount === 1 ? '' : 's'})`);
+  }
+  console.log(`\nTotal: ${money(rows.reduce((sum, r) => sum + r.totalCents, 0))}\n`);
+}
+
+async function reissueAudit() {
+  const rows = await request('GET', '/api/BillingSubscription/reports/reissues');
+  if (rows.length === 0) {
+    console.log('No reissued/superseded invoices.');
+    return;
+  }
+  console.log(`\n${rows.length} reissued/superseded invoice(s):\n${'-'.repeat(80)}`);
+  for (const r of rows) {
+    const chainParts = [];
+    if (r.reissuedFromInvoiceId) chainParts.push(`reissue of invoice ${r.reissuedFromInvoiceId}`);
+    if (r.supersededByInvoiceId) chainParts.push(`superseded by invoice ${r.supersededByInvoiceId}`);
+    const chain = chainParts.length ? chainParts.join(', ') : 'no linked invoice';
+    console.log(`  ${r.invoiceNumberFormatted} (id ${r.id}, sub ${r.subscriptionId}, ${r.customerName}) -- ${money(r.totalCents)} [${r.status}] -- ${chain}`);
+    if (r.internalNotes) console.log(`    notes: ${r.internalNotes.split('\n').pop()}`);
+  }
+  console.log('');
+}
+
+async function qboSync(invoiceId, args) {
+  const live = !!args.live && !args.dryRun;
+  const result = await request('POST', `/api/BillingSubscription/invoice/${invoiceId}/qbo-sync`, { live });
+  const tag = result.success ? '\x1b[32mOK\x1b[0m' : '\x1b[31mFAILED\x1b[0m';
+  console.log(`${tag} invoice ${invoiceId}: live=${result.live} outcome=${result.outcome} qboInvoiceId=${result.qboInvoiceId ?? '(none)'}`);
+  if (result.detail) console.log(`  ${result.detail}`);
+  if (!args.live) console.log('  (dry-run -- pass --live to actually call the QBO client (currently a no-op, no real credentials configured))');
+}
+
+async function anomalies() {
+  const rows = await request('GET', '/api/BillingSubscription/anomalies');
+  if (!Array.isArray(rows) || rows.length === 0) {
+    console.log('No flagged anomalies.');
+    return;
+  }
+  console.log(`\nFlagged invoices needing review (${rows.length})\n${'-'.repeat(70)}`);
+  for (const r of rows) {
+    console.log(`  [invoice ${r.id}] ${r.invoiceNumberFormatted}  ${r.customerName}  ${money(r.totalCents)}  (subscription ${r.subscriptionId})`);
+    console.log(`      ${r.anomalyReason}`);
+  }
+  console.log('');
+}
+
+async function anomalyClear(invoiceId, args) {
+  const result = await request('POST', `/api/BillingSubscription/anomaly/${invoiceId}/clear`, { note: args.note });
+  console.log(`Anomaly cleared on invoice ${result.id} by ${result.anomalyClearedBy} at ${result.anomalyClearedAt}`);
+}
+
+async function generateDocument(invoiceId, args) {
+  const type = args.type;
+  if (type !== 'invoice' && type !== 'receipt' && type !== 'quote') {
+    console.error('Usage: velaro billing-subscription document <invoiceId> --type invoice|receipt|quote [--out <path>]');
+    process.exit(1);
+  }
+
+  const [{ invoice, subscription }, paymentsResult] = await Promise.all([
+    request('GET', `/api/BillingSubscription/invoice/${invoiceId}`),
+    request('GET', `/api/BillingSubscription/invoice/${invoiceId}/payments`),
+  ]);
+
+  // A quote's default filename must not embed the real INV- number either -- that's the exact
+  // file that would get attached/emailed to a prospect, defeating the point of the QUO- reference
+  // rendered inside the PDF itself.
+  const defaultRef = type === 'quote'
+    ? `QUO-${invoice.invoiceNumber ?? invoiceId}`
+    : (invoice.invoiceNumberFormatted ?? `invoice-${invoiceId}`);
+  const outPath = args.out ?? path.resolve(process.cwd(), `${defaultRef}-${type}.pdf`);
+
+  try {
+    await generateBillingDocument({
+      invoice,
+      subscription,
+      payments: paymentsResult.payments,
+      balance: paymentsResult.balance,
+      type,
+      outPath,
+    });
+  } catch (err) {
+    console.error(`\x1b[31mFailed to generate ${type}: ${err.message}\x1b[0m`);
+    process.exit(1);
+  }
+
+  console.log(`\x1b[32mGenerated ${type} for invoice ${invoice.invoiceNumberFormatted} -> ${outPath}\x1b[0m`);
+}
+
 export const billingSubscriptionCommand = {
   command: 'billing-subscription <subcommand>',
   describe: 'Manage standalone billing subscriptions, invoices, payments, and QBO dry-run sync status',
@@ -250,10 +732,18 @@ export const billingSubscriptionCommand = {
         'net-terms':      { type: 'number' },
         'cancellation-notice-days': { type: 'number' },
         'total-cents':    { type: 'number' },
+        'recurring-amount-cents': { type: 'number', describe: 'Amount billed on EACH renewal invoice -- required before the renewal sweep will invoice this subscription' },
         notes:            { type: 'string' },
         'enable-billing': { type: 'boolean', default: false },
         'stripe-customer-id': { type: 'string' },
+        force:            { type: 'boolean', default: false, describe: 'Bypass the duplicate-subscription guard (same customer, overlapping service period)' },
       }, (args) => createSubscription(args))
+      .command('delete <id>', 'Permanently delete a subscription and its invoices -- refused if any invoice has a payment or was already sent/paid/voided', {
+        confirm: { type: 'boolean', default: false, describe: 'Required to actually delete -- without it, only prints what would be deleted' },
+      }, (args) => deleteSubscription(args.id, args))
+      .command('delete-invoice <invoiceId>', 'Permanently delete a single invoice -- refused if it has a payment or was already sent/paid/voided', {
+        confirm: { type: 'boolean', default: false, describe: 'Required to actually delete' },
+      }, (args) => deleteInvoice(args.invoiceId, 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' },
@@ -268,6 +758,9 @@ export const billingSubscriptionCommand = {
         'service-end':      { type: 'string' },
         'pre-generate':     { type: 'boolean', default: false },
         notes:              { type: 'string' },
+        'number-mode':      { type: 'string', default: 'sequential', describe: 'sequential | random-jitter' },
+        'number-max-jitter': { type: 'number', default: 10, describe: 'Max jitter (inclusive) when --number-mode random-jitter' },
+        'invoice-number':   { type: 'number', describe: 'Explicit manual override -- bypasses --number-mode entirely' },
       }, (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)' },
@@ -282,19 +775,133 @@ export const billingSubscriptionCommand = {
         reference:      { type: 'string' },
         note:           { type: 'string' },
       }, (args) => recordPayment(args.invoiceId, args))
+      .command('expiry <id>', 'Show paid-through date, expiry policy and any push-ahead override', {}, (args) => showExpiry(args.id))
+      .command('set-expiry-policy <id>', 'Set ExpiryPolicy (Default|CustomGrace|NeverExpire) and grace days (audited)', {
+        policy:       { type: 'string' },
+        'grace-days': { type: 'number' },
+        reason:       { type: 'string' },
+      }, (args) => setExpiryPolicy(args.id, args))
+      .command('send-invoice <invoiceId>', 'Email the invoice to the customer (idempotent; sets SentAt; --force resends)', {
+        force: { type: 'boolean', default: false },
+      }, (args) => sendInvoice(args.invoiceId, args))
+      .command('reminders <id>', 'Show or set payment reminders (--on/--off, --cadence "-7,-1,0,3,7,14" or "" for default, --email addr)', {
+        on:      { type: 'boolean', default: false },
+        off:     { type: 'boolean', default: false },
+        cadence: { type: 'string' },
+        email:   { type: 'string' },
+      }, (args) => reminders(args.id, args))
+      .command('push-expiry <id>', 'Hold access open until a date without changing PaidThroughAt (audited; --clear removes)', {
+        until:  { type: 'string' },
+        reason: { type: 'string' },
+        clear:  { type: 'boolean', default: false },
+      }, (args) => pushExpiry(args.id, 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('invoice-send-log <invoiceId>', 'Show the durable send/delivery audit log for an invoice -- every recipient, ACS message id, and delivered/bounced/complaint outcome', {}, (args) => invoiceSendLog(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))
       .command('set-auto-renew <id>', 'Set whether a subscription auto-renews at ServiceEndDate (data flag only -- no sweep enforces it yet)', {
         'auto-renew': { type: 'string', describe: 'true or false' },
       }, (args) => setAutoRenew(args.id, args))
+      .command('cancel <id>', 'Cancel a subscription: bill_more_periods | shutdown_accelerate | shutdown_keep_recognizing | shutdown_after_covered', {
+        mode: { type: 'string' }, 'extra-periods': { type: 'number' }, 'effective-date': { type: 'string' }, reason: { type: 'string' },
+      }, (args) => cancelSub(args.id, args))
+      .command('one-time-invoice <id>', 'Create a one-time invoice (setup/NRE/true-up)', {
+        description: { type: 'string' }, 'amount-cents': { type: 'number' }, date: { type: 'string' }, po: { type: 'string' },
+      }, (args) => oneTimeInvoice(args.id, args))
+      .command('mid-term-upgrade <id>', 'Mid-term upgrade prorated to the current period end (blocks flip-flop within 90 days)', {
+        'new-amount-cents': { type: 'number' }, 'effective-date': { type: 'string' }, reason: { type: 'string' },
+      }, (args) => midTermUpgrade(args.id, args))
       .command('schedule-cadence-change <id>', 'Schedule (or cancel) a future BillingCadence change, applied by the hourly sweep once the effective date passes', {
         cadence:        { type: 'string', describe: 'annual | monthly | quarterly' },
         'effective-at': { type: 'string', describe: 'YYYY-MM-DD the change takes effect' },
         cancel:         { type: 'boolean', default: false, describe: 'Cancel a previously-scheduled change instead of setting one' },
       }, (args) => scheduleCadenceChange(args.id, args))
-      .demandCommand(1, 'Specify a subcommand: list | get | create | attach-stripe-customer | invoice | provision-placeholder-site | recognition-schedule | payment | payments | qbo-status | renewals | set-auto-renew | schedule-cadence-change'),
+      .command('payment-correct <paymentId>', 'Correct a field on an already-recorded payment (audited, never a silent overwrite)', {
+        field:  { type: 'string', describe: 'date | amount-cents | method | reference | note' },
+        value:  { type: 'string' },
+        reason: { type: 'string' },
+      }, (args) => correctPayment(args.paymentId, args))
+      .command('payment-history <paymentId>', 'Show a payment\'s live value plus every correction ever applied', {}, (args) => paymentHistory(args.paymentId))
+      .command('invoice-correct <invoiceId>', 'Correct a field on an already-generated invoice (audited, never a silent overwrite)', {
+        field:  { type: 'string', describe: 'po-number | invoice-date | due-date | total-cents | internal-notes | service-period-start | service-period-end' },
+        value:  { type: 'string' },
+        reason: { type: 'string' },
+      }, (args) => correctInvoice(args.invoiceId, args))
+      .command('invoice-history <invoiceId>', 'Show an invoice\'s live value plus every correction ever applied', {}, (args) => invoiceHistory(args.invoiceId))
+      .command('subscription-correct <id>', 'Correct a field on an existing subscription (audited, never a silent overwrite) -- does NOT touch any invoice already generated against the old dates', {
+        field:  { type: 'string', describe: 'service-start-date|service-end-date|next-bill-date|po-number|notes|recurring-amount-cents|target-system|target-account-id|parallel-billing-mode|billing-cutover-date|external-billing-system|external-billing-account-id|auto-charge-enabled|invoice-delivery-action|invoice-recipient-emails|invoice-cc-emails|invoice-bcc-emails|contract-id|grace-period-days|auto-expire-after-grace-period|exclude-from-entitlement-sync|exclude-from-bulk-price-import' },
+        value:  { type: 'string' },
+        reason: { type: 'string' },
+        clear:  { type: 'boolean', default: false, describe: 'Explicitly blank out po-number/notes instead of providing --value' },
+        force:  { type: 'boolean', default: false, describe: 'Bypass the customer-name overlap guard when correcting service-start-date/service-end-date' },
+      }, (args) => correctSubscription(args.id, args))
+      .command('subscription-history <id>', 'Show a subscription\'s live value plus every correction ever applied', {}, (args) => subscriptionHistory(args.id))
+      .command('invoice-reissue <invoiceId>', 'Mark an invoice superseded and generate a corrected replacement (kept for audit/historical reasons, never deleted)', {
+        reason: { type: 'string' },
+        'service-period-start': { type: 'string' },
+        'service-period-end': { type: 'string' },
+        'po-number': { type: 'string' },
+        'internal-notes': { type: 'string' },
+      }, (args) => reissueInvoice(args.invoiceId, args))
+      .command('release <invoiceId>', 'Release a pending_send_gate invoice to ready_to_send (the Activate action)', {}, (args) => releaseInvoice(args.invoiceId))
+      .command('test-fire <invoiceId>', 'Send the real invoice email to internal recipients only', {}, (args) => testFireInvoice(args.invoiceId))
+      .command('issue-now <id>', 'Issue an invoice early, dated today (id = invoice id, or subscription id with --subscription)', {
+        subscription: { type: 'boolean', default: false },
+      }, (args) => issueNow(args.id, args))
+      .command('regenerate <invoiceId>', 'Reissue an unsent invoice with totals regenerated from its line items', {}, (args) => regenerateInvoice(args.invoiceId))
+      .command('materialize <subscriptionId>', 'Create the next projected invoice for a subscription now', {}, (args) => materializeInvoice(args.subscriptionId))
+      .command('upcoming', 'List invoices due to send and projected invoices in the next N days', {
+        days: { type: 'number', default: 30 },
+      }, (args) => upcomingInvoices(args))
+      .command('invoice-copy <invoiceId>', 'Clone an invoice into a new DRAFT with a new number (no payments, PDF, or sent state copied)', {
+        'service-period-start': { type: 'string' },
+        'service-period-end': { type: 'string' },
+        'invoice-date': { type: 'string' },
+        'po-number': { type: 'string' },
+      }, (args) => copyInvoice(args.invoiceId, args))
+      .command('subscription-copy <id>', 'Clone a subscription into a new INACTIVE draft (no billing, no auto-charge, new name required)', {
+        name: { type: 'string', describe: 'New customer name (required)' },
+        'service-start-date': { type: 'string' },
+        'service-end-date': { type: 'string' },
+      }, (args) => copySubscription(args.id, args))
+      .command('pause <id>', 'Pause recurring billing. The renewal job skips it and auto-resumes at --resume-date', {
+        'resume-date': { type: 'string', describe: 'ISO date to auto-resume (optional)' },
+        'invoice-behavior': { type: 'string', describe: 'skip (default) | keep_draft | void' },
+        reason: { type: 'string' },
+      }, (args) => pauseBilling(args.id, args))
+      .command('resume <id>', 'Resume paused recurring billing now', {}, (args) => resumeBilling(args.id))
+      .command('invoice-void <invoiceId>', 'Void a finalized invoice (finalized invoices cannot be deleted, only voided)', {
+        reason: { type: 'string' },
+      }, (args) => voidInvoice(args.invoiceId, args))
+      .command('credit-note <invoiceId>', 'Issue a credit note against an invoice (total or line-level; cannot exceed invoice total)', {
+        reason: { type: 'string' },
+        'amount-cents': { type: 'number' },
+        lines: { type: 'string', describe: 'lineItemId:cents,lineItemId:cents' },
+      }, (args) => creditNote(args.invoiceId, args))
+      .command('credit-notes <invoiceId>', 'List credit notes for an invoice', {}, (args) => creditNotes(args.invoiceId))
+      .command('credit-note-void <creditNoteId>', 'Void a credit note (restores the amount due)', {
+        reason: { type: 'string' },
+      }, (args) => creditNoteVoid(args.creditNoteId, args))
+      .command('renewal-sweep', 'Manually run the recurring-invoice generator now (same code the daily Hangfire sweep calls)', {}, () => runRenewalSweep())
+      .command('dunning-report', 'Show past-due invoices and grace-period status (report-only unless a subscription has AutoExpireAfterGracePeriod enabled)', {}, () => runDunningReport())
+      .command('revenue-report', 'Portfolio-wide recognized revenue by month (built on the same revenue-schedule rows recognition-schedule reads per-invoice)', {
+        'from-month': { type: 'string', describe: 'ISO date -- only recognition months on/after this date' },
+        'through-month': { type: 'string', describe: 'ISO date -- only recognition months on/before this date' },
+      }, (args) => revenueReport({ fromMonth: args.fromMonth, throughMonth: args.throughMonth }))
+      .command('reissue-audit', 'List every invoice that has been superseded (reissued) or is itself a reissue replacement', {}, () => reissueAudit())
+      .command('qbo-sync <invoiceId>', 'Sync an invoice to QuickBooks (idempotent upsert). Dry-run unless --live is passed.', {
+        live: { type: 'boolean', default: false, describe: 'Actually call the QBO client (currently NoopQboClient -- no real credentials configured, makes no real API call)' },
+      }, (args) => qboSync(args.invoiceId, args))
+      .command('anomalies', 'List invoices currently flagged for anomaly review', {}, () => anomalies())
+      .command('anomaly-clear <invoiceId>', 'Acknowledge/clear a flagged anomaly on an invoice', {
+        note: { type: 'string' },
+      }, (args) => anomalyClear(args.invoiceId, args))
+      .command('document <invoiceId>', 'Generate a polished, on-brand invoice, receipt, or quote PDF for an invoice. --type receipt is refused unless the invoice is recorded as paid in full. --type quote renders the same invoice record without a due date/INV- number, for pre-sale use.', {
+        type: { type: 'string', describe: 'invoice | receipt | quote' },
+        out:  { type: 'string', describe: 'Output file path (default: ./<InvoiceNumber>-<type>.pdf in the current directory)' },
+      }, (args) => generateDocument(args.invoiceId, args))
+      .demandCommand(1, 'Specify a subcommand: list | get | create | delete | delete-invoice | attach-stripe-customer | invoice | provision-placeholder-site | recognition-schedule | payment | payments | qbo-status | invoice-send-log | renewals | set-auto-renew | cancel | one-time-invoice | mid-term-upgrade | schedule-cadence-change | payment-correct | payment-history | invoice-correct | invoice-history | subscription-correct | subscription-history | invoice-reissue | release | test-fire | issue-now | regenerate | materialize | upcoming | renewal-sweep | dunning-report | revenue-report | reissue-audit | qbo-sync | anomalies | anomaly-clear | document | invoice-copy | subscription-copy | pause | resume | invoice-void | credit-note | credit-notes | credit-note-void | send-invoice | reminders'),
   handler: () => {},
 };