@velaro/cli 1.2.0 → 1.4.9

package/lib/commands/ops.js

@@ -1,173 +1,267 @@
-import { get, getCredentials } from '../api.js';
-import { readConfig, ENVS }   from '../config.js';
-
-// ── helpers ──────────────────────────────────────────────────────────────────
-
-function ago(dateStr) {
-  if (!dateStr) return 'unknown';
-  const diffMs = Date.now() - new Date(dateStr).getTime();
-  const mins  = Math.round(diffMs / 60000);
-  if (mins < 2)   return 'just now';
-  if (mins < 60)  return `${mins}m ago`;
-  const hrs = Math.round(mins / 60);
-  if (hrs < 24)   return `${hrs}h ago`;
-  return `${Math.round(hrs / 24)}d ago`;
-}
-
-function utcLabel(dateStr) {
-  if (!dateStr) return '';
-  const d = new Date(dateStr);
-  return d.toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
-}
-
-const OK    = '\x1b[32m✓\x1b[0m';
-const WARN  = '\x1b[33m⚠\x1b[0m';
-const ERR   = '\x1b[31m✗\x1b[0m';
-const HIGH  = '\x1b[31m[high]\x1b[0m  ';
-const MED   = '\x1b[33m[med]\x1b[0m   ';
-const LOW   = '\x1b[36m[low]\x1b[0m   ';
-
-function severityPrefix(s) {
-  if (s === 'high')   return HIGH;
-  if (s === 'medium') return MED;
-  return LOW;
-}
-
-async function pingVersion(label, base) {
-  try {
-    const res = await fetch(`${base}/Version`, { signal: AbortSignal.timeout(6000) });
-    if (!res.ok) return { label, ok: false, status: res.status };
-    const data = await res.json();
-    return { label, ok: true, version: data.version, deployedAt: data.deployedAt };
-  } catch (e) {
-    return { label, ok: false, err: e.message };
-  }
-}
-
-async function pingHealth(label, url) {
-  try {
-    const res = await fetch(url, { signal: AbortSignal.timeout(6000) });
-    return { label, ok: res.ok, status: res.status };
-  } catch (e) {
-    return { label, ok: false, err: e.message };
-  }
-}
-
-// ── ops command ───────────────────────────────────────────────────────────────
-
-export const opsCommand = {
-  command:  'ops',
-  describe: 'System health: deploy times, Hangfire, API status, and active alerts (Velaro staff only)',
-  handler:  async () => {
-    const creds = await getCredentials();
-    const isAdmin = creds.siteId === 1032;
-
-    if (!isAdmin) {
-      console.error('velaro ops is only available to Velaro staff.');
-      process.exit(1);
-    }
-
-    const cfg = readConfig();
-
-    // ── 1. Deploy versions (anonymous — both envs in parallel) ───────────────
-    const prodBase    = cfg.envs?.prod?.adminApiBase    ?? ENVS.prod.adminApiBase;
-    const stagingBase = cfg.envs?.staging?.adminApiBase ?? ENVS.staging.adminApiBase;
-
-    const [prodVer, stagingVer] = await Promise.all([
-      pingVersion('prod',    prodBase),
-      pingVersion('staging', stagingBase),
-    ]);
-
-    console.log('\n\x1b[1m── Deploy ──────────────────────────────────────────────────\x1b[0m');
-    for (const v of [prodVer, stagingVer]) {
-      if (v.ok) {
-        const sym  = OK;
-        const ver  = `\x1b[36m${v.version}\x1b[0m`;
-        const time = `${ago(v.deployedAt).padEnd(12)} (${utcLabel(v.deployedAt)})`;
-        console.log(`  ${sym}  ${v.label.padEnd(8)}  ${ver.padEnd(30)}  deployed ${time}`);
-      } else {
-        const detail = v.err ?? `HTTP ${v.status}`;
-        console.log(`  ${ERR}  ${v.label.padEnd(8)}  UNREACHABLE — ${detail}`);
-      }
-    }
-
-    // ── 2. API health (admin + messaging, both envs) ──────────────────────────
-    const prodMsgBase    = cfg.envs?.prod?.messagingApiBase    ?? ENVS.prod.messagingApiBase;
-    const stagingMsgBase = cfg.envs?.staging?.messagingApiBase ?? ENVS.staging.messagingApiBase;
-
-    const [adminProdHealth, adminStagingHealth, msgProdHealth, msgStagingHealth] = await Promise.all([
-      pingHealth('admin/prod',    `${prodBase}/Status`),
-      pingHealth('admin/staging', `${stagingBase}/Status`),
-      pingHealth('msg/prod',      `${prodMsgBase}/api/health`),
-      pingHealth('msg/staging',   `${stagingMsgBase}/api/health`),
-    ]);
-
-    console.log('\n\x1b[1m── API Health ──────────────────────────────────────────────\x1b[0m');
-    for (const h of [adminProdHealth, adminStagingHealth, msgProdHealth, msgStagingHealth]) {
-      if (h.ok) {
-        console.log(`  ${OK}  ${h.label}`);
-      } else {
-        const detail = h.err ?? `HTTP ${h.status}`;
-        console.log(`  ${ERR}  ${h.label.padEnd(20)}  ${detail}`);
-      }
-    }
-
-    // ── 3. Hangfire failed jobs ───────────────────────────────────────────────
-    console.log('\n\x1b[1m── Hangfire ────────────────────────────────────────────────\x1b[0m');
-    try {
-      const jobs = await get('/DatabaseTool/FailedJobs');
-      if (!jobs?.length) {
-        console.log(`  ${OK}  0 failed jobs`);
-      } else {
-        const sym = jobs.length >= 20 ? ERR : jobs.length >= 5 ? WARN : WARN;
-        console.log(`  ${sym}  ${jobs.length} failed job(s)`);
-        for (const j of jobs.slice(0, 5)) {
-          const when = j.failedAt ? ago(j.failedAt) : '?';
-          const name = [j.typeName, j.methodName].filter(Boolean).join('.');
-          const msg  = j.exceptionMessage?.split('\n')[0]?.slice(0, 80) ?? j.reason?.slice(0, 80) ?? '';
-          console.log(`    ${WARN}  ${name.padEnd(35)} ${when.padEnd(10)}  ${msg}`);
-        }
-        if (jobs.length > 5) console.log(`    ... and ${jobs.length - 5} more`);
-        console.log('  Open /hangfire to inspect and retry.');
-      }
-    } catch (e) {
-      console.log(`  ${WARN}  Could not load Hangfire jobs: ${e.message}`);
-    }
-
-    // ── 4. Active alerts (needs-attention via messaging API) ──────────────────
-    console.log('\n\x1b[1m── Alerts ──────────────────────────────────────────────────\x1b[0m');
-    try {
-      const res = await fetch(`${prodMsgBase}/SuperAdmin/needs-attention`, {
-        headers: {
-          Authorization:      `Bearer ${creds.velaroToken}`,
-          'X-Internal-SiteId': String(creds.siteId),
-          'Content-Type':     'application/json',
-        },
-        signal: AbortSignal.timeout(15000),
-      });
-
-      if (!res.ok) {
-        console.log(`  ${WARN}  Could not reach alerts endpoint (HTTP ${res.status})`);
-      } else {
-        const items = await res.json();
-        const alertItems = Array.isArray(items)
-          ? items.filter(i => i.type !== 'hangfire_failed') // shown above
-          : [];
-        if (!alertItems.length) {
-          console.log(`  ${OK}  Nothing needs attention`);
-        } else {
-          for (const item of alertItems) {
-            console.log(`  ${severityPrefix(item.severity)}${item.title}`);
-            if (item.recommendedFix) {
-              console.log(`         \x1b[2m${item.recommendedFix.slice(0, 100)}\x1b[0m`);
-            }
-          }
-        }
-      }
-    } catch (e) {
-      console.log(`  ${WARN}  Alerts unavailable: ${e.message}`);
-    }
-
-    console.log('\n──────────────────────────────────────────────────────────────\n');
-  },
-};
+import { get, del, post, getCredentials } from '../api.js';
+import { readConfig, ENVS }   from '../config.js';
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function ago(dateStr) {
+  if (!dateStr) return 'unknown';
+  const diffMs = Date.now() - new Date(dateStr).getTime();
+  const mins  = Math.round(diffMs / 60000);
+  if (mins < 2)   return 'just now';
+  if (mins < 60)  return `${mins}m ago`;
+  const hrs = Math.round(mins / 60);
+  if (hrs < 24)   return `${hrs}h ago`;
+  return `${Math.round(hrs / 24)}d ago`;
+}
+
+function utcLabel(dateStr) {
+  if (!dateStr) return '';
+  const d = new Date(dateStr);
+  return d.toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
+}
+
+const OK    = '\x1b[32m✓\x1b[0m';
+const WARN  = '\x1b[33m⚠\x1b[0m';
+const ERR   = '\x1b[31m✗\x1b[0m';
+const HIGH  = '\x1b[31m[high]\x1b[0m  ';
+const MED   = '\x1b[33m[med]\x1b[0m   ';
+const LOW   = '\x1b[36m[low]\x1b[0m   ';
+
+function severityPrefix(s) {
+  if (s === 'high')   return HIGH;
+  if (s === 'medium') return MED;
+  return LOW;
+}
+
+async function pingVersion(label, base) {
+  try {
+    const res = await fetch(`${base}/Version`, { signal: AbortSignal.timeout(6000) });
+    if (!res.ok) return { label, ok: false, status: res.status };
+    const data = await res.json();
+    return { label, ok: true, version: data.version, deployedAt: data.deployedAt };
+  } catch (e) {
+    return { label, ok: false, err: e.message };
+  }
+}
+
+async function pingHealth(label, url) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(6000) });
+    return { label, ok: res.ok, status: res.status };
+  } catch (e) {
+    return { label, ok: false, err: e.message };
+  }
+}
+
+// ── hangfire subcommands ──────────────────────────────────────────────────────
+
+async function requireAdmin() {
+  const creds = await getCredentials();
+  if (creds.siteId !== 1032) {
+    console.error('velaro ops is only available to Velaro staff.');
+    process.exit(1);
+  }
+  return creds;
+}
+
+const hangfireCommand = {
+  command:  'hangfire <action>',
+  describe: 'Manage Hangfire failed jobs (Velaro staff only)',
+  builder:  (yargs) => yargs
+    .positional('action', { choices: ['list', 'delete', 'retry'], describe: 'Action to perform' })
+    .option('id', { type: 'string', describe: 'Job ID (for delete/retry of a single job)' })
+    .option('all', { type: 'boolean', describe: 'Apply to all failed jobs (delete only)' }),
+  handler: async (argv) => {
+    await requireAdmin();
+    const { action, id, all } = argv;
+
+    if (action === 'list') {
+      const jobs = await get('/DatabaseTool/FailedJobs');
+      if (!jobs?.length) { console.log('No failed jobs.'); return; }
+      console.log(`\n${jobs.length} failed job(s):\n`);
+      for (const j of jobs) {
+        const name = [j.typeName, j.methodName].filter(Boolean).join('.') || '(unknown)';
+        console.log(`  #${j.id.padEnd(5)} ${name.padEnd(50)} ${j.exceptionMessage?.split('\n')[0]?.slice(0, 80) ?? ''}`);
+      }
+      console.log('');
+    } else if (action === 'delete') {
+      if (all) {
+        const res = await del('/DatabaseTool/FailedJobs');
+        console.log(`Deleted ${res.deleted} failed job(s).`);
+      } else if (id) {
+        const res = await del(`/DatabaseTool/FailedJobs/${id}`);
+        console.log(`Deleted ${res.deleted} job(s).`);
+      } else {
+        console.error('Specify --id <jobId> or --all');
+        process.exit(1);
+      }
+    } else if (action === 'retry') {
+      if (!id) { console.error('Specify --id <jobId>'); process.exit(1); }
+      const res = await post(`/DatabaseTool/FailedJobs/${id}/retry`);
+      console.log(`Requeued ${res.requeued} job(s).`);
+    }
+  },
+};
+
+// ── ops command ───────────────────────────────────────────────────────────────
+
+export const opsCommand = {
+  command:  'ops',
+  describe: 'System health: deploy times, Hangfire, API status, and active alerts (Velaro staff only)',
+  builder:  (yargs) => yargs.command(hangfireCommand),
+  handler:  async () => {
+    const creds = await getCredentials();
+    const isAdmin = creds.siteId === 1032;
+
+    if (!isAdmin) {
+      console.error('velaro ops is only available to Velaro staff.');
+      process.exit(1);
+    }
+
+    const cfg = readConfig();
+
+    // ── 1. Deploy versions (anonymous — both envs in parallel) ───────────────
+    const prodBase    = cfg.envs?.prod?.adminApiBase    ?? ENVS.prod.adminApiBase;
+    const stagingBase = cfg.envs?.staging?.adminApiBase ?? ENVS.staging.adminApiBase;
+
+    const [prodVer, stagingVer] = await Promise.all([
+      pingVersion('prod',    prodBase),
+      pingVersion('staging', stagingBase),
+    ]);
+
+    console.log('\n\x1b[1m── Deploy ──────────────────────────────────────────────────\x1b[0m');
+    for (const v of [prodVer, stagingVer]) {
+      if (v.ok) {
+        const sym  = OK;
+        const ver  = `\x1b[36m${v.version}\x1b[0m`;
+        const time = `${ago(v.deployedAt).padEnd(12)} (${utcLabel(v.deployedAt)})`;
+        console.log(`  ${sym}  ${v.label.padEnd(8)}  ${ver.padEnd(30)}  deployed ${time}`);
+      } else {
+        const detail = v.err ?? `HTTP ${v.status}`;
+        console.log(`  ${ERR}  ${v.label.padEnd(8)}  UNREACHABLE — ${detail}`);
+      }
+    }
+
+    // ── 2. API health (admin + messaging, both envs) ──────────────────────────
+    const prodMsgBase    = cfg.envs?.prod?.messagingApiBase    ?? ENVS.prod.messagingApiBase;
+    const stagingMsgBase = cfg.envs?.staging?.messagingApiBase ?? ENVS.staging.messagingApiBase;
+
+    const [adminProdHealth, adminStagingHealth, msgProdHealth, msgStagingHealth] = await Promise.all([
+      pingHealth('admin/prod',    `${prodBase}/Status`),
+      pingHealth('admin/staging', `${stagingBase}/Status`),
+      pingHealth('msg/prod',      `${prodMsgBase}/api/health`),
+      pingHealth('msg/staging',   `${stagingMsgBase}/api/health`),
+    ]);
+
+    console.log('\n\x1b[1m── API Health ──────────────────────────────────────────────\x1b[0m');
+    for (const h of [adminProdHealth, adminStagingHealth, msgProdHealth, msgStagingHealth]) {
+      if (h.ok) {
+        console.log(`  ${OK}  ${h.label}`);
+      } else {
+        const detail = h.err ?? `HTTP ${h.status}`;
+        console.log(`  ${ERR}  ${h.label.padEnd(20)}  ${detail}`);
+      }
+    }
+
+    // ── 3. Hangfire failed jobs ───────────────────────────────────────────────
+    console.log('\n\x1b[1m── Hangfire ────────────────────────────────────────────────\x1b[0m');
+    try {
+      const jobs = await get('/DatabaseTool/FailedJobs');
+      if (!jobs?.length) {
+        console.log(`  ${OK}  0 failed jobs`);
+      } else {
+        const sym = jobs.length >= 20 ? ERR : jobs.length >= 5 ? WARN : WARN;
+        console.log(`  ${sym}  ${jobs.length} failed job(s)`);
+        for (const j of jobs.slice(0, 5)) {
+          const when = j.failedAt ? ago(j.failedAt) : '?';
+          const name = [j.typeName, j.methodName].filter(Boolean).join('.');
+          const msg  = j.exceptionMessage?.split('\n')[0]?.slice(0, 80) ?? j.reason?.slice(0, 80) ?? '';
+          console.log(`    ${WARN}  ${name.padEnd(35)} ${when.padEnd(10)}  ${msg}`);
+        }
+        if (jobs.length > 5) console.log(`    ... and ${jobs.length - 5} more`);
+        console.log('  Open /hangfire to inspect and retry.');
+      }
+    } catch (e) {
+      console.log(`  ${WARN}  Could not load Hangfire jobs: ${e.message}`);
+    }
+
+    // ── 4. Active alerts (needs-attention via messaging API) ──────────────────
+    console.log('\n\x1b[1m── Alerts ──────────────────────────────────────────────────\x1b[0m');
+    try {
+      const res = await fetch(`${prodMsgBase}/SuperAdmin/needs-attention`, {
+        headers: {
+          Authorization:      `Bearer ${creds.velaroToken}`,
+          'X-Internal-SiteId': String(creds.siteId),
+          'Content-Type':     'application/json',
+        },
+        signal: AbortSignal.timeout(15000),
+      });
+
+      if (!res.ok) {
+        console.log(`  ${WARN}  Could not reach alerts endpoint (HTTP ${res.status})`);
+      } else {
+        const items = await res.json();
+        const alertItems = Array.isArray(items)
+          ? items.filter(i => i.type !== 'hangfire_failed') // shown above
+          : [];
+        if (!alertItems.length) {
+          console.log(`  ${OK}  Nothing needs attention`);
+        } else {
+          for (const item of alertItems) {
+            console.log(`  ${severityPrefix(item.severity)}${item.title}`);
+            if (item.recommendedFix) {
+              console.log(`         \x1b[2m${item.recommendedFix.slice(0, 100)}\x1b[0m`);
+            }
+          }
+        }
+      }
+    } catch (e) {
+      console.log(`  ${WARN}  Alerts unavailable: ${e.message}`);
+    }
+
+    // ── 5. Recent errors + perf + AI routing (last 1h) ───────────────────────
+    console.log('\n\x1b[1m── Recent Issues (last 1h) ─────────────────────────────────\x1b[0m');
+    try {
+      const stagingMsgBaseLocal = cfg.envs?.staging?.messagingApiBase ?? ENVS.staging.messagingApiBase;
+      const from1h = new Date(Date.now() - 3600000).toISOString();
+
+      const [errRes, perfRes] = await Promise.all([
+        fetch(`${stagingMsgBaseLocal}/superadmin/logs/search?q=level%3AERROR&from=${from1h}&take=5`, {
+          headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+          signal: AbortSignal.timeout(12000),
+        }),
+        fetch(`${stagingMsgBaseLocal}/superadmin/logs/search?q=WF-AI-ROUTE+OR+PERF-SLOW&from=${from1h}&take=20`, {
+          headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+          signal: AbortSignal.timeout(12000),
+        }),
+      ]);
+
+      const errors   = errRes.ok  ? (await errRes.json().catch(() => [])) : [];
+      const perfLogs = perfRes.ok ? (await perfRes.json().catch(() => [])) : [];
+
+      const perfCount  = perfLogs.filter(e => (e.Message ?? e.message ?? '').includes('PERF-SLOW')).length;
+      const routeCount = perfLogs.filter(e => (e.Message ?? e.message ?? '').includes('WF-AI-ROUTE')).length;
+
+      const errSym  = errors.length  ? ERR  : OK;
+      const perfSym = perfCount      ? WARN : OK;
+      const routeSym = routeCount    ? '\x1b[36m🤖\x1b[0m' : OK;
+
+      console.log(`  ${errSym}  Errors last 1h:        ${errors.length}`);
+      if (errors.length) {
+        for (const e of errors.slice(0, 3)) {
+          const msg = (e.Message ?? e.message ?? '').slice(0, 90);
+          console.log(`        \x1b[31m${msg}\x1b[0m`);
+        }
+      }
+      console.log(`  ${perfSym}  Slow responses (PERF): ${perfCount}`);
+      console.log(`  ${routeSym}  AI routing events:     ${routeCount}`);
+      if (errors.length || perfCount || routeCount) {
+        console.log(`\n  Run \x1b[36mvelaro logs diagnose\x1b[0m for full detail.`);
+      }
+    } catch (e) {
+      console.log(`  ${WARN}  Could not load recent issues: ${e.message}`);
+    }
+
+    console.log('\n──────────────────────────────────────────────────────────────\n');
+  },
+};

package/lib/commands/payment-recovery.js

@@ -0,0 +1,170 @@
+import { messagingGet, messagingPost, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+
+// ── velaro payment-recovery ─────────────────────────────────────────────────────
+// CLI surface for "Payment Recovery" -- text a contact a payment link for an
+// outstanding balance, optionally with recurring reminders until paid or marked
+// paid, view send history, and manage the per-site config. First-party AR
+// reminders ONLY -- never debt collection (docs/architecture/payment-recovery-
+// and-billing-webhooks.md). siteId is applied server-side from the vmsg-siteId
+// header (see cli/lib/api.js messagingRequest) -- never a CLI arg.
+//
+// Backend contract: server/Velaro.Messaging/Controllers/PaymentRecoveryController.cs
+//   POST   PaymentRecovery/Contacts/{contactId}/send                  { amountCents, currency?, description?, startReminderChain, cadenceHours?, maxReminders? } -> { conversationBaseId, workflowJobId, paymentLinkUrl }
+//   POST   PaymentRecovery/Conversations/{conversationBaseId}/mark-paid -> { success }
+//   GET    PaymentRecovery/Contacts/{contactId}/sends                 -> history[]
+//   GET    PaymentRecovery/Config                                     -> config | 404
+//   POST   PaymentRecovery/Config                                     -> create (409 if one already exists)
+//   PUT    PaymentRecovery/Config/{id}                                -> apply-if-present update
+
+const BOLD = '\x1b[1m';
+const DIM  = '\x1b[2m';
+const GRN  = '\x1b[32m';
+const RST  = '\x1b[0m';
+
+function fmtDate(d) {
+  return d ? new Date(d).toISOString().replace('T', ' ').slice(0, 19) : '-';
+}
+
+async function sendHandler(argv) {
+  const result = await messagingPost(`/PaymentRecovery/Contacts/${argv.contactId}/send`, {
+    amountCents:        argv.amountCents,
+    currency:           argv.currency,
+    description:        argv.description,
+    startReminderChain: !!argv.remind,
+    cadenceHours:       argv.cadenceHours,
+    maxReminders:       argv.maxReminders,
+  });
+  console.log(`\n${GRN}✓${RST} Payment reminder sent to contact ${argv.contactId}.`);
+  console.log(`  Conversation:  ${result.conversationBaseId}`);
+  console.log(`  Payment link:  ${result.paymentLinkUrl}`);
+  if (result.workflowJobId) console.log(`  Reminder job:  ${result.workflowJobId}`);
+  console.log('');
+}
+
+async function markPaidHandler(argv) {
+  await messagingPost(`/PaymentRecovery/Conversations/${argv.conversationId}/mark-paid`, {});
+  console.log(`\n${GRN}✓${RST} Conversation ${argv.conversationId} marked paid. Reminders stopped.\n`);
+}
+
+async function historyHandler(argv) {
+  const history = await messagingGet(`/PaymentRecovery/Contacts/${argv.contactId}/sends`);
+  if (!Array.isArray(history) || !history.length) {
+    console.log(`\n  No Payment Recovery sends found for contact ${argv.contactId}.\n`);
+    return;
+  }
+  console.log(`\n${BOLD}Payment Recovery send history -- contact ${argv.contactId}${RST}\n`);
+  for (const h of history) {
+    const kind = h.isInitialSend ? `${GRN}initial${RST}` : 'reminder';
+    const chain = h.workflowJobId ? `  ${DIM}chain:${h.workflowJobId}${RST}` : '';
+    console.log(`  ${fmtDate(h.sentAtUtc)}  conv:${h.conversationBaseId ?? '-'}  ${kind}${chain}`);
+  }
+  console.log('');
+}
+
+async function configGetHandler() {
+  let config;
+  try {
+    config = await messagingGet('/PaymentRecovery/Config');
+  } catch (err) {
+    if (String(err.message).includes(' 404')) {
+      console.log(`\n  No Payment Recovery config exists for this site yet. Run "velaro payment-recovery config set" to create one.\n`);
+      return;
+    }
+    throw err;
+  }
+  console.log(`\n${BOLD}Payment Recovery config${RST}  (id ${config.id})`);
+  console.log(`  Enabled:              ${config.isEnabled ? `${GRN}yes${RST}` : 'no'}`);
+  console.log(`  Default cadence:      ${config.defaultCadenceHours}h`);
+  console.log(`  Default max reminders:${config.defaultMaxReminders}`);
+  console.log(`  Message template:     ${config.defaultMessageTemplate ?? '-'}`);
+  console.log('');
+}
+
+async function configSetHandler(argv) {
+  const body = {
+    isEnabled:              argv.enabled,
+    defaultCadenceHours:    argv.cadenceHours,
+    defaultMaxReminders:    argv.maxReminders,
+    defaultMessageTemplate: argv.template,
+  };
+
+  let existing = null;
+  try {
+    existing = await messagingGet('/PaymentRecovery/Config');
+  } catch (err) {
+    if (!String(err.message).includes(' 404')) throw err;
+  }
+
+  const config = existing
+    ? await messagingPut(`/PaymentRecovery/Config/${existing.id}`, body)
+    : await messagingPost('/PaymentRecovery/Config', body);
+
+  console.log(`\n${GRN}✓${RST} Payment Recovery config ${existing ? 'updated' : 'created'} (id ${config.id}).\n`);
+}
+
+const sendCommand = {
+  command:  'send <contactId>',
+  describe: 'Text a contact a payment link for an outstanding balance, optionally with recurring reminders',
+  builder:  (y) => y
+    .positional('contactId', { describe: 'Contact ID to send the reminder to', type: 'number' })
+    .option('amount-cents',  { describe: 'Amount owed, in cents (e.g. 5000 = $50.00)', type: 'number', demandOption: true })
+    .option('currency',      { describe: 'ISO currency code (default usd)', type: 'string' })
+    .option('description',   { describe: 'What this payment is for', type: 'string' })
+    .option('remind',        { describe: 'Schedule recurring reminders until paid', type: 'boolean', default: false })
+    .option('cadence-hours', { describe: 'Hours between reminders, 1-168 (default: site config default)', type: 'number' })
+    .option('max-reminders', { describe: 'Max reminder texts, 1-10 (default: site config default)', type: 'number' }),
+  handler: runCommand(sendHandler),
+};
+
+const markPaidCommand = {
+  command:  'mark-paid <conversationId>',
+  describe: 'Mark a conversation\'s balance as paid -- stops any further reminder texts',
+  builder:  (y) => y
+    .positional('conversationId', { describe: 'Conversation base ID', type: 'number' }),
+  handler: runCommand(markPaidHandler),
+};
+
+const historyCommand = {
+  command:  'history <contactId>',
+  describe: 'Show Payment Recovery send history for a contact',
+  builder:  (y) => y
+    .positional('contactId', { describe: 'Contact ID', type: 'number' }),
+  handler: runCommand(historyHandler),
+};
+
+const configCommand = {
+  command:  'config <subcommand>',
+  describe: 'Get or set this site\'s Payment Recovery config',
+  builder:  (y) => y
+    .command({
+      command:  'get',
+      describe: 'Show this site\'s Payment Recovery config',
+      handler:  runCommand(configGetHandler),
+    })
+    .command({
+      command:  'set',
+      describe: 'Create or update this site\'s Payment Recovery config (apply-if-present -- omit a flag to leave it unchanged)',
+      builder:  (y2) => y2
+        .option('enabled',       { describe: 'Enable/disable Payment Recovery site-wide', type: 'boolean' })
+        .option('cadence-hours', { describe: 'Default hours between reminders, 1-168', type: 'number' })
+        .option('max-reminders', { describe: 'Default max reminder texts, 1-10', type: 'number' })
+        .option('template',      { describe: 'Default reminder message text, supports <<paymentLinkUrl>>', type: 'string' }),
+      handler: runCommand(configSetHandler),
+    })
+    .demandCommand(1, 'Specify a config subcommand: get | set'),
+  handler: () => {},
+};
+
+export const paymentRecoveryCommand = {
+  command:  'payment-recovery <subcommand>',
+  describe: 'Payment Recovery -- send payment reminders, manage reminder chains, and site config',
+  builder:  (y) => y
+    .command(sendCommand)
+    .command(markPaidCommand)
+    .command(historyCommand)
+    .command(configCommand)
+    .demandCommand(1, 'Specify a payment-recovery subcommand: send | mark-paid | history | config')
+    .strict(),
+  handler: () => {},
+};