@profullstack/coinpay 0.8.0 → 0.10.0

package/bin/coinpay.js

@@ -15,8 +15,17 @@ import {
   DEFAULT_CHAINS,
 } from '../src/wallet.js';
 import { SwapClient, SwapCoins } from '../src/swap.js';
-import { createInvoice, getInvoice, listInvoices, InvoiceStatus } from '../src/invoices.js';
-import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'fs';
+import {
+  createInvoice,
+  deleteInvoice,
+  getInvoice,
+  listInvoices,
+  publishInvoice,
+  sendInvoice,
+  updateInvoice,
+  InvoiceStatus,
+} from '../src/invoices.js';
+import { readFileSync, writeFileSync, existsSync, unlinkSync, chmodSync } from 'fs';
 import { execSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
 import { homedir, hostname } from 'os';
@@ -150,6 +159,34 @@ function createUnauthenticatedClient() {
   return new CoinPayClient({ baseUrl: getBaseUrl() });
 }
 
+const BOOLEAN_FLAGS = new Set([
+  'active',
+  // finances reports / statements
+  'wait',
+  'strict',
+  'setup-token-stdin',
+  'overwrite',
+  'no-pending',
+  'liability-positive',
+  'acknowledge',
+  'plain',
+  'no-stream',
+  'hidden',
+  'active-only',
+  'debug',
+  'escrow',
+  'escrow-mode',
+  'h',
+  'help',
+  'json',
+  'no-open',
+  'no-save',
+  'show',
+  'v',
+  'version',
+  'yes',
+]);
+
 /**
  * Parse command line arguments
  */
@@ -164,16 +201,20 @@ function parseArgs(args) {
       if (eqIdx !== -1) {
         result.flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
       } else {
+        const name = arg.slice(2);
         const next = args[i + 1];
-        if (next && !next.startsWith('-')) {
-          result.flags[arg.slice(2)] = next;
+        if (BOOLEAN_FLAGS.has(name)) {
+          result.flags[name] = true;
+        } else if (next && !next.startsWith('-')) {
+          result.flags[name] = next;
           i++;
         } else {
-          result.flags[arg.slice(2)] = true;
+          result.flags[name] = true;
         }
       }
     } else if (arg.startsWith('-')) {
-      result.flags[arg.slice(1)] = args[++i] ?? true;
+      const name = arg.slice(1);
+      result.flags[name] = BOOLEAN_FLAGS.has(name) ? true : args[++i] ?? true;
     } else if (!result.command) {
       result.command = arg;
     } else if (!result.subcommand) {
@@ -186,6 +227,15 @@ function parseArgs(args) {
   return result;
 }
 
+function validateBooleanFlags(flags) {
+  for (const name of BOOLEAN_FLAGS) {
+    if (flags[name] !== undefined && flags[name] !== true) {
+      print.error('--' + name + ' does not take a value');
+      process.exit(1);
+    }
+  }
+}
+
 function parsePositiveInteger(value) {
   if (typeof value !== 'string' || !/^\d+$/.test(value.trim())) {
     return null;
@@ -232,6 +282,79 @@ function requireFlagValues(flags, names) {
   }
 }
 
+function requireSingleInvoiceId(args, subcommand) {
+  if (args.length !== 1) {
+    print.error('Usage: coinpay invoice ' + subcommand + ' <id>');
+    process.exit(1);
+  }
+  return args[0];
+}
+
+function rejectUnsupportedFlags(flags, allowed) {
+  const allowedFlags = new Set([...allowed, 'debug', 'json']);
+  const unsupported = Object.keys(flags).filter((name) => !allowedFlags.has(name));
+  if (unsupported.length > 0) {
+    print.error('Unsupported option' + (unsupported.length > 1 ? 's' : '') + ': ' +
+      unsupported.map((name) => '--' + name).join(', '));
+    process.exit(1);
+  }
+}
+
+function invoiceForOutput(data, fallbackId) {
+  const invoice = data?.invoice ?? data ?? {};
+  const output = {
+    id: invoice.id ?? fallbackId,
+    invoiceNumber: invoice.invoiceNumber ?? invoice.invoice_number,
+    businessId: invoice.businessId ?? invoice.business_id,
+    clientId: invoice.clientId ?? invoice.client_id,
+    currency: invoice.currency,
+    amount: invoice.amount,
+    cryptoCurrency: invoice.cryptoCurrency ?? invoice.crypto_currency,
+    cryptoAmount: invoice.cryptoAmount ?? invoice.crypto_amount,
+    status: invoice.status,
+    dueDate: invoice.dueDate ?? invoice.due_date,
+    notes: invoice.notes,
+    walletId: invoice.walletId ?? invoice.wallet_id,
+    merchantWalletAddress:
+      invoice.merchantWalletAddress ?? invoice.merchant_wallet_address,
+    paymentAddress: invoice.paymentAddress ?? invoice.payment_address,
+    stripeCheckoutUrl: invoice.stripeCheckoutUrl ?? invoice.stripe_checkout_url,
+    paidAt: invoice.paidAt ?? invoice.paid_at,
+    sentAt: invoice.sentAt ?? invoice.sent_at,
+    createdAt: invoice.createdAt ?? invoice.created_at,
+    updatedAt: invoice.updatedAt ?? invoice.updated_at,
+  };
+
+  return Object.fromEntries(
+    Object.entries(output).filter(([, value]) => value !== undefined)
+  );
+}
+
+function assertInvoiceUpdatesApplied(invoice, updates) {
+  if (invoice.status !== InvoiceStatus.DRAFT) {
+    throw new Error('Invoice changed state before the update completed; no draft update was confirmed');
+  }
+
+  const mismatches = Object.entries(updates).filter(([field, expected]) => {
+    const actual = invoice[field];
+    if (field === 'amount') return Number(actual) !== Number(expected);
+    if (field === 'dueDate') return String(actual || '').slice(0, 10) !== expected;
+    return actual !== expected;
+  });
+
+  if (mismatches.length > 0) {
+    throw new Error(
+      'Invoice update was not confirmed for: ' + mismatches.map(([field]) => field).join(', ')
+    );
+  }
+}
+
+function describeInvoiceRouting(invoice) {
+  const crypto = invoice.cryptoCurrency || 'unset crypto';
+  const destination = invoice.merchantWalletAddress || 'resolved payee';
+  return crypto + ' -> ' + destination;
+}
+
 /**
  * Show help
  */
@@ -266,12 +389,23 @@ ${colors.cyan}Commands:${colors.reset}
                             Route settlement to a direct address
     get <id>              Get invoice details
     list                  List invoices with optional filters
+    update <id>           Update editable fields on a draft invoice
+    publish <id>          Create payment details without emailing the client
+    send <id>             Create payment details and email the client
+    delete <id>           Permanently delete a draft invoice
+      --yes               Skip confirmation for publish/send/delete
 
   ${colors.bright}tokens${colors.reset}
     list                  List checkout tokens (--business-id, --active-only)
 
   ${colors.bright}business${colors.reset}
     create                Create a new business
+      --name <name>       Required
+      --category <slug>   Required; see: coinpay business categories
+      --description <s>   Optional
+      --webhook-url <url> Optional; enables webhooks and a generated secret
+      --webhook-secret <s>  Optional; supply your own instead
+    categories            List the valid business category slugs
     get <id>              Get business details
     list                  List businesses
     update <id>           Update business
@@ -315,6 +449,36 @@ ${colors.cyan}Commands:${colors.reset}
     escrow release <id>   Release card escrow funds
     escrow refund <id>    Refund card escrow
 
+  ${colors.bright}finances${colors.reset}       (also: coinpay money)
+    [tui]                 Live dashboard: earnings, commission, refunds,
+                            bank & credit-card feeds, ledger, invoices, escrow
+      --days <n>          Window for earnings/cashflow (7, 30, 90, 365; default 30)
+      --interval <s>      Refresh every s seconds (default 30)
+      --business-id <id>  Narrow payments to one business
+    summary               Plain-text headline numbers (--json for machines)
+    position              Debt vs income, credits vs debits, recurring bills
+                            (also: coinpay finances debt)
+    scope <id> <side>     Put an account on the business or personal books
+                            (side: business | personal | clear)
+    accounts              Linked bank and card accounts with balances
+    ledger                Bank/card transactions (--limit, --search, --category, --account)
+    connections           Linked institutions and their last sync
+    sync                  Pull fresh balances from the bank bridge (--days)
+    connect               Link SimpleFIN: token prompted without echo, or --setup-token-stdin
+    disconnect <id>       Stop syncs and drop the credential; history stays (--yes)
+    consent <id> on|off   Opt a connection into a once-daily background sync
+    backfill              Fetch a calendar period in safe chunks (--period 2026-Q2 |
+                            --from/--to, --connection, --timezone, --wait, --json)
+    jobs [get|cancel <id>] Persisted sync/report jobs; reading one costs no request
+    coverage              What part of a period was ever fetched (--period, --account)
+    report                Monthly/quarterly/custom activity report (--period 2026-08 |
+                            --from/--to; --account, --scope, --timezone, --format pdf|csv|html|json,
+                            --output <file>, --strict, --wait, --json)
+    reports [get|download|delete <id>]  Report history and downloads
+    statements import <pdf>  Keep an original bank statement (--account, --period|--from/--to)
+    statements list|get|download|reconcile|delete
+                          Statement library; reconcile takes --report --opening --closing --currency
+
   ${colors.bright}escrow${colors.reset}
     create                Create a new escrow
     get <id>              Get escrow status
@@ -482,6 +646,28 @@ async function promptYesNo(question, defaultYes = true) {
   return answer.toLowerCase().startsWith('y');
 }
 
+async function promptYesNoOnStderr(question) {
+  const answer = await new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question + ' [y/N] ', (value) => {
+      rl.close();
+      resolve(value.trim());
+    });
+  });
+  return answer.toLowerCase().startsWith('y');
+}
+
+async function confirmInvoiceMutation(flags, question) {
+  if (flags.yes === true) return true;
+  if (flags.json) {
+    throw new Error('--json requires --yes for invoice publish/send/delete');
+  }
+  if (!process.stdin.isTTY) {
+    throw new Error('Confirmation requires an interactive terminal; rerun with --yes');
+  }
+  return promptYesNoOnStderr(question);
+}
+
 /**
  * Run gpg with the passphrase on a dedicated file descriptor and the plaintext
  * on stdin, so neither ever touches the filesystem.
@@ -542,7 +728,39 @@ function hasGpg() {
 /**
  * Encrypt mnemonic with GPG and save to file
  */
+
+/**
+ * Minimum strength for a passphrase that protects an exported wallet.
+ *
+ * F5-L1-07 / L6B-05: there was no minimum at all here, while the sibling
+ * `generate-hd-wallets` backup asks for eight characters and the web wallet's
+ * create/import flow requires length >= 8 AND a strength score. A one-character
+ * passphrase was accepted on the path that produces a file an attacker can walk
+ * away with — and GPG's default KDF is far cheaper to attack on a GPU than the
+ * scrypt used by the other backup, so the passphrase is doing most of the work.
+ */
+function assertStrongPassphrase(password) {
+  const problems = [];
+  if (!password || password.length < 12) {
+    problems.push('at least 12 characters');
+  }
+  if (!/[a-z]/.test(password ?? '') || !/[A-Z]/.test(password ?? '')) {
+    problems.push('both upper and lower case');
+  }
+  if (!/\d/.test(password ?? '') && !/[^A-Za-z0-9]/.test(password ?? '')) {
+    problems.push('a digit or a symbol');
+  }
+  if (problems.length > 0) {
+    throw new Error(
+      'Passphrase too weak — this is the only thing protecting your wallet file. ' +
+      'It needs ' + problems.join(', ') + '.'
+    );
+  }
+}
+
 async function saveEncryptedWallet(mnemonic, walletId, password, walletFile) {
+  assertStrongPassphrase(password);
+
   if (!hasGpg()) {
     throw new Error('GPG is required for wallet encryption. Install: apt install gnupg');
   }
@@ -569,6 +787,22 @@ async function saveEncryptedWallet(mnemonic, walletId, password, walletFile) {
     { stdinData: content, passphrase: password }
   );
 
+  // Restrict the file gpg just created (F-L7-01 / F5-L1-02).
+  //
+  // `--output` means GPG creates the file itself, at the process umask — so it
+  // typically lands world-readable, and every other local user can copy an
+  // encrypted wallet at their leisure and attack the passphrase offline.
+  // Sibling writes in this same CLI pass `{ mode: 0o600 }`, but that option
+  // only applies when Node does the writing.
+  try {
+    chmodSync(walletFile, 0o600);
+  } catch (err) {
+    console.warn(
+      `Warning: could not restrict permissions on ${walletFile} — ` +
+      'other local users may be able to read it. ' + (err?.message ?? err)
+    );
+  }
+
   return true;
 }
 
@@ -780,9 +1014,16 @@ function printInvoiceDetails(invoice, { shareUrl } = {}) {
   if (invoice.businessId) print.info('Business: ' + invoice.businessId);
   if (invoice.clientId) print.info('Client: ' + invoice.clientId);
   if (invoice.cryptoCurrency) print.info('Crypto: ' + invoice.cryptoCurrency);
+  if (invoice.walletId) print.info('Wallet reference: ' + invoice.walletId);
+  if (invoice.merchantWalletAddress) {
+    print.info('Settlement address: ' + invoice.merchantWalletAddress);
+  }
+  if (invoice.paymentAddress) print.info('Payment address: ' + invoice.paymentAddress);
   if (invoice.dueDate) print.info('Due: ' + invoice.dueDate);
   if (invoice.notes) print.info('Notes: ' + invoice.notes);
-  if (shareUrl) print.info('Share link (opens after send): ' + shareUrl);
+  if (shareUrl) {
+    print.info('Share link: ' + shareUrl);
+  }
   console.log();
 }
 
@@ -837,15 +1078,13 @@ async function handleInvoice(subcommand, args, flags) {
         walletId: flags['wallet-id'],
         merchantWalletAddress: flags['merchant-wallet-address'],
       });
-      const shareUrl = invoice.id ? getInvoiceShareUrl(invoice.id) : undefined;
-
       if (flags.json) {
-        print.json(shareUrl ? { ...invoice, shareUrl } : invoice);
+        print.json(invoice);
         break;
       }
 
       print.success('Draft invoice created');
-      printInvoiceDetails(invoice, { shareUrl });
+      printInvoiceDetails(invoice);
       break;
     }
 
@@ -909,11 +1148,8 @@ async function handleInvoice(subcommand, args, flags) {
     }
 
     case 'get': {
-      const id = args[0];
-      if (!id) {
-        print.error('Usage: coinpay invoice get <id>');
-        process.exit(1);
-      }
+      rejectUnsupportedFlags(flags, []);
+      const id = requireSingleInvoiceId(args, 'get');
 
       const invoice = await getInvoice(client, id);
       if (flags.json) {
@@ -925,9 +1161,301 @@ async function handleInvoice(subcommand, args, flags) {
       break;
     }
 
+    case 'update': {
+      const updateFlags = [
+        'amount',
+        'currency',
+        'crypto-currency',
+        'due-date',
+        'notes',
+        'client-id',
+        'wallet-id',
+        'merchant-wallet-address',
+      ];
+      rejectUnsupportedFlags(flags, updateFlags);
+      if (flags.notes === true) {
+        print.error('--notes requires a value; use --notes= to clear existing notes');
+        process.exit(1);
+      }
+      requireFlagValues(flags, updateFlags);
+      const id = requireSingleInvoiceId(args, 'update');
+      const updates = {};
+
+      if (flags.amount !== undefined) {
+        const amount = parsePositiveAmount(flags.amount);
+        if (amount === null) {
+          print.error('--amount must be a positive decimal with at most two decimal places');
+          process.exit(1);
+        }
+        updates.amount = amount;
+      }
+
+      if (flags.currency !== undefined) {
+        if (!/^[A-Za-z]{3}$/.test(flags.currency)) {
+          print.error('--currency must be a three-letter currency code');
+          process.exit(1);
+        }
+        updates.currency = flags.currency.toUpperCase();
+      }
+
+      if (flags['crypto-currency'] !== undefined) {
+        const cryptoCurrency = flags['crypto-currency'].trim();
+        if (!cryptoCurrency) {
+          print.error('--crypto-currency must not be empty');
+          process.exit(1);
+        }
+        updates.cryptoCurrency = cryptoCurrency.toUpperCase();
+      }
+
+      if (flags['due-date'] !== undefined) {
+        if (!isValidDate(flags['due-date'])) {
+          print.error('--due-date must be a valid date in YYYY-MM-DD format');
+          process.exit(1);
+        }
+        updates.dueDate = flags['due-date'];
+      }
+
+      if (flags.notes !== undefined) updates.notes = flags.notes;
+
+      const stringUpdates = [
+        ['client-id', 'clientId'],
+        ['wallet-id', 'walletId'],
+        ['merchant-wallet-address', 'merchantWalletAddress'],
+      ];
+      for (const [flag, field] of stringUpdates) {
+        if (flags[flag] === undefined) continue;
+        const value = flags[flag].trim();
+        if (!value) {
+          print.error('--' + flag + ' must not be empty');
+          process.exit(1);
+        }
+        updates[field] = value;
+      }
+
+      if (Object.keys(updates).length === 0) {
+        print.error('Provide at least one editable field for invoice update');
+        print.info('Example: coinpay invoice update <id> --amount 125 --notes "Updated scope"');
+        process.exit(1);
+      }
+
+      const current = await getInvoice(client, id);
+      if (current.status !== InvoiceStatus.DRAFT) {
+        throw new Error('Only draft invoices can be updated (current: ' +
+          (current.status || 'unknown') + ')');
+      }
+
+      const updated = await updateInvoice(client, id, updates);
+      assertInvoiceUpdatesApplied(updated, updates);
+
+      if (flags.json) {
+        print.json(updated);
+        break;
+      }
+
+      print.success('Draft invoice updated');
+      const routingFields = ['cryptoCurrency', 'merchantWalletAddress'];
+      if (routingFields.some((field) => updates[field] !== undefined)) {
+        print.info('Payment routing: ' + describeInvoiceRouting(current) +
+          ' => ' + describeInvoiceRouting(updated));
+      }
+      if (updates.walletId !== undefined) {
+        print.info('Wallet reference: ' + (current.walletId || 'unset') +
+          ' => ' + updated.walletId);
+      }
+      printInvoiceDetails(updated);
+      break;
+    }
+
+    case 'publish': {
+      rejectUnsupportedFlags(flags, ['yes']);
+      const id = requireSingleInvoiceId(args, 'publish');
+      const current = await getInvoice(client, id);
+      const existingShareUrl = getInvoiceShareUrl(id);
+
+      if (current.status === InvoiceStatus.SENT) {
+        if (!current.paymentAddress) {
+          throw new Error(
+            'Published invoice has no active payment address; refresh it in the web app'
+          );
+        }
+        if (flags.json) {
+          print.json({
+            ...current,
+            shareUrl: existingShareUrl,
+            emailAttempted: false,
+            idempotentReplay: true,
+          });
+          break;
+        }
+        print.success('Invoice is already published; no email sent');
+        printInvoiceDetails(current, { shareUrl: existingShareUrl });
+        break;
+      }
+
+      if (current.status !== InvoiceStatus.DRAFT) {
+        throw new Error(
+          'Only draft invoices can be published (current: ' + (current.status || 'unknown') + ')'
+        );
+      }
+      if (!current.cryptoCurrency) {
+        throw new Error('Set --crypto-currency before publishing this invoice');
+      }
+
+      const label = current.invoiceNumber || current.id;
+      const confirmed = await confirmInvoiceMutation(
+        flags,
+        'Publish ' +
+          label +
+          ' for ' +
+          current.amount +
+          ' ' +
+          (current.currency || '') +
+          ' using ' +
+          current.cryptoCurrency +
+          '? This creates live payment details but does not email the client.'
+      );
+      if (!confirmed) {
+        print.info('Aborted');
+        break;
+      }
+
+      const result = await publishInvoice(client, id);
+      const published = invoiceForOutput(result, id);
+      if (
+        result?.success === false ||
+        published.status !== InvoiceStatus.SENT ||
+        !published.paymentAddress
+      ) {
+        throw new Error('Invoice publish was not confirmed by the server');
+      }
+      const shareUrl =
+        typeof result?.paymentLink === 'string'
+          ? result.paymentLink
+          : getInvoiceShareUrl(published.id);
+
+      if (flags.json) {
+        print.json({
+          ...published,
+          shareUrl,
+          emailAttempted: false,
+          idempotentReplay: result?.idempotentReplay === true,
+        });
+        break;
+      }
+
+      print.success('Invoice published; no email sent');
+      printInvoiceDetails(published, { shareUrl });
+      break;
+    }
+
+    case 'send': {
+      rejectUnsupportedFlags(flags, ['yes']);
+      const id = requireSingleInvoiceId(args, 'send');
+      const current = await getInvoice(client, id);
+      const sendable = new Set([InvoiceStatus.DRAFT, InvoiceStatus.OVERDUE]);
+      if (!sendable.has(current.status)) {
+        throw new Error('Only draft or overdue invoices can be sent (current: ' +
+          (current.status || 'unknown') + ')');
+      }
+      if (!current.cryptoCurrency) {
+        throw new Error('Set --crypto-currency before sending this invoice');
+      }
+
+      const label = current.invoiceNumber || current.id;
+      const recipient = current.clientId ? 'client ' + current.clientId : 'the configured client';
+      const amount = current.amount + ' ' + (current.currency || '');
+      const resendWarning = current.status === InvoiceStatus.OVERDUE
+        ? ' This will issue new payment details and email the client again.'
+        : ' This will create payment details and email the client.';
+      const confirmed = await confirmInvoiceMutation(
+        flags,
+        'Send ' + label + ' to ' + recipient + ' for ' + amount +
+          ' using ' + current.cryptoCurrency + '?' + resendWarning
+      );
+      if (!confirmed) {
+        print.info('Aborted');
+        break;
+      }
+
+      const result = await sendInvoice(client, id);
+      let sent = invoiceForOutput(result, id);
+      const legacySuccess = result?.success === true &&
+        !Object.prototype.hasOwnProperty.call(result, 'invoice') &&
+        sent.status === undefined;
+
+      if (legacySuccess) {
+        sent = invoiceForOutput({
+          ...current,
+          ...result,
+          status: InvoiceStatus.SENT,
+        }, id);
+      } else if (result?.success === false || sent.status !== InvoiceStatus.SENT) {
+        throw new Error('Invoice send was not confirmed by the server');
+      }
+      const shareUrl = getInvoiceShareUrl(sent.id);
+
+      if (flags.json) {
+        const delivery = {};
+        for (const field of ['emailAccepted', 'emailTrackingSaved', 'warning', 'emailError']) {
+          if (Object.prototype.hasOwnProperty.call(result ?? {}, field)) {
+            delivery[field] = result[field];
+          }
+        }
+        print.json({ ...sent, shareUrl, ...delivery });
+        break;
+      }
+
+      if (result?.emailAccepted === false) {
+        print.warn('Invoice payment link created, but the email provider did not accept the message');
+      } else if (result?.emailAccepted === true) {
+        print.success('Invoice sent; email accepted by provider');
+      } else {
+        print.success('Invoice sent; email status was not reported by the server');
+      }
+      if (legacySuccess) {
+        print.warn('The server returned limited invoice details; run coinpay invoice get ' +
+          id + ' to refresh them.');
+      }
+      printInvoiceDetails(sent, { shareUrl });
+      break;
+    }
+
+    case 'delete': {
+      rejectUnsupportedFlags(flags, ['yes']);
+      const id = requireSingleInvoiceId(args, 'delete');
+      const current = await getInvoice(client, id);
+      if (current.status !== InvoiceStatus.DRAFT) {
+        throw new Error('Only draft invoices can be deleted (current: ' +
+          (current.status || 'unknown') + ')');
+      }
+
+      const label = current.invoiceNumber || current.id;
+      const confirmed = await confirmInvoiceMutation(
+        flags,
+        'Permanently delete draft invoice ' + label + ' for ' + current.amount +
+          ' ' + (current.currency || '') + '?'
+      );
+      if (!confirmed) {
+        print.info('Aborted');
+        break;
+      }
+
+      const result = await deleteInvoice(client, id);
+      if (result?.success === false) {
+        throw new Error('Invoice deletion was not confirmed by the server');
+      }
+
+      if (flags.json) {
+        print.json({ id, deleted: true });
+        break;
+      }
+      print.success('Draft invoice deleted: ' + id);
+      break;
+    }
+
     default:
       print.error('Unknown invoice command: ' + subcommand);
-      print.info('Available: create, list, get');
+      print.info('Available: create, list, get, update, publish, send, delete');
       process.exit(1);
   }
 }
@@ -973,18 +1501,43 @@ async function handleBusiness(subcommand, args, flags) {
   
   switch (subcommand) {
     case 'create': {
-      const { name, 'webhook-url': webhookUrl } = flags;
-      
-      if (!name) {
-        print.error('Required: --name');
+      const {
+        name,
+        category,
+        description,
+        'webhook-url': webhookUrl,
+        'webhook-secret': webhookSecret,
+      } = flags;
+
+      if (!name || !category) {
+        // The API has required a category since businesses started being
+        // classified on create, and this command had no way to send one -- so it
+        // failed with "Select a valid business category" and no route to fixing
+        // it. Naming the flag here is cheaper than reading the taxonomy.
+        print.error('Required: --name <name> --category <slug>');
+        print.info('Categories: coinpay business categories');
         return;
       }
-      
-      const business = await client.createBusiness({ name, webhookUrl });
+
+      const business = await client.createBusiness({
+        name,
+        category,
+        description,
+        webhookUrl,
+        webhookSecret,
+      });
       print.success('Business created');
       print.json(business);
       break;
     }
+
+    case 'categories': {
+      // Fetched rather than hardcoded: the taxonomy is server-side and a stale
+      // copy in the CLI is how "Select a valid business category" happens twice.
+      const result = await client.listBusinessCategories();
+      print.json(result);
+      break;
+    }
     
     case 'get': {
       const businessId = args[0];
@@ -2935,7 +3488,9 @@ const MENU_COMMANDS = [
   ['logout', 'Sign out on this device'],
   ['config', 'API key & endpoint (set-key, set-url, show)'],
   ['auth', 'Merchant account (register, login, me)'],
+  ['finances', 'Live money dashboard (earnings, cards, bank feeds, ledger)'],
   ['payment', 'Payments (create, get, list, qr)'],
+  ['invoice', 'Invoices (create, list, get, update, publish, send, delete)'],
   ['tokens', 'List checkout tokens'],
   ['business', 'Businesses (create, get, list, update)'],
   ['rates', 'Exchange rates (get, list)'],
@@ -2955,7 +3510,9 @@ const MENU_COMMANDS = [
 const SUBCOMMANDS = {
   config: [['set-key', 'Set your API key'], ['set-url', 'Set custom API URL'], ['show', 'Show current configuration']],
   auth: [['register', 'Register new merchant account'], ['login', 'Login to merchant account'], ['me', 'Show current merchant info']],
+  finances: [['tui', 'Live dashboard (default)'], ['summary', 'Headline numbers as text'], ['position', 'Debt vs income, credits vs debits'], ['scope', 'Set an account business or personal'], ['accounts', 'Bank & card accounts'], ['ledger', 'Bank/card transactions'], ['connections', 'Linked institutions'], ['sync', 'Pull fresh bank data'], ['report', 'Monthly/quarterly activity report'], ['backfill', 'Fetch a calendar period'], ['statements', 'Original bank statements'], ['jobs', 'Sync and report jobs']],
   payment: [['create', 'Create a new payment'], ['get', 'Get payment details <id>'], ['list', 'List payments'], ['qr', 'Get payment QR code <id>']],
+  invoice: [['create', 'Create a draft invoice'], ['list', 'List invoices'], ['get', 'Get invoice details <id>'], ['update', 'Update a draft invoice <id>'], ['publish', 'Publish an invoice <id>'], ['send', 'Send an invoice <id>'], ['delete', 'Delete a draft invoice <id>']],
   tokens: [['list', 'List checkout tokens']],
   business: [['create', 'Create a new business'], ['get', 'Get business details <id>'], ['list', 'List businesses'], ['update', 'Update business <id>']],
   rates: [['get', 'Get exchange rate <crypto>'], ['list', 'Get all exchange rates']],
@@ -3215,13 +3772,19 @@ async function handleLogin() {
     process.exit(1);
   }
 
+  // G-1.2-10: there is no pre-filled approval link any more. A link that filled
+  // in the code turned a phishing message into one-click account takeover —
+  // anyone could start a device authorization and send the resulting link to a
+  // signed-in merchant. Entering the code by hand is what ties the approval to
+  // a terminal the person is actually sitting at.
   print.info('');
-  console.log('  To log in, open this URL on any device (e.g. your desktop) and approve:');
+  console.log('  To log in, open this URL on any device (e.g. your desktop):');
+  console.log('');
+  console.log('    ' + colors.cyan + start.verification_uri + colors.reset);
   console.log('');
-  console.log('    ' + colors.cyan + start.verification_uri_complete + colors.reset);
+  console.log('  and enter this code: ' + colors.bright + start.user_code + colors.reset);
   console.log('');
-  console.log('  …or go to ' + colors.cyan + start.verification_uri + colors.reset +
-    ' and enter code ' + colors.bright + start.user_code + colors.reset);
+  console.log(colors.yellow + '  Only enter a code your own terminal printed.' + colors.reset);
   console.log('');
   print.info('Waiting for approval… (Ctrl-C to cancel)');
 
@@ -3295,8 +3858,441 @@ async function handleWhoami(flags) {
   if (flags?.json) print.json(me);
 }
 
+
+/**
+ * Finances — the merchant's money in one place (bank feeds via SimpleFIN or
+ * Plaid, crypto and card earnings, commission paid, refunds, invoices, escrow).
+ *
+ * Needs the merchant session from `coinpay login`; the bank-data routes
+ * refuse business API keys on purpose.
+ */
+function financesClient() {
+  const cfg = loadConfig();
+  const token = process.env.COINPAY_SESSION_TOKEN || cfg.jwtToken;
+  if (!token) {
+    print.error('Finances need your merchant session, not an API key. Run: coinpay login');
+    process.exit(1);
+  }
+  return { client: new CoinPayClient({ apiKey: token, baseUrl: getBaseUrl(), timeout: 120000 }), token, baseUrl: getBaseUrl() };
+}
+
+function pad(value, width, align = 'left') {
+  const s = String(value ?? '');
+  if (s.length >= width) return s;
+  return align === 'right' ? s.padStart(width) : s.padEnd(width);
+}
+
+function printTable(rows, columns) {
+  if (!rows.length) return;
+  const widths = columns.map((c) => Math.max(c.title.length, ...rows.map((r) => String(c.render(r) ?? '').length)));
+  console.log(colors.bright + columns.map((c, i) => pad(c.title, widths[i], c.align)).join('  ') + colors.reset);
+  for (const r of rows) {
+    console.log(columns.map((c, i) => pad(c.render(r) ?? '', widths[i], c.align)).join('  '));
+  }
+}
+
+function printFinanceSummary(snapshot, fmt) {
+  const { money, ago } = fmt;
+  const e = snapshot.earnings;
+  const b = snapshot.bank;
+  const cur = b.currency || 'USD';
+  const win = `${snapshot.windowDays}d`;
+  const line = (label, value, color = '') => console.log(`  ${pad(label, 26)} ${color}${value}${colors.reset}`);
+
+  console.log(`\n${colors.bright}Earnings · ${win}${colors.reset}${snapshot.plan ? colors.cyan + '  (' + snapshot.plan.commission_percent + ' plan)' + colors.reset : ''}`);
+  line('Gross volume', money(e.grossVolumeUsd), colors.bright);
+  line('  crypto', money(e.cryptoVolumeUsd));
+  line('  cards', money(e.cardVolumeUsd));
+  line('Commission paid', `-${money(e.commissionUsd)}`, colors.yellow);
+  line('Card processor fees', `-${money(e.stripeFeesUsd)}`, colors.yellow);
+  line('Refunds', `-${money(e.refundsUsd)}`, e.refundsUsd > 0 ? colors.red : '');
+  line('Net earnings', money(e.netUsd), e.netUsd >= 0 ? colors.green : colors.red);
+  line('Paid transactions', `${e.transactions} (${e.failed} failed, ${e.failureRate}%)`);
+
+  console.log(`\n${colors.bright}Bank & cards${colors.reset}`);
+  if (!b.connections.length) {
+    console.log('  Nothing linked. Connect a bank at ' + new URL('/finances', getBaseUrl()).toString());
+  } else {
+    line('Cash & assets', money(b.assets, cur), colors.green);
+    line('Cards & loans owed', money(b.liabilities, cur), colors.red);
+    line('Net position', money(b.net, cur), b.net >= 0 ? colors.green : colors.red);
+    line(`Cash in · ${win}`, money(b.cashflow.moneyIn, cur), colors.green);
+    line(`Cash out · ${win}`, money(b.cashflow.moneyOut, cur), colors.red);
+    line('Cashflow net', money(b.cashflow.net, cur), b.cashflow.net >= 0 ? colors.green : colors.red);
+    line('Accounts', `${b.accountCount} (${b.creditCards.length} credit cards)`);
+    line('Last bank sync', `${ago(b.connections[0]?.last_synced_at)} · ${b.connections[0]?.last_sync_status || '—'}`);
+  }
+
+  console.log(`\n${colors.bright}Pipeline${colors.reset}`);
+  const inv = snapshot.invoices;
+  const esc = snapshot.escrow;
+  line('Invoices outstanding', `${money(inv.totals.outstanding)} (${inv.counts.outstanding})`, colors.yellow);
+  line('Invoices overdue', `${money(inv.totals.overdue)} (${inv.counts.overdue})`, inv.counts.overdue ? colors.red : '');
+  line(`Invoices paid · ${win}`, `${money(inv.totals.paid)} (${inv.counts.paid})`, colors.green);
+  line('Escrow held', `${money(esc.heldUsd)} (${esc.held})`, colors.cyan);
+  line(`Escrow released · ${win}`, `${money(esc.releasedUsd)} (${esc.released})`);
+  line(`Escrow refunded · ${win}`, `${money(esc.refundedUsd)} (${esc.refunded})`, esc.refunded ? colors.red : '');
+  line('Card payouts pending', money(snapshot.payout.pendingUsd));
+  line(`Card payouts paid · ${win}`, money(snapshot.payout.paidUsd), colors.green);
+
+  if (snapshot.position) printPosition(snapshot.position, fmt, { heading: true });
+
+  const failed = Object.keys(snapshot.errors);
+  if (failed.length) {
+    console.log('');
+    print.warn(`Unavailable: ${failed.map((k) => `${k} (${snapshot.errors[k]})`).join('; ')}`);
+  }
+  console.log('');
+}
+
+/**
+ * Debt against income as text.
+ *
+ * Shared by `finances summary` (as one more section) and `finances position`
+ * (on its own, with the account and recurring detail the summary omits).
+ */
+function printPosition(position, fmt, { heading = false, detail = false } = {}) {
+  const { money, pct } = fmt;
+  const cur = position.currency || 'USD';
+  const look = `${Math.round(position.observedDays ?? position.lookbackDays)}d`;
+  const line = (label, value, color = '') => console.log(`  ${pad(label, 26)} ${color}${value}${colors.reset}`);
+
+  if (heading) console.log(`\n${colors.bright}Debt & income · ${look}${colors.reset}${colors.cyan}  (${position.monthsObserved} months)${colors.reset}`);
+
+  const inc = position.income;
+  const spend = position.spending;
+  const debt = position.debt;
+  const r = position.ratios;
+
+  line('Income', `${money(inc.total, cur)}  (${money(inc.perMonth, cur)}/mo)`, colors.green);
+  line('Spending', `${money(spend.total, cur)}  (${money(spend.perMonth, cur)}/mo)`, colors.red);
+  line('Net', `${money(position.net.total, cur)}  (${money(position.net.perMonth, cur)}/mo)`, position.net.total >= 0 ? colors.green : colors.red);
+  line('Kept of income', pct(position.net.savingsRate, 1));
+  line('Gross credits / debits', `${money(inc.grossCredits, cur)} / ${money(spend.grossDebits, cur)}`);
+  line('Total owed', money(debt.total, cur), colors.red);
+  line('  revolving / instalment', `${money(debt.revolving, cur)} / ${money(debt.instalment, cur)}`);
+  line('Debt paid per month', money(debt.servicePerMonth, cur), colors.green);
+  line('Fixed bills per month', money(position.recurring.monthlyTotal, cur), colors.yellow);
+  line('Clear in', debt.payoffMonths === null ? 'never at this rate' : `${debt.payoffMonths} months (${debt.payoffDate ? debt.payoffDate.slice(0, 10) : '—'})`, debt.payoffMonths === null ? colors.red : '');
+  line('Debt to income', r.debtToIncome === null ? '—' : `${r.debtToIncome.toFixed(2)}x`, (r.debtToIncome ?? 0) > 1 ? colors.red : colors.green);
+  line('Debt service ratio', pct(r.debtServiceRatio, 1), (r.debtServiceRatio ?? 0) > 0.36 ? colors.red : colors.green);
+  line('Months of cover', r.monthsOfCover === null ? '—' : r.monthsOfCover.toFixed(1));
+  line('Card utilisation', pct(r.creditUtilisation, 0));
+
+  for (const sc of position.scopes) {
+    line(`${sc.scope} (${sc.accounts} acct)`, `${money(sc.income, cur)} in · ${money(sc.spending, cur)} out · owes ${money(sc.debt, cur)}`);
+  }
+
+  if (position.confidence.noLiabilityAccounts) {
+    console.log('');
+    print.warn('No card or loan account is linked, so the debt figures are blind.');
+  }
+  if (position.confidence.uncategorisedShare > 0.25) {
+    console.log('');
+    print.warn(`${pct(position.confidence.uncategorisedShare, 0)} of transactions are uncategorised — the income/spending split is rough.`);
+  }
+
+  if (!detail) return;
+
+  if (position.months.length) {
+    console.log(`\n${colors.bright}Month by month${colors.reset}`);
+    printTable(position.months, [
+      { title: 'Month', align: 'left', render: (m) => (m.partial ? `${m.month} *` : m.month) },
+      { title: 'Income', align: 'right', render: (m) => money(m.income, cur) },
+      { title: 'Spending', align: 'right', render: (m) => money(m.spending, cur) },
+      { title: 'Net', align: 'right', render: (m) => money(m.net, cur) },
+      { title: 'Debt paid', align: 'right', render: (m) => money(m.debtService, cur) },
+      { title: 'Rows', align: 'right', render: (m) => String(m.transactions) },
+    ]);
+    console.log(`  ${colors.cyan}* partial month${colors.reset}`);
+  }
+
+  if (debt.accounts.length) {
+    console.log(`\n${colors.bright}Owed by account${colors.reset}`);
+    printTable(debt.accounts, [
+      { title: 'Institution', align: 'left', render: (d) => d.org || '—' },
+      { title: 'Account', align: 'left', render: (d) => d.name },
+      { title: 'Kind', align: 'left', render: (d) => d.kind },
+      { title: 'Side', align: 'left', render: (d) => d.scope },
+      { title: 'Owed', align: 'right', render: (d) => money(d.owed, cur) },
+      { title: 'Share', align: 'right', render: (d) => pct(d.share, 0) },
+      { title: `Paid ${look}`, align: 'right', render: (d) => money(d.paid, cur) },
+      { title: 'Clear in', align: 'right', render: (d) => (d.payoffMonths === null ? 'never' : `${d.payoffMonths} mo`) },
+    ]);
+  }
+
+  if (position.recurring.charges.length) {
+    console.log(`\n${colors.bright}Recurring${colors.reset}  ${colors.cyan}${money(position.recurring.monthlyTotal, cur)}/mo, of which ${money(position.recurring.monthlyDebtService, cur)} is debt${colors.reset}`);
+    printTable(position.recurring.charges, [
+      { title: 'Payee', align: 'left', render: (c) => c.payee },
+      { title: 'Amount', align: 'right', render: (c) => money(c.amount, cur) },
+      { title: 'Every', align: 'left', render: (c) => c.cadence },
+      { title: 'Seen', align: 'right', render: (c) => String(c.occurrences) },
+      { title: 'Last', align: 'left', render: (c) => c.lastSeen.slice(0, 10) },
+      { title: 'Next', align: 'left', render: (c) => c.nextExpected.slice(0, 10) },
+      { title: 'Per month', align: 'right', render: (c) => money(c.monthlyEquivalent, cur) },
+      { title: 'Kind', align: 'left', render: (c) => (c.isDebtService ? 'debt' : 'bill') },
+    ]);
+  }
+  console.log('');
+}
+
+async function handleFinances(subcommand, args, flags) {
+  const parsedDays = Number.parseInt(String(flags.days ?? flags.window ?? ''), 10);
+  const days = Number.isFinite(parsedDays) && parsedDays > 0 ? parsedDays : 30;
+  const fin = await import('../src/finances.js');
+
+  switch (subcommand || 'tui') {
+    case 'tui':
+    case 'dashboard':
+    case 'watch': {
+      const { client, token, baseUrl } = financesClient();
+
+      // A document for somebody who bills by the hour. Every question it
+      // answers up front is a question nobody pays to have asked, so it
+      // defaults to the whole transaction list and a year of history.
+      if (flags.pdf || flags.report) {
+        const reportDays = Number.isFinite(parsedDays) && parsedDays > 0 ? parsedDays : 365;
+        const limit = Number.parseInt(String(flags.limit ?? ''), 10);
+        const snapshot = await fin.collectFinanceSnapshot(client, {
+          days: reportDays,
+          limit: Number.isFinite(limit) && limit > 0 ? limit : 5000,
+          businessId: flags['business-id'],
+          // Page the whole window. Asking for 5000 returns 500, and a report
+          // built on one page understates the period without saying so.
+          allTransactions: true,
+        });
+        const { buildFinanceReportHtml } = await import('../src/finances-report.js');
+        const html = buildFinanceReportHtml(snapshot, {
+          preparedFor: typeof flags.for === 'string' ? flags.for : '',
+          preparedBy: typeof flags.by === 'string' ? flags.by : '',
+          entity: typeof flags.entity === 'string' ? flags.entity : '',
+          includeTransactions: !flags['no-transactions'],
+          transactionLimit: 0,
+          title: typeof flags.title === 'string' ? flags.title : 'Financial summary',
+        });
+
+        const stamp = new Date().toISOString().slice(0, 10);
+        const base = typeof flags.pdf === 'string' && flags.pdf
+          ? String(flags.pdf).replace(/\.pdf$/i, '')
+          : `finances-${stamp}`;
+        const pdfPath = `${base}.pdf`;
+        const htmlOut = `${base}.html`;
+
+        const { writeFileSync } = await import('node:fs');
+        writeFileSync(htmlOut, html, 'utf8');
+
+        const { htmlToPdf, installHint } = await import('../src/pdf.js');
+        const result = await htmlToPdf(html, pdfPath);
+        if (result.ok) {
+          console.log(`Wrote ${pdfPath}`);
+          console.log(`       ${htmlOut}`);
+        } else {
+          // The HTML is the report. Losing the PDF is a downgrade, not a failure.
+          console.log(`Wrote ${htmlOut}`);
+          console.log('');
+          console.log('Could not render a PDF on this machine.');
+          console.log(installHint(result.tried));
+          console.log('');
+          console.log('Or open the HTML in a browser and print it to PDF.');
+        }
+        return;
+      }
+
+      const wantsText = flags.plain || flags.json || !process.stdout.isTTY || !process.stdin.isTTY;
+      if (wantsText) {
+        const snapshot = await fin.collectFinanceSnapshot(client, { days, businessId: flags['business-id'] });
+        if (flags.json) { print.json(snapshot); return; }
+        const fmt = await import('../src/finances-tui.js');
+        printFinanceSummary(snapshot, fmt);
+        return;
+      }
+      const parsedInterval = Number.parseInt(String(flags.interval ?? ''), 10);
+      const { runFinancesTui } = await import('../src/finances-tui.js');
+      await runFinancesTui({
+        client,
+        baseUrl,
+        token: flags['no-stream'] ? null : token,
+        days,
+        interval: Number.isFinite(parsedInterval) ? parsedInterval : 30,
+        businessId: flags['business-id'],
+        theme: flags.theme,
+      });
+      return;
+    }
+
+    case 'summary': {
+      const { client } = financesClient();
+      const snapshot = await fin.collectFinanceSnapshot(client, { days, businessId: flags['business-id'] });
+      if (flags.json) { print.json(snapshot); return; }
+      const fmt = await import('../src/finances-tui.js');
+      printFinanceSummary(snapshot, fmt);
+      return;
+    }
+
+    case 'position':
+    case 'debt':
+    case 'income': {
+      // Reads the summary route alone: everything on this screen comes from
+      // there, so there is no reason to fan out to eleven sources for it.
+      const { client } = financesClient();
+      const summary = await fin.getFinanceSummary(client, { days, includeHidden: Boolean(flags.hidden) });
+      const position = summary?.position;
+      if (!position) {
+        print.error('This CoinPay server does not report a debt-and-income position yet.');
+        process.exit(1);
+      }
+      if (flags.json) { print.json(position); return; }
+      const fmt = await import('../src/finances-tui.js');
+      console.log('');
+      printPosition(position, fmt, { heading: true, detail: true });
+      return;
+    }
+
+    case 'scope': {
+      // Which set of books an account belongs to. The name-derived guess is
+      // right about "Business Checking" and blind to a personal card carrying
+      // company spend, so the correction is stored and always wins.
+      const { client } = financesClient();
+      const accountId = args[0];
+      const value = (args[1] || '').toLowerCase();
+      if (!accountId) {
+        print.error('Usage: coinpay finances scope <account-id> <business|personal|clear>  (ids: coinpay finances accounts)');
+        process.exit(1);
+      }
+      const scope = value === 'clear' || value === 'auto' || value === '' ? null : value;
+      if (scope !== null && scope !== 'business' && scope !== 'personal') {
+        print.error(`Unknown scope '${value}'. Use business, personal, or clear.`);
+        process.exit(1);
+      }
+      const account = await fin.updateFinanceAccount(client, accountId, { scope });
+      if (flags.json) { print.json({ account }); return; }
+      print.success(
+        `${account.name} → ${account.effective_scope}${scope === null ? ' (derived from the name again)' : ''}`,
+      );
+      return;
+    }
+
+    case 'accounts': {
+      const { client } = financesClient();
+      const accounts = await fin.listFinanceAccounts(client, { includeHidden: Boolean(flags.hidden) });
+      if (flags.json) { print.json({ accounts }); return; }
+      if (!accounts.length) { print.info('No linked accounts. Connect a bank at ' + new URL('/finances', getBaseUrl()).toString()); return; }
+      const { money, shortDate } = await import('../src/finances-tui.js');
+      console.log('');
+      printTable(accounts, [
+        { title: 'Institution', render: (a) => a.org_name || '—' },
+        { title: 'Account', render: (a) => a.name },
+        { title: 'Kind', render: (a) => a.effective_kind || a.kind },
+        { title: 'Side', render: (a) => `${a.effective_scope || '—'}${a.scope_override ? '*' : ''}` },
+        { title: 'Balance', align: 'right', render: (a) => money(a.display_balance ?? a.balance ?? 0, a.currency || 'USD') },
+        { title: 'Available', align: 'right', render: (a) => (a.available_balance == null ? '—' : money(a.available_balance, a.currency || 'USD')) },
+        { title: 'As of', render: (a) => shortDate(a.balance_date) },
+        { title: 'Id', render: (a) => a.id },
+      ]);
+      console.log('');
+      return;
+    }
+
+    case 'ledger':
+    case 'transactions': {
+      const { client } = financesClient();
+      const parsedLimit = Number.parseInt(String(flags.limit ?? ''), 10);
+      const page = await fin.listFinanceTransactions(client, {
+        limit: Number.isFinite(parsedLimit) ? parsedLimit : 50,
+        offset: Number.parseInt(String(flags.offset ?? '0'), 10) || 0,
+        search: flags.search,
+        category: flags.category,
+        accountId: flags.account,
+        startDate: flags.start || flags.since,
+        endDate: flags.end || flags.until,
+        includePending: !flags['no-pending'],
+      });
+      if (flags.json) { print.json(page); return; }
+      if (!page.rows?.length) { print.info('No transactions match.'); return; }
+      const { money, shortDate } = await import('../src/finances-tui.js');
+      console.log('');
+      printTable(page.rows, [
+        { title: 'Date', render: (r) => shortDate(r.transacted_at || r.posted) },
+        { title: 'Account', render: (r) => `${r.org_name ? r.org_name.split(' ')[0] + ' ' : ''}${r.account_name}` },
+        { title: 'Payee / description', render: (r) => (r.payee || r.description || r.memo || '—').slice(0, 40) },
+        { title: 'Category', render: (r) => r.category || '—' },
+        { title: 'Amount', align: 'right', render: (r) => money(r.amount, r.currency || 'USD') },
+        { title: '', render: (r) => (r.pending ? 'pending' : '') },
+      ]);
+      console.log(`\n${page.rows.length} of ${page.total}` + (page.total > page.offset + page.rows.length ? `  (--offset ${page.offset + page.rows.length} for more)` : ''));
+      console.log('');
+      return;
+    }
+
+    case 'connections': {
+      const { client } = financesClient();
+      const data = await fin.listFinanceConnections(client);
+      if (flags.json) { print.json(data); return; }
+      const list = data.connections || [];
+      if (!list.length) {
+        print.info('No bank connections. Link one at ' + new URL('/finances', getBaseUrl()).toString() + (data.plaidEnabled ? ' (Plaid or SimpleFIN)' : ' (SimpleFIN)'));
+        return;
+      }
+      const { ago } = await import('../src/finances-tui.js');
+      console.log('');
+      for (const c of list) {
+        console.log(`${colors.bright}${c.label || c.id}${colors.reset}  ${colors.cyan}${c.provider}${colors.reset}  ${c.is_active ? colors.green + 'active' : colors.yellow + 'inactive'}${colors.reset}`);
+        console.log(`  id          ${c.id}`);
+        console.log(`  last sync   ${ago(c.last_synced_at)} · ${c.last_sync_status || '—'} · ${c.last_sync_accounts ?? 0} accounts / ${c.last_sync_transactions ?? 0} transactions`);
+        if (c.last_sync_error) console.log(`  ${colors.yellow}note${colors.reset}        ${c.last_sync_error}`);
+      }
+      console.log('');
+      return;
+    }
+
+    case 'sync': {
+      const { client } = financesClient();
+      print.info('Pulling fresh balances and transactions from the bank bridge…');
+      const parsedSyncDays = Number.parseInt(String(flags.days ?? ''), 10);
+      const result = await fin.syncFinances(client, {
+        days: Number.isFinite(parsedSyncDays) ? parsedSyncDays : undefined,
+        connectionId: flags.connection || flags['connection-id'],
+      });
+      if (flags.json) { print.json(result); return; }
+      const t = result.totals || {};
+      print.success(`Synced ${t.accounts ?? 0} accounts: ${t.transactionsNew ?? 0} new of ${t.transactionsSeen ?? 0} transactions (${result.status}).`);
+      for (const r of result.results || []) {
+        if (r.status === 'partial' || r.error) print.warn(`${r.connectionId || r.id || 'connection'}: ${r.error || r.status}`);
+      }
+      return;
+    }
+
+    case 'connect':
+    case 'disconnect':
+    case 'consent':
+    case 'backfill':
+    case 'jobs':
+    case 'coverage':
+    case 'report':
+    case 'reports':
+    case 'statements': {
+      const { client } = financesClient();
+      const { runFinancesCommand } = await import('../src/finances-commands.js');
+      const code = await runFinancesCommand(subcommand, args, flags, {
+        client,
+        out: (line) => console.log(line),
+        err: (line) => console.error(line),
+      });
+      if (code !== 0) process.exit(code);
+      return;
+    }
+
+    default:
+      print.error(`Unknown finances command: ${subcommand}`);
+      console.log('Usage: coinpay finances [tui|summary|accounts|ledger|connections|sync|connect|disconnect|backfill|jobs|coverage|report|reports|statements]');
+      process.exit(1);
+  }
+}
+
 async function main() {
   const { command, subcommand, args, flags } = parseArgs(process.argv.slice(2));
+  validateBooleanFlags(flags);
   
   if (flags.version || flags.v) {
     console.log(VERSION);
@@ -3331,10 +4327,12 @@ async function handleLightning(subcommand, args, flags) {
         console.error(colors.red + 'Error: --wallet-id required' + colors.reset);
         process.exit(1);
       }
-      const mnemonic = await getDecryptedMnemonic(flags);
+      // NEW-20: this used to decrypt the stored seed — prompting for the
+      // passphrase — purely to post it to the server, which validated it and
+      // threw it away. Provisioning is a custodial LNbits wallet, so nothing
+      // is derived or signed here. The seed never leaves the machine now.
       const result = await client.lightning.enableWallet({
         wallet_id: walletId,
-        mnemonic,
         business_id: flags['business-id'],
       });
       console.log(colors.green + '⚡ Lightning wallet enabled!' + colors.reset);
@@ -3543,6 +4541,17 @@ async function handleLightning(subcommand, args, flags) {
         await handleOAuth(subcommand, args, flags);
         break;
 
+      case 'finances':
+      case 'finance':
+      case 'money':
+        await handleFinances(subcommand, args, flags);
+        break;
+
+      case 'tui':
+      case 'dashboard':
+        await handleFinances('tui', [subcommand, ...args].filter(Boolean), flags);
+        break;
+
       case 'update':
       case 'upgrade':
       case 'self-update':
@@ -3560,7 +4569,8 @@ async function handleLightning(subcommand, args, flags) {
         process.exit(1);
     }
   } catch (error) {
-    print.error(error.message);
+    const code = error?.response?.code;
+    print.error(error.message + (code ? ' (' + code + ')' : ''));
     if (flags.debug) {
       console.error(error);
     }
@@ -3619,12 +4629,16 @@ async function handleOAuth(subcommand, args, flags) {
         description,
       });
 
+      // The API wraps the record: { success, client: { ..., client_secret }, warning }.
+      // Accept a bare record too so either shape prints.
+      const created = result.client ?? result;
+
       print.success('OAuth client created');
-      if (result.client_id) {
-        console.log(`\n  ${colors.bright}Client ID:${colors.reset}     ${result.client_id}`);
+      if (created.client_id) {
+        console.log(`\n  ${colors.bright}Client ID:${colors.reset}     ${created.client_id}`);
       }
-      if (result.client_secret) {
-        console.log(`  ${colors.bright}Client Secret:${colors.reset} ${colors.yellow}${result.client_secret}${colors.reset}`);
+      if (created.client_secret) {
+        console.log(`  ${colors.bright}Client Secret:${colors.reset} ${colors.yellow}${created.client_secret}${colors.reset}`);
         console.log();
         print.warn('Save the client secret — it is only shown once!');
       }
@@ -3642,13 +4656,15 @@ async function handleOAuth(subcommand, args, flags) {
       }
 
       const result = await client.getOAuthClient(id);
-
-      print.success(`OAuth Client: ${result.name || id}`);
-      if (result.client_id) print.info(`  Client ID: ${result.client_id}`);
-      if (result.description) print.info(`  Description: ${result.description}`);
-      if (result.redirect_uris) print.info(`  Redirect URIs: ${result.redirect_uris.join(', ')}`);
-      if (result.scopes) print.info(`  Scopes: ${Array.isArray(result.scopes) ? result.scopes.join(', ') : result.scopes}`);
-      if (result.created_at) print.info(`  Created: ${result.created_at}`);
+      // GET /oauth/clients/:id also wraps the record as { success, client }.
+      const found = result.client ?? result;
+
+      print.success(`OAuth Client: ${found.name || id}`);
+      if (found.client_id) print.info(`  Client ID: ${found.client_id}`);
+      if (found.description) print.info(`  Description: ${found.description}`);
+      if (found.redirect_uris) print.info(`  Redirect URIs: ${found.redirect_uris.join(', ')}`);
+      if (found.scopes) print.info(`  Scopes: ${Array.isArray(found.scopes) ? found.scopes.join(', ') : found.scopes}`);
+      if (found.created_at) print.info(`  Created: ${found.created_at}`);
 
       if (flags.json) print.json(result);
       break;