@profullstack/coinpay 0.6.11 → 0.8.0

package/bin/coinpay.js

@@ -15,16 +15,34 @@ 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 { execSync } from 'child_process';
+import { execSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
-import { homedir } from 'os';
+import { homedir, hostname } from 'os';
 import { join } from 'path';
 import { tmpdir } from 'os';
 
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-const CONFIG_FILE = join(homedir(), '.coinpay.json');
-const DEFAULT_WALLET_FILE = join(homedir(), '.coinpay-wallet.gpg');
+const HOME_DIRECTORY = process.env.COINPAY_HOME || process.env.HOME || homedir();
+const CONFIG_FILE = join(HOME_DIRECTORY, '.coinpay.json');
+const DEFAULT_WALLET_FILE = join(HOME_DIRECTORY, '.coinpay-wallet.gpg');
+// Where `coinpay update|upgrade|remove|uninstall` re-invoke the installer.
+const INSTALL_URL = process.env.COINPAY_INSTALL_URL || 'https://coinpayportal.com/install.sh';
+
+// Self-manage the CLI by delegating to the installer, which owns the
+// fetch-from-GitHub / uninstall logic. Works whether the user hit the
+// shell wrapper (which also intercepts these) or the raw binary directly.
+function handleSelfManage(action) {
+  const label = action === 'remove' ? 'Removing' : 'Updating';
+  print.info(`${label} the coinpay CLI via ${INSTALL_URL}`);
+  try {
+    execSync(`curl -fsSL "${INSTALL_URL}" | sh -s -- ${action}`, { stdio: 'inherit' });
+  } catch {
+    print.error(`coinpay ${action} failed — run it manually:\n  curl -fsSL ${INSTALL_URL} | sh -s -- ${action}`);
+    process.exit(1);
+  }
+}
 
 // ANSI colors
 const colors = {
@@ -74,11 +92,11 @@ function saveConfig(config) {
  */
 function getWalletFilePath(flags = {}) {
   if (flags['wallet-file']) {
-    return flags['wallet-file'].replace(/^~/, homedir());
+    return flags['wallet-file'].replace(/^~/, HOME_DIRECTORY);
   }
   const config = loadConfig();
   if (config.walletFile) {
-    return config.walletFile.replace(/^~/, homedir());
+    return config.walletFile.replace(/^~/, HOME_DIRECTORY);
   }
   return DEFAULT_WALLET_FILE;
 }
@@ -107,13 +125,19 @@ function getBaseUrl() {
   return process.env.COINPAY_BASE_URL || config.baseUrl || 'https://coinpayportal.com/api';
 }
 
+function getInvoiceShareUrl(invoiceId) {
+  return new URL(`/now/${encodeURIComponent(invoiceId)}`, getBaseUrl()).toString();
+}
+
 /**
  * Create client instance
  */
 function createClient() {
-  const apiKey = getApiKey();
+  // An API key, or the session token from `coinpay login` (the merchant JWT is
+  // accepted by the API the same way — via its userId claim).
+  const apiKey = getApiKey() || loadConfig().jwtToken;
   if (!apiKey) {
-    print.error('API key not configured. Run: coinpay config set-key <api-key>');
+    print.error('Not authenticated. Run: coinpay login  (or coinpay config set-key <api-key>)');
     process.exit(1);
   }
   return new CoinPayClient({ apiKey, baseUrl: getBaseUrl() });
@@ -162,6 +186,52 @@ function parseArgs(args) {
   return result;
 }
 
+function parsePositiveInteger(value) {
+  if (typeof value !== 'string' || !/^\d+$/.test(value.trim())) {
+    return null;
+  }
+
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function parsePositiveAmount(value) {
+  if (typeof value !== 'string') return null;
+
+  const normalized = value.trim();
+  const match = /^(\d+)(?:\.(\d{1,2}))?$/.exec(normalized);
+  if (!match) return null;
+
+  const cents = BigInt(match[1]) * 100n + BigInt((match[2] || '').padEnd(2, '0'));
+  if (cents <= 0n || cents > BigInt(Number.MAX_SAFE_INTEGER)) return null;
+
+  return Number(cents) / 100;
+}
+
+function isValidDate(value) {
+  if (typeof value !== 'string') return false;
+
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return false;
+
+  const [, year, month, day] = match.map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return (
+    date.getUTCFullYear() === year &&
+    date.getUTCMonth() === month - 1 &&
+    date.getUTCDate() === day
+  );
+}
+
+function requireFlagValues(flags, names) {
+  for (const name of names) {
+    if (flags[name] === true) {
+      print.error('--' + name + ' requires a value');
+      process.exit(1);
+    }
+  }
+}
+
 /**
  * Show help
  */
@@ -189,6 +259,17 @@ ${colors.cyan}Commands:${colors.reset}
     list                  List payments
     qr <id>               Get payment QR code
 
+  ${colors.bright}invoice${colors.reset}
+    create                Create a draft invoice (--amount required)
+      --wallet-id <id>    Route settlement through a saved wallet
+      --merchant-wallet-address <address>
+                            Route settlement to a direct address
+    get <id>              Get invoice details
+    list                  List invoices with optional filters
+
+  ${colors.bright}tokens${colors.reset}
+    list                  List checkout tokens (--business-id, --active-only)
+
   ${colors.bright}business${colors.reset}
     create                Create a new business
     get <id>              Get business details
@@ -229,7 +310,7 @@ ${colors.cyan}Commands:${colors.reset}
     create                Create a card payment via Stripe
     get <id>              Get card payment status
     list                  List card payments
-    connect onboard <id>  Create Stripe onboarding link
+    connect onboard <id>  Create Stripe onboarding link (--country required first time)
     connect status <id>   Check Stripe account status
     escrow release <id>   Release card escrow funds
     escrow refund <id>    Refund card escrow
@@ -259,6 +340,7 @@ ${colors.cyan}Commands:${colors.reset}
     badge [did]           Get embeddable reputation badge URL
     verify <id>           Verify a credential
     revocations           List revoked credentials
+    did setup             Use existing DID or create one automatically
     did claim             Claim (auto-generate) a new DID
     did me                Show your current DID
     issuer register       Register platform issuer (--name, --domain)
@@ -270,6 +352,12 @@ ${colors.cyan}Commands:${colors.reset}
     logs <business-id>    Get webhook logs
     test <business-id>    Send test webhook
 
+  ${colors.bright}self${colors.reset}
+    update                Update the coinpay CLI to the latest version
+    upgrade               Alias for update
+    remove                Uninstall the coinpay CLI
+    uninstall             Alias for remove
+
 ${colors.cyan}Wallet Options:${colors.reset}
   --words <12|24>         Number of mnemonic words (default: 12)
   --chains <BTC,ETH,...>  Chains to derive (default: BTC,ETH,SOL,POL,BCH)
@@ -326,6 +414,12 @@ ${colors.cyan}Examples:${colors.reset}
   coinpay swap quote --from BTC --to ETH --amount 0.1
   coinpay swap create --from BTC --to ETH --amount 0.1 --settle 0x...
 
+  # Connect Stripe to a business (country is locked at Stripe account creation)
+  coinpay card connect onboard <business-id> --country CA --email merchant@example.com
+
+  # List payment tokens for a business
+  coinpay tokens list --business-id <business-id> --active-only
+
 ${colors.cyan}Environment Variables:${colors.reset}
   COINPAY_API_KEY         API key (overrides config)
   COINPAY_BASE_URL        Custom API URL
@@ -388,6 +482,51 @@ async function promptYesNo(question, defaultYes = true) {
   return answer.toLowerCase().startsWith('y');
 }
 
+/**
+ * Run gpg with the passphrase on a dedicated file descriptor and the plaintext
+ * on stdin, so neither ever touches the filesystem.
+ *
+ * This replaces a pair of temporary files in the system temp directory that
+ * held the wallet MNEMONIC and the password in plaintext for the duration of
+ * the gpg call. Three things made that dangerous:
+ *
+ *   1. The names were predictable — built from Date.now() — so another process
+ *      could poll the temp directory for `coinpay-wallet-*`.
+ *   2. Mode 0600 keeps out other OS users. It does not keep out anything
+ *      running AS the same user, which is the realistic threat on a developer
+ *      machine: a malicious npm postinstall, a compromised editor extension.
+ *   3. Overwrite-then-unlink does not reliably erase data on journalling or
+ *      copy-on-write filesystems, or on SSDs that remap blocks.
+ *
+ * The mnemonic derives every private key on every chain, so this window was
+ * worth removing rather than narrowing. Using fd 3 also keeps the passphrase
+ * off the command line, where it would be visible in `ps`.
+ */
+function runGpg(args, { stdinData, passphrase }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('gpg', args, { stdio: ['pipe', 'pipe', 'pipe', 'pipe'] });
+
+    const stdout = [];
+    let stderr = '';
+
+    child.stdout.on('data', (d) => stdout.push(d));
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve(Buffer.concat(stdout));
+      else reject(new Error(stderr.trim() || `gpg exited with code ${code}`));
+    });
+
+    const passFd = child.stdio[3];
+    passFd.on('error', () => {});
+    passFd.end(passphrase);
+
+    child.stdin.on('error', () => {});
+    if (stdinData !== undefined) child.stdin.end(stdinData);
+    else child.stdin.end();
+  });
+}
+
 /**
  * Check if gpg is available
  */
@@ -415,24 +554,22 @@ async function saveEncryptedWallet(mnemonic, walletId, password, walletFile) {
     createdAt: new Date().toISOString(),
   });
   
-  const tmpFile = join(tmpdir(), `coinpay-wallet-${Date.now()}.json`);
-  const passFile = join(tmpdir(), `coinpay-pass-${Date.now()}`);
-  
-  try {
-    writeFileSync(tmpFile, content, { mode: 0o600 });
-    writeFileSync(passFile, password, { mode: 0o600 });
-    
-    execSync(
-      `gpg --batch --yes --passphrase-file "${passFile}" --pinentry-mode loopback --symmetric --cipher-algo AES256 --output "${walletFile}" "${tmpFile}"`,
-      { stdio: ['pipe', 'pipe', 'pipe'] }
-    );
-    
-    return true;
-  } finally {
-    // Secure cleanup
-    try { writeFileSync(tmpFile, Buffer.alloc(content.length, 0)); unlinkSync(tmpFile); } catch {}
-    try { writeFileSync(passFile, Buffer.alloc(password.length, 0)); unlinkSync(passFile); } catch {}
-  }
+  // The mnemonic goes to gpg on stdin and the passphrase on fd 3. Neither is
+  // written to disk, and neither appears in the process arguments.
+  await runGpg(
+    [
+      '--batch',
+      '--yes',
+      '--passphrase-fd', '3',
+      '--pinentry-mode', 'loopback',
+      '--symmetric',
+      '--cipher-algo', 'AES256',
+      '--output', walletFile,
+    ],
+    { stdinData: content, passphrase: password }
+  );
+
+  return true;
 }
 
 /**
@@ -447,21 +584,18 @@ async function loadEncryptedWallet(password, walletFile) {
     throw new Error(`Wallet file not found: ${walletFile}`);
   }
   
-  const passFile = join(tmpdir(), `coinpay-pass-${Date.now()}`);
-  
-  try {
-    writeFileSync(passFile, password, { mode: 0o600 });
-    
-    const result = execSync(
-      `gpg --batch --yes --passphrase-file "${passFile}" --pinentry-mode loopback --decrypt "${walletFile}"`,
-      { stdio: ['pipe', 'pipe', 'pipe'] }
-    );
-    
-    const data = JSON.parse(result.toString());
-    return data;
-  } finally {
-    try { writeFileSync(passFile, Buffer.alloc(password.length, 0)); unlinkSync(passFile); } catch {}
-  }
+  const result = await runGpg(
+    [
+      '--batch',
+      '--yes',
+      '--passphrase-fd', '3',
+      '--pinentry-mode', 'loopback',
+      '--decrypt', walletFile,
+    ],
+    { passphrase: password }
+  );
+
+  return JSON.parse(result.toString());
 }
 
 /**
@@ -637,6 +771,200 @@ async function handlePayment(subcommand, args, flags) {
   }
 }
 
+function printInvoiceDetails(invoice, { shareUrl } = {}) {
+  const label = invoice.invoiceNumber || invoice.id;
+  console.log('\n' + colors.bright + label + colors.reset);
+  print.info('ID: ' + invoice.id);
+  print.info('Status: ' + (invoice.status || 'unknown'));
+  print.info('Amount: ' + invoice.amount + ' ' + (invoice.currency || ''));
+  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.dueDate) print.info('Due: ' + invoice.dueDate);
+  if (invoice.notes) print.info('Notes: ' + invoice.notes);
+  if (shareUrl) print.info('Share link (opens after send): ' + shareUrl);
+  console.log();
+}
+
+/**
+ * Invoice commands
+ */
+async function handleInvoice(subcommand, args, flags) {
+  const client = createClient();
+
+  switch (subcommand) {
+    case 'create': {
+      requireFlagValues(flags, [
+        'amount',
+        'business-id',
+        'client-id',
+        'currency',
+        'crypto-currency',
+        'due-date',
+        'notes',
+        'wallet-id',
+        'merchant-wallet-address',
+      ]);
+
+      const amount = parsePositiveAmount(flags.amount);
+      if (amount === null) {
+        print.error('--amount must be a positive decimal with at most two decimal places');
+        print.info('Example: coinpay invoice create --amount 125 --currency USD --notes "Consulting"');
+        process.exit(1);
+      }
+
+      const currency = flags.currency || 'USD';
+      if (!/^[A-Za-z]{3}$/.test(currency)) {
+        print.error('--currency must be a three-letter currency code');
+        process.exit(1);
+      }
+
+      const dueDate = flags['due-date'];
+      if (dueDate !== undefined && !isValidDate(dueDate)) {
+        print.error('--due-date must be a valid date in YYYY-MM-DD format');
+        process.exit(1);
+      }
+
+      const cryptoCurrency = flags['crypto-currency'];
+      const invoice = await createInvoice(client, {
+        businessId: flags['business-id'],
+        clientId: flags['client-id'],
+        currency: currency.toUpperCase(),
+        amount,
+        cryptoCurrency: cryptoCurrency?.toUpperCase(),
+        dueDate,
+        notes: flags.notes,
+        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);
+        break;
+      }
+
+      print.success('Draft invoice created');
+      printInvoiceDetails(invoice, { shareUrl });
+      break;
+    }
+
+    case 'list': {
+      requireFlagValues(flags, ['business-id', 'status', 'client-id', 'date-from', 'date-to']);
+
+      const status = flags.status?.toLowerCase();
+      const validStatuses = new Set(Object.values(InvoiceStatus));
+      if (status !== undefined && !validStatuses.has(status)) {
+        print.error('--status must be one of: ' + [...validStatuses].join(', '));
+        process.exit(1);
+      }
+
+      const dateFrom = flags['date-from'];
+      const dateTo = flags['date-to'];
+      if (dateFrom !== undefined && !isValidDate(dateFrom)) {
+        print.error('--date-from must be a valid date in YYYY-MM-DD format');
+        process.exit(1);
+      }
+      if (dateTo !== undefined && !isValidDate(dateTo)) {
+        print.error('--date-to must be a valid date in YYYY-MM-DD format');
+        process.exit(1);
+      }
+      if (dateFrom && dateTo && dateFrom > dateTo) {
+        print.error('--date-from must not be later than --date-to');
+        process.exit(1);
+      }
+
+      const result = await listInvoices(client, {
+        businessId: flags['business-id'],
+        status,
+        clientId: flags['client-id'],
+        dateFrom,
+        dateTo,
+      });
+
+      if (flags.json) {
+        print.json(result);
+        break;
+      }
+
+      if (result.invoices.length === 0) {
+        print.info('No invoices found');
+        break;
+      }
+
+      console.log('\n' + colors.bright + 'Invoices' + colors.reset + ' (' + (result.total ?? result.invoices.length) + ')\n');
+      for (const invoice of result.invoices) {
+        const label = invoice.invoiceNumber || invoice.id;
+        const created = invoice.createdAt ? invoice.createdAt.slice(0, 10) : '-';
+        console.log(
+          '  ' + colors.bright + label + colors.reset +
+          '  ' + (invoice.status || 'unknown') +
+          '  ' + invoice.amount + ' ' + (invoice.currency || '') +
+          '  ' + created
+        );
+        if (invoice.invoiceNumber && invoice.id) console.log('    ' + invoice.id);
+      }
+      console.log();
+      break;
+    }
+
+    case 'get': {
+      const id = args[0];
+      if (!id) {
+        print.error('Usage: coinpay invoice get <id>');
+        process.exit(1);
+      }
+
+      const invoice = await getInvoice(client, id);
+      if (flags.json) {
+        print.json(invoice);
+        break;
+      }
+
+      printInvoiceDetails(invoice);
+      break;
+    }
+
+    default:
+      print.error('Unknown invoice command: ' + subcommand);
+      print.info('Available: create, list, get');
+      process.exit(1);
+  }
+}
+
+/**
+ * Token discovery commands
+ */
+async function handleTokens(subcommand, args, flags) {
+  const client = createClient();
+
+  switch (subcommand) {
+    case 'list': {
+      const businessId = flags['business-id'];
+      const activeOnly = flags['active-only'] === true || flags.active === true;
+      const result = await client.getTokens({ businessId, activeOnly });
+
+      if (flags.json) {
+        print.json(result);
+        break;
+      }
+
+      const tokens = result.tokens || [];
+      print.info(`Payment tokens (${tokens.length})`);
+      for (const token of tokens) {
+        const chain = token.chain ? ` on ${token.chain}` : '';
+        const source = token.wallet_source ? ` (${token.wallet_source})` : '';
+        console.log(`  ${colors.bright}${token.code}${colors.reset} ${token.ticker || token.symbol}${chain}${source}`);
+      }
+      break;
+    }
+
+    default:
+      print.error(`Unknown tokens command: ${subcommand}`);
+      print.info('Available: list');
+  }
+}
+
 /**
  * Business commands
  */
@@ -1836,17 +2164,18 @@ async function handleAuth(subcommand, args, flags) {
         const client = new CoinPayClient({ apiKey: jwtToken, baseUrl: getBaseUrl() });
         const { getMe } = await import('../src/auth.js');
         const result = await getMe(client);
-        
+        const me = result?.merchant || result;
+
         print.success('Current merchant:');
-        print.info(`ID: ${result.id}`);
-        print.info(`Email: ${result.email}`);
-        if (result.name) {
-          print.info(`Name: ${result.name}`);
+        print.info(`ID: ${me.id}`);
+        print.info(`Email: ${me.email}`);
+        if (me.name) {
+          print.info(`Name: ${me.name}`);
         }
-        print.info(`Created: ${result.created_at}`);
-        
+        if (me.created_at) print.info(`Created: ${me.created_at}`);
+
         if (flags.json) {
-          print.json(result);
+          print.json(me);
         }
       } catch (error) {
         if (error.message.includes('401') || error.message.includes('403')) {
@@ -2013,15 +2342,28 @@ async function handleReputation(subcommand, args, flags) {
       const client = createClient();
 
       if (didSubcommand === 'claim') {
-        const { claimDid } = await import('../src/reputation.js');
-        const result = await claimDid(client);
+        const { claimDid, getMyDid } = await import('../src/reputation.js');
+
+        // Idempotent: a merchant can only hold one principal DID, so if one
+        // already exists just show it (exit 0) instead of erroring with
+        // "already has a principal DID". This lets automated setup (e.g.
+        // c0mpute worker onboarding) call `did claim` unconditionally.
+        let existing = null;
+        try {
+          existing = await getMyDid(client);
+        } catch {
+          existing = null; // no DID yet — fall through to claim
+        }
+
+        const result = existing?.did ? existing : await claimDid(client);
 
         if (result.did) {
-          print.success(`DID claimed: ${result.did}`);
+          print.success(`${existing?.did ? 'DID ready' : 'DID claimed'}: ${result.did}`);
           console.log(`  Public Key: ${result.public_key}`);
           console.log(`  Verified: ${result.verified}`);
         } else {
           print.error(result.error || 'Failed to claim DID');
+          process.exitCode = 1;
         }
 
         if (flags.json) print.json(result);
@@ -2061,6 +2403,31 @@ async function handleReputation(subcommand, args, flags) {
           print.info('No DID found. Run: coinpay reputation did claim');
         }
 
+        if (flags.json) print.json(result);
+      } else if (didSubcommand === 'setup') {
+        // Ensure the merchant has a payable DID, hands-free: use the existing
+        // one if there is one, otherwise create it automatically. No prompts —
+        // worker onboarding (c0mpute worker register) must never block.
+        const { getMyDid, claimDid } = await import('../src/reputation.js');
+
+        let existing = null;
+        try {
+          existing = await getMyDid(client);
+        } catch {
+          existing = null; // none yet — create below
+        }
+
+        const result = existing?.did ? existing : await claimDid(client);
+
+        if (result.did) {
+          print.success(`${existing?.did ? 'Using existing DID' : 'Created DID'}: ${result.did}`);
+          console.log(`  Public Key: ${result.public_key}`);
+          console.log(`  Verified: ${result.verified}`);
+        } else {
+          print.error(result.error || 'Failed to set up DID');
+          process.exitCode = 1;
+        }
+
         if (flags.json) print.json(result);
       } else {
         // Default: show current DID
@@ -2291,9 +2658,9 @@ async function handlePayout(subcommand, args, flags) {
 
   switch (subcommand) {
     case 'create': {
-      const amount = parseInt(flags.amount);
-      if (!amount || amount <= 0) {
-        print.error('--amount is required (in cents, e.g., 5000 for $50.00)');
+      const amount = parsePositiveInteger(flags.amount);
+      if (amount === null) {
+        print.error('--amount must be a positive integer in cents (e.g., 5000 for $50.00)');
         print.info('Example: coinpay payout create --amount 5000 --description "Weekly payout"');
         process.exit(1);
       }
@@ -2435,7 +2802,8 @@ async function handleCard(subcommand, args, flags) {
         case 'onboard': {
           if (!merchantId) {
             print.error('Merchant ID required');
-            print.info('Usage: coinpay card connect onboard <merchantId>');
+            print.info('Usage: coinpay card connect onboard <merchantId> --country <ISO-2> [--email <email>]');
+            print.info('Country is required on first onboarding (e.g. US, CA, GB, AU, DE) and is locked once the Stripe account is created.');
             return;
           }
 
@@ -2559,6 +2927,374 @@ async function handleCard(subcommand, args, flags) {
 /**
  * Main entry point
  */
+// Top-level commands offered by the interactive menu (shown when `coinpay` is
+// run with no arguments in a TTY). Self-manage commands are intentionally omitted.
+const MENU_COMMANDS = [
+  ['login', 'Log in headlessly — approve in a browser on any device'],
+  ['whoami', 'Show the signed-in merchant'],
+  ['logout', 'Sign out on this device'],
+  ['config', 'API key & endpoint (set-key, set-url, show)'],
+  ['auth', 'Merchant account (register, login, me)'],
+  ['payment', 'Payments (create, get, list, qr)'],
+  ['tokens', 'List checkout tokens'],
+  ['business', 'Businesses (create, get, list, update)'],
+  ['rates', 'Exchange rates (get, list)'],
+  ['wallet', 'Local encrypted wallet (create, import, balance, send, history…)'],
+  ['swap', 'Cross-chain swaps'],
+  ['escrow', 'Escrow & series operations'],
+  ['ln', 'Lightning wallet'],
+  ['webhook', 'Webhook management'],
+  ['payout', 'Payouts'],
+  ['card', 'Card payments & issuing'],
+  ['reputation', 'DID, credentials, receipts, issuer'],
+  ['x402', 'x402 protocol operations'],
+  ['oauth', 'OAuth operations'],
+];
+
+// Subcommands per command group (name → [[subcommand, description], …]).
+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']],
+  payment: [['create', 'Create a new payment'], ['get', 'Get payment details <id>'], ['list', 'List payments'], ['qr', 'Get payment QR code <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']],
+  wallet: [['create', 'Create a new wallet'], ['import', 'Import wallet <mnemonic>'], ['unlock', 'Decrypt wallet and show info'], ['info', 'Show wallet info'], ['addresses', 'List all addresses'], ['derive', 'Derive new address <chain>'], ['derive-missing', 'Derive missing chains'], ['balance', 'Get balance(s) [chain]'], ['send', 'Send a transaction'], ['history', 'Transaction history'], ['backup', 'Export encrypted backup'], ['delete', 'Delete local wallet file']],
+  swap: [['coins', 'List supported coins'], ['quote', 'Get swap quote'], ['create', 'Create swap transaction'], ['status', 'Check swap status <swap-id>'], ['history', 'Swap history']],
+  escrow: [['create', 'Create a new escrow'], ['get', 'Get escrow status <id>'], ['list', 'List escrows'], ['release', 'Release funds <id>'], ['refund', 'Refund funds <id>'], ['dispute', 'Open a dispute <id>'], ['events', 'Get escrow audit log <id>'], ['auth', 'Authenticate with escrow token <id>'], ['series', 'Series operations']],
+  ln: [['enable', 'Enable Lightning wallet'], ['address', 'Lightning address'], ['invoice', 'Create an invoice'], ['send', 'Send a payment'], ['balance', 'Lightning balance'], ['payments', 'List payments']],
+  webhook: [['logs', 'Get webhook logs <business-id>'], ['test', 'Send test webhook <business-id>']],
+  payout: [['create', 'Create a payout'], ['list', 'List payouts'], ['get', 'Get payout details <id>']],
+  card: [['create', 'Create a card payment'], ['get', 'Get card payment status <id>'], ['list', 'List card payments'], ['connect', 'Stripe onboarding / status'], ['escrow', 'Release / refund card escrow']],
+  reputation: [['submit', 'Submit a task receipt'], ['query', 'Query agent reputation <did>'], ['credential', 'Get credential details <id>'], ['credentials', 'List credentials [did]'], ['receipts', 'List task receipts [did]'], ['badge', 'Reputation badge URL [did]'], ['verify', 'Verify a credential <id>'], ['revocations', 'List revoked credentials'], ['did', 'DID claim / me'], ['issuer', 'Issuer register / list / rotate']],
+  x402: [
+    ['status', 'x402 status'],
+    ['test', 'x402 test'],
+    ['pay', 'pay for a URL, approving in your browser'],
+  ],
+  oauth: [['list', 'List OAuth clients'], ['create', 'Create an OAuth client'], ['get', 'Get client details <id>'], ['delete', 'Delete a client <id>']],
+};
+
+function askLine(prompt) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (answer) => { rl.close(); resolve(answer); });
+  });
+}
+
+// Re-invoke this CLI as a child so the real parser/handlers run unchanged.
+function runChild(argv) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [process.argv[1], ...argv], { stdio: 'inherit' });
+    child.on('exit', () => resolve());
+    child.on('error', () => resolve());
+  });
+}
+
+// An authenticated client (session token or API key) for the guided menu flows
+// that need to fetch your data. Returns null if not authenticated.
+function authedClientOrNull() {
+  const apiKey = getApiKey() || loadConfig().jwtToken;
+  return apiKey ? new CoinPayClient({ apiKey, baseUrl: getBaseUrl() }) : null;
+}
+
+function unwrapList(res) {
+  const list = res?.data ?? res?.businesses ?? res?.payments ?? res;
+  return Array.isArray(list) ? list : [];
+}
+
+// Fetch the merchant's businesses and let them pick one; returns a business id.
+async function pickBusiness(io) {
+  const client = authedClientOrNull();
+  if (!client) { print.error('Not signed in — run `coinpay login` first.'); return null; }
+  let list;
+  try { list = unwrapList(await client.listBusinesses()); }
+  catch (e) { print.error('Could not fetch businesses: ' + e.message); return null; }
+  if (!list.length) { print.info('No businesses yet — create one first (business → create).'); return null; }
+  if (list.length === 1) return list[0].id; // only one — no need to ask
+  return io.select({
+    message: 'Which business?',
+    choices: list.map((b) => ({ name: `${b.name || b.id}  ${colors.reset}(${b.id})`, value: b.id })),
+    pageSize: 15,
+  });
+}
+
+// Fetch payments for a business and let them pick one; returns a payment id.
+async function pickPayment(io, businessId) {
+  const client = authedClientOrNull();
+  if (!client) return null;
+  let list;
+  try { list = unwrapList(await client.listPayments({ businessId })); }
+  catch (e) { print.error('Could not fetch payments: ' + e.message); return null; }
+  if (!list.length) { print.info('No payments for that business yet.'); return null; }
+  return io.select({
+    message: 'Which payment?',
+    choices: list.map((p) => ({
+      name: `${p.id}  ${[p.amount, p.currency, p.status].filter(Boolean).join(' ')}`.trim(),
+      value: p.id,
+    })),
+    pageSize: 15,
+  });
+}
+
+// Guided interactive flows keyed by "command subcommand": fetch your data + ask
+// for inputs, then return the argv to run (or null to abort). Used by the menu.
+const GUIDED = {
+  'business get': async (io) => {
+    const id = await pickBusiness(io);
+    return id ? ['business', 'get', id] : null;
+  },
+  'business update': async (io) => {
+    const id = await pickBusiness(io);
+    if (!id) return null;
+    const name = (await io.input({ message: 'New name (blank to keep):' })).trim();
+    const url = (await io.input({ message: 'New webhook URL (blank to keep):' })).trim();
+    const argv = ['business', 'update', id];
+    if (name) argv.push('--name', name);
+    if (url) argv.push('--webhook-url', url);
+    if (argv.length === 3) { print.info('Nothing to update.'); return null; }
+    return argv;
+  },
+  'business create': async (io) => {
+    const name = (await io.input({ message: 'Business name:' })).trim();
+    if (!name) { print.error('Name is required.'); return null; }
+    const url = (await io.input({ message: 'Webhook URL (optional):' })).trim();
+    const argv = ['business', 'create', '--name', name];
+    if (url) argv.push('--webhook-url', url);
+    return argv;
+  },
+  'payment create': async (io) => {
+    const businessId = await pickBusiness(io);
+    if (!businessId) return null;
+    const amount = (await io.input({ message: 'Amount:' })).trim();
+    if (!amount) { print.error('Amount is required.'); return null; }
+    const currency = (await io.input({ message: 'Currency:', default: 'USD' })).trim() || 'USD';
+    const blockchain = await io.select({
+      message: 'Blockchain:',
+      choices: ['BTC', 'ETH', 'SOL', 'POL', 'BCH'].map((c) => ({ name: c, value: c })),
+    });
+    const description = (await io.input({ message: 'Description (optional):' })).trim();
+    const argv = ['payment', 'create', '--business-id', businessId, '--amount', amount, '--currency', currency, '--blockchain', blockchain];
+    if (description) argv.push('--description', description);
+    return argv;
+  },
+  'payment get': async (io) => {
+    const b = await pickBusiness(io);
+    if (!b) return null;
+    const p = await pickPayment(io, b);
+    return p ? ['payment', 'get', p] : null;
+  },
+  'payment qr': async (io) => {
+    const b = await pickBusiness(io);
+    if (!b) return null;
+    const p = await pickPayment(io, b);
+    return p ? ['payment', 'qr', p] : null;
+  },
+  'payment list': async (io) => {
+    const b = await pickBusiness(io);
+    return b ? ['payment', 'list', '--business-id', b] : null;
+  },
+};
+
+// Fallback menu (used only if @inquirer/prompts can't be loaded): a numbered
+// list, then a prompt for the subcommand + args.
+async function numberedMenu() {
+  console.log('');
+  console.log(`  ${colors.bright}${colors.cyan}coinpay${colors.reset}  ·  interactive menu (v${VERSION})`);
+  for (;;) {
+    console.log('');
+    MENU_COMMANDS.forEach(([name, desc], i) => {
+      const num = colors.yellow + String(i + 1).padStart(2) + colors.reset;
+      console.log(`  ${num}  ${colors.bright}${name.padEnd(11)}${colors.reset}${desc}`);
+    });
+    console.log('');
+    const answer = (await askLine('  pick a number, type a command (with args), or q to quit: ')).trim();
+    if (!answer || answer === 'q' || answer === 'quit' || answer === 'exit') break;
+
+    let argv;
+    if (/^\d+$/.test(answer)) {
+      const idx = parseInt(answer, 10) - 1;
+      if (idx < 0 || idx >= MENU_COMMANDS.length) { print.error('  invalid choice'); continue; }
+      const name = MENU_COMMANDS[idx][0];
+      const hint = (SUBCOMMANDS[name] || []).map((s) => s[0]).join(', ');
+      const rest = (await askLine(
+        `  coinpay ${colors.bright}${name}${colors.reset} ▸ subcommand + args${hint ? ` (${hint})` : ''} — Enter to list: `
+      )).trim();
+      argv = [name, ...(rest ? rest.split(/\s+/) : [])];
+    } else {
+      argv = answer.split(/\s+/);
+    }
+    console.log('');
+    await runChild(argv);
+  }
+}
+
+// Arrow-key drill-down menu (parity with the ugig CLI): pick a command, pick a
+// subcommand, fill in args, run — looping until you quit. Falls back to the
+// numbered menu if @inquirer/prompts isn't installed.
+async function runInteractiveMenu() {
+  let select, input;
+  try { ({ select, input } = await import('@inquirer/prompts')); }
+  catch { return numberedMenu(); }
+
+  const BACK = '\x00back';
+  const TYPE = '\x00type';
+  const splitArgs = (s) => (s ? s.trim().split(/\s+/).filter(Boolean) : []);
+
+  // Who's signed in (refreshed after login/logout). Shown in the menu header.
+  let me = await fetchMe();
+
+  for (;;) {
+    let cmd;
+    try {
+      cmd = await select({
+        message: `coinpay — ${me ? `signed in as ${me.email}` : 'not signed in (pick login)'} — pick a command:`,
+        choices: MENU_COMMANDS.map(([name, desc]) => ({ name: `${name.padEnd(11)} ${desc}`, value: name })),
+        pageSize: 20,
+      });
+    } catch { break; } // Ctrl-C / ESC quits
+
+    const subs = SUBCOMMANDS[cmd] || [];
+    let argv;
+    if (subs.length) {
+      let sub;
+      try {
+        sub = await select({
+          message: `coinpay ${cmd} — pick a subcommand:`,
+          choices: [
+            ...subs.map(([n, d]) => ({ name: `${n.padEnd(14)} ${d || ''}`.trimEnd(), value: n })),
+            { name: '✎ type subcommand + args…', value: TYPE },
+            { name: '↩ back', value: BACK },
+          ],
+          pageSize: 20,
+        });
+      } catch { continue; }
+      if (sub === BACK) continue;
+      if (sub === TYPE) {
+        let line; try { line = await input({ message: `coinpay ${cmd}` }); } catch { continue; }
+        argv = [cmd, ...splitArgs(line)];
+      } else if (GUIDED[`${cmd} ${sub}`]) {
+        // Guided flow: fetch your data + ask for the inputs, then run.
+        let g; try { g = await GUIDED[`${cmd} ${sub}`]({ select, input }); } catch { continue; }
+        if (!g) continue;
+        argv = g;
+      } else {
+        let extra; try { extra = await input({ message: `args/flags for 'coinpay ${cmd} ${sub}' (optional):` }); } catch { continue; }
+        argv = [cmd, sub, ...splitArgs(extra)];
+      }
+    } else {
+      let line; try { line = await input({ message: `coinpay ${cmd}` }); } catch { continue; }
+      argv = [cmd, ...splitArgs(line)];
+    }
+    console.log('');
+    await runChild(argv);
+    console.log('');
+    // login/logout change who's signed in — refresh the header.
+    if (argv[0] === 'login' || argv[0] === 'logout') me = await fetchMe();
+  }
+}
+
+// Headless login: ask the server for a device code, show a URL to approve on any
+// device, and poll until a merchant session token is minted and stored. No
+// password on this machine — works over SSH / on a server.
+async function handleLogin() {
+  const cfg = loadConfig();
+  const base = (cfg.baseUrl || 'https://coinpayportal.com/api').replace(/\/$/, '');
+
+  let start;
+  try {
+    const res = await fetch(`${base}/cli-auth/start`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ client_name: hostname() }),
+    });
+    if (!res.ok) throw new Error(`server returned ${res.status}`);
+    start = await res.json();
+  } catch (err) {
+    print.error(`Couldn't start login: ${err.message}`);
+    process.exit(1);
+  }
+
+  print.info('');
+  console.log('  To log in, open this URL on any device (e.g. your desktop) and approve:');
+  console.log('');
+  console.log('    ' + colors.cyan + start.verification_uri_complete + 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('');
+  print.info('Waiting for approval… (Ctrl-C to cancel)');
+
+  const deadline = Date.now() + (start.expires_in || 600) * 1000;
+  const intervalMs = Math.max(1, start.interval || 5) * 1000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, intervalMs));
+    let data = {};
+    try {
+      const res = await fetch(`${base}/cli-auth/poll`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ device_code: start.device_code }),
+      });
+      if (res.status === 202) continue; // authorization_pending
+      data = await res.json().catch(() => ({}));
+    } catch {
+      continue; // transient network error — keep polling
+    }
+    if (data.status === 'complete' && data.token) {
+      cfg.jwtToken = data.token;
+      saveConfig(cfg);
+      const me = await fetchMe();
+      print.success(me ? `Logged in as ${meLabel(me)}` : 'Logged in! Session saved to ' + CONFIG_FILE);
+      return;
+    }
+    if (data.status === 'denied') { print.error('Request denied.'); process.exit(1); }
+    if (data.status === 'expired') { print.error('Login request expired — run `coinpay login` again.'); process.exit(1); }
+  }
+  print.error('Timed out waiting for approval.');
+  process.exit(1);
+}
+
+function handleLogout() {
+  const cfg = loadConfig();
+  delete cfg.jwtToken;
+  saveConfig(cfg);
+  print.success('Logged out — session removed from ' + CONFIG_FILE);
+}
+
+// Fetch the signed-in merchant (via the stored session token), or null if not
+// logged in / the token is stale. Used to greet after login, for `whoami`, and
+// to show who you are in the interactive menu.
+async function fetchMe() {
+  const cfg = loadConfig();
+  if (!cfg.jwtToken) return null;
+  try {
+    const client = new CoinPayClient({ apiKey: cfg.jwtToken, baseUrl: getBaseUrl() });
+    const { getMe } = await import('../src/auth.js');
+    const result = await getMe(client);
+    return result?.merchant || result || null;
+  } catch {
+    return null;
+  }
+}
+
+function meLabel(me) {
+  if (!me) return null;
+  return me.name ? `${me.name} <${me.email}>` : me.email;
+}
+
+async function handleWhoami(flags) {
+  const me = await fetchMe();
+  if (!me) {
+    print.error('Not signed in. Run: coinpay login');
+    process.exitCode = 1;
+    return;
+  }
+  print.success(`Signed in as ${meLabel(me)}`);
+  if (me.id) print.info(`Merchant ID: ${me.id}`);
+  if (flags?.json) print.json(me);
+}
+
 async function main() {
   const { command, subcommand, args, flags } = parseArgs(process.argv.slice(2));
   
@@ -2567,7 +3303,18 @@ async function main() {
     return;
   }
   
-  if (flags.help || flags.h || !command) {
+  if (flags.help || flags.h) {
+    showHelp();
+    return;
+  }
+
+  if (!command) {
+    // No command in an interactive terminal → browse-and-run menu instead of a
+    // bare help dump. Piped/non-TTY invocations keep printing help.
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      await runInteractiveMenu();
+      return;
+    }
     showHelp();
     return;
   }
@@ -2715,6 +3462,18 @@ async function handleLightning(subcommand, args, flags) {
 }
 
     switch (command) {
+      case 'login':
+        await handleLogin();
+        break;
+
+      case 'logout':
+        handleLogout();
+        break;
+
+      case 'whoami':
+        await handleWhoami(flags);
+        break;
+
       case 'config':
         await handleConfig(subcommand, args);
         break;
@@ -2722,6 +3481,14 @@ async function handleLightning(subcommand, args, flags) {
       case 'payment':
         await handlePayment(subcommand, args, flags);
         break;
+
+      case 'invoice':
+        await handleInvoice(subcommand, args, flags);
+        break;
+
+      case 'tokens':
+        await handleTokens(subcommand, args, flags);
+        break;
         
       case 'business':
         await handleBusiness(subcommand, args, flags);
@@ -2775,7 +3542,18 @@ async function handleLightning(subcommand, args, flags) {
       case 'oauth':
         await handleOAuth(subcommand, args, flags);
         break;
-        
+
+      case 'update':
+      case 'upgrade':
+      case 'self-update':
+        handleSelfManage('update');
+        break;
+
+      case 'remove':
+      case 'uninstall':
+        handleSelfManage('remove');
+        break;
+
       default:
         print.error(`Unknown command: ${command}`);
         showHelp();
@@ -2896,6 +3674,108 @@ async function handleOAuth(subcommand, args, flags) {
   }
 }
 
+/**
+ * Open the platform's browser at a URL.
+ *
+ * Failure is not fatal: the URL is printed either way, so a headless box or an
+ * unusual desktop just means the user opens it themselves.
+ */
+async function openInBrowser(url) {
+  const { spawn } = await import('node:child_process');
+  const command =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    spawn(command, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' })
+      .on('error', () => {})
+      .unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `coinpay x402 pay <url>` — fetch a paid resource, approving in the browser.
+ *
+ * The terminal cannot sign: browser wallets expose themselves to pages, not to
+ * processes. So this serves a one-shot approval page on loopback, opens it,
+ * and waits for the signed `X-PAYMENT` header to come back before retrying the
+ * original request.
+ */
+async function handleX402Pay(args, flags) {
+  const target = args[0] || flags.url;
+  if (!target) {
+    print.error('Usage: coinpay x402 pay <url>');
+    process.exit(1);
+  }
+
+  const { startPaymentServer } = await import('../src/x402-pay-server.js');
+
+  print.info(`Fetching ${target}`);
+  const first = await fetch(target);
+
+  if (first.status !== 402) {
+    // Nothing to pay for. Still the useful answer, so print it rather than
+    // treating "free" as an error.
+    print.success(`No payment required (HTTP ${first.status})`);
+    const body = await first.text();
+    if (flags.output) {
+      await (await import('node:fs/promises')).writeFile(flags.output, body);
+      print.info(`Wrote ${flags.output}`);
+    } else {
+      console.log(body);
+    }
+    return;
+  }
+
+  let paymentRequired;
+  try {
+    paymentRequired = await first.clone().json();
+  } catch {
+    print.error('Resource returned 402 but its body was not valid x402 JSON');
+    process.exit(1);
+  }
+
+  const server = await startPaymentServer({
+    paymentRequired,
+    resourceUrl: target,
+    port: flags.port ? Number(flags.port) : 0,
+  });
+
+  try {
+    if (flags['no-open']) {
+      print.info(`Open this to approve:\n  ${server.url}`);
+    } else {
+      await openInBrowser(server.url);
+      print.info(`Approve in your browser:\n  ${server.url}`);
+    }
+    print.info('Waiting for approval…');
+
+    const header = await server.waitForPayment();
+    print.success('Payment approved');
+
+    const paid = await fetch(target, { headers: { 'X-PAYMENT': header } });
+    if (paid.status === 402) {
+      // Never sign again automatically — a second 402 means the payment was
+      // refused rather than missing, and retrying spends the user's money on a
+      // resource that just said no.
+      print.error('Payment was rejected by the resource. Not retrying.');
+      process.exit(1);
+    }
+
+    const body = await paid.text();
+    if (flags.output) {
+      await (await import('node:fs/promises')).writeFile(flags.output, body);
+      print.success(`HTTP ${paid.status} — wrote ${flags.output}`);
+    } else {
+      print.success(`HTTP ${paid.status}`);
+      console.log(body);
+    }
+  } finally {
+    await server.close();
+  }
+}
+
 /**
  * Handle x402 commands
  */
@@ -2911,16 +3791,23 @@ Usage: coinpay x402 <command> [options]
 Commands:
   status          Check x402 facilitator status
   test            Test x402 flow against an endpoint
+  pay <url>       Fetch a paid URL, approving payment in your browser
 
 Options:
   --url <url>     Endpoint URL for testing
   --network <net> Network: base, ethereum, polygon (default: base)
   --amount <amt>  Amount in USDC smallest unit (default: 1000000 = 1 USDC)
+  --output <file> (pay) Write the paid response body to a file
+  --port <n>      (pay) Port for the local approval page (default: random)
+  --no-open       (pay) Print the URL instead of opening a browser
 `);
     return;
   }
 
   switch (subcommand) {
+    case 'pay':
+      return handleX402Pay(args, flags);
+
     case 'status': {
       const apiKey = flags['api-key'] || config.apiKey;
       const baseUrl = flags['base-url'] || config.baseUrl || 'https://coinpayportal.com';