@profullstack/coinpay 0.12.1 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,77 @@ All notable changes to `@profullstack/coinpay` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.15.0] - 2026-10-07
+
+### Added
+- Brokerage sources, starting with `webull` (Webull E-Documents). Like the tax
+  sources they need no linked account: `coinpay finances statements
+  login|assist|fetch webull` and `statements cloud connect|fetch|schedule
+  webull`. A new `documents` collector mode keeps dated statements and trade
+  confirmations and 1099s listed by tax year (the bank collector skips 1099s).
+  Monthly statements and confirmations are filed into the document library as
+  category `statement` with their month (a confirmation with its day); 1099,
+  1042-S and 5498 forms as category `tax`, type `form`, with the tax year. One
+  copy per file; `statements retry` re-files failures. Brokerages are not
+  throttled like the agencies. If SimpleFIN ever links a Webull account, it
+  keeps the bank path (statements matched to the account).
+- MCP `statements_banks` lists `brokerages`; statements engine exports
+  `BROKERAGE_SOURCES`, `brokerageSource`, `isBrokerageSource`, `sourceMode`,
+  `classifyBrokerageDocument`, `keepBrokerageDocument`, `COLLECT_DOCS`,
+  `OPEN_DOCUMENTS`.
+
+## [0.14.0] - 2026-10-05
+
+### Added
+- Tax document sources: `ftb` (California FTB, MyFTB), `irs` (IRS Online
+  Account) and `irs-business` (IRS Business Tax Account). They need no linked
+  bank: `coinpay finances statements login|assist|fetch <source>` and
+  `statements cloud connect|fetch|schedule <source>` take them. Notices,
+  letters and transcripts are collected in a tax mode (the bank collector
+  still skips them) and filed into the document library as category `tax`,
+  with tax year, document type and the source key; one copy per file.
+- Attempt throttle for tax sources: at most 2 visits per 30 minutes and 4 per
+  day, counted before the visit, lockout pages detected and respected (no
+  override), credentials never re-entered. Ledger at
+  `~/.coinpay/statements/throttle.json`.
+- `coinpay finances books export --with-documents` (a ZIP with the period's
+  tax documents and a manifest) and `books send --with-documents` (to the
+  account owner's own address only), within 8 MiB; what does not fit is listed.
+- MCP: `tax_documents_list`, `tax_documents_get`; `statements_banks` lists the
+  tax sources with their throttle state. API: `GET /finances/documents?category=`
+  and `GET /finances/documents/:id`; SDK `getFinanceDocument`.
+- SDK: `uploadFinanceDocument`, `listFinanceDocuments`; statements engine
+  exports `TAX_SOURCES`, `standaloneSources`, `withStandaloneSources`,
+  `keepCandidate`, `collectScript`, `classifyTaxDocument`, `keepTaxDocument`
+  and the throttle helpers (`evaluateThrottle`, `detectLockout`, …).
+
+### Fixed
+- `coinpay auth login` is the OAuth 2.1 sign-in the help always advertised
+  (`--device` works); `--email/--password` keeps the old password path with a
+  deprecation note.
+- `coinpay self update|upgrade|remove|uninstall` now work as listed in the help
+  (the top-level forms still do). `coinpay mcp` is listed on its own.
+- `institutionKey` maps `*.ftb.ca.gov` to `ftb` (was `ca`) and `*.irs.gov`
+  to `irs`.
+
+## [0.13.0] - 2026-10-04
+
+### Added
+- `coinpay login` signs in with OAuth 2.1: authorization code + PKCE over a
+  loopback redirect, as the public `coinpay-cli` client, with single-use
+  refresh tokens rotated before any command whose access token is about to
+  expire. `coinpay login --device` keeps the device flow for SSH.
+- `coinpay finances statements cloud [status|connect|fetch|schedule|forget]`:
+  CoinPay cloud statement fetching (Professional plan, free for admins).
+  `connect` opens CoinPay's cloud browser to sign in to the bank once; CoinPay
+  keeps the bank's session sealed and fetches every week.
+- MCP: `statements_cloud_status`, `statements_cloud_fetch`.
+- `@profullstack/coinpay/statements` export with types; `openBrowser` takes
+  `extraArgs` and `handleSignals`; `CoinPayClient#baseUrl` getter.
+
+### Fixed
+- The statement fetcher no longer attaches to Chrome's own omnibox page.
+
 ## [0.12.1] - 2026-10-04
 
 ### Fixed

package/bin/coinpay.js

@@ -53,6 +53,13 @@ function handleSelfManage(action) {
   }
 }
 
+/** `coinpay self <sub>`: which installer action, or null. */
+function selfAction(sub) {
+  if (sub === 'update' || sub === 'upgrade' || sub === 'self-update') return 'update';
+  if (sub === 'remove' || sub === 'uninstall') return 'remove';
+  return null;
+}
+
 // ANSI colors
 const colors = {
   reset: '\x1b[0m',
@@ -165,6 +172,7 @@ const BOOLEAN_FLAGS = new Set([
   'wait',
   'strict',
   'headed',
+  'device',
   'force',
   'setup-token-stdin',
   'overwrite',
@@ -175,6 +183,7 @@ const BOOLEAN_FLAGS = new Set([
   'no-model',
   'only-uncategorized',
   'no-attach',
+  'with-documents',
   'estimate-gaps',
   'plain',
   'no-stream',
@@ -378,9 +387,13 @@ ${colors.cyan}Commands:${colors.reset}
     set-url <base-url>    Set custom API URL
     show                  Show current configuration
 
+  ${colors.bright}login${colors.reset}                 Sign in (OAuth 2.1 in your browser; --device on a machine without one)
+  ${colors.bright}logout${colors.reset}                Forget the saved session
+
   ${colors.bright}auth${colors.reset}
     register              Register new merchant account
-    login                 Login to merchant account
+    login                 Same as \`coinpay login\` (OAuth 2.1; --device over SSH).
+                            --email/--password is the old password sign-in (deprecated)
     me                    Show current merchant info
 
   ${colors.bright}payment${colors.reset}
@@ -490,18 +503,31 @@ ${colors.cyan}Commands:${colors.reset}
     statements fetch [bank…]  Download every new PDF statement from the banks and import it
                             (--since YYYY-MM, --max N, --headed, --render S; exits 3 if a bank needs you)
     statements assist <bank>  A window: every PDF you download is imported
+    statements assist ftb|irs|irs-business  Tax sources (no linked bank needed): every
+                            notice, letter or transcript you download is filed under
+                            Documents (tax). IRS: use this, locally (ID.me blocks clouds).
+                            Throttled: 2 visits per 30 min, 4 per day; lockouts respected
+    statements login|fetch|assist webull  Brokerage (no linked account needed): monthly
+                            statements, trade confirmations and 1099s are filed under Documents
     statements coverage   Which account-months have a statement (--months 12)
     statements runs|local|retry  Fetch history, the local archive, re-import what failed
+    statements cloud [status]  CoinPay cloud fetching (Professional; free for admins)
+    statements cloud connect <bank|ftb|irs|webull>  Sign in once in CoinPay's cloud browser (opens your browser)
+    statements cloud fetch [bank] [--wait]  Fetch now in the cloud; weekly by default
+    statements cloud schedule <bank> weekly|off | cloud forget <bank>
     books [queue]         Transactions awaiting category review (--status, --scope, --search)
     books confirm <id>    Confirm a row (--category, --tax, --scope, --note, --always makes a rule)
     books confirm-all     Accept every pending suggestion (--yes)
     books categorize      Rules, heuristics, then the model over unreviewed rows (--wait)
     books rules [add|delete]  Merchant category rules
     books summary         Totals by tax category (--period 2026|2026-Q3|2026-08, --scope)
-    books export          CPA pack (--period, --scope, --format csv|pdf|html|json, --output)
+    books export          CPA pack (--period, --scope, --format csv|pdf|html|json, --output;
+                            --with-documents: a ZIP with the period's tax documents, up to 8 MiB)
     payloads [list|download <id>]  Raw provider responses, exactly as received
     reports send <id>     Email a report (--to a@x,b@y, --format pdf,csv, --message, --no-attach)
-    books send            Email the CPA pack (--to, --period, --scope, --format)
+    books send            Email the CPA pack (--to, --period, --scope, --format,
+                            --with-documents attaches the period's tax documents within
+                            8 MiB; only to your own address)
     digest [show|set|off|send-now]  Weekly digest email (--days mon,fri --hour 8 --to …)
 
   ${colors.bright}escrow${colors.reset}
@@ -541,14 +567,15 @@ ${colors.cyan}Commands:${colors.reset}
     logs <business-id>    Get webhook logs
     test <business-id>    Send test webhook
 
-  ${colors.bright}self${colors.reset}
+  ${colors.bright}self${colors.reset}                  (each also works without "self": coinpay update)
     update                Update the coinpay CLI to the latest version
-    mcp                   Serve CoinPay finances to an AI agent over MCP (stdio):
-                            claude mcp add coinpay -- coinpay mcp
     upgrade               Alias for update
     remove                Uninstall the coinpay CLI
     uninstall             Alias for remove
 
+  ${colors.bright}mcp${colors.reset}                   Serve CoinPay finances to an AI agent over MCP (stdio):
+                          claude mcp add coinpay -- coinpay mcp
+
 ${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)
@@ -2694,13 +2721,20 @@ async function handleAuth(subcommand, args, flags) {
     case 'login': {
       const email = flags.email;
       const password = flags.password;
-      
-      if (!email || !password) {
-        print.error('Required: --email <email> --password <password>');
-        print.info('Example: coinpay auth login --email user@example.com --password mysecret');
+
+      // `auth login` is the documented way in; it is the same OAuth 2.1 sign-in
+      // as `coinpay login`. Only an explicit --email/--password takes the old path.
+      if (email === undefined && password === undefined) {
+        await handleLogin(flags);
         return;
       }
-      
+      print.warn('Password sign-in (--email/--password) is deprecated; use `coinpay login` (OAuth 2.1) or `coinpay login --device`.');
+      if (!email || !password || email === true || password === true) {
+        print.error('Required: --email <email> --password <password>');
+        print.info('Or sign in without a password: coinpay auth login');
+        process.exit(1);
+      }
+
       try {
         const client = createUnauthenticatedClient();
         const { loginMerchant } = await import('../src/auth.js');
@@ -3781,7 +3815,26 @@ async function runInteractiveMenu() {
 // 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() {
+async function handleLogin(flags = {}) {
+  // OAuth 2.1 (authorization code + PKCE, loopback redirect, rotating refresh)
+  // unless asked for the device flow, which is what works over SSH.
+  if (!flags.device) {
+    const cfg = loadConfig();
+    const { loopbackLogin, toStoredSession } = await import('../src/oauth-login.js');
+    try {
+      const tokens = await loopbackLogin({ apiBase: cfg.baseUrl, log: (line) => console.log(line) });
+      cfg.oauth = toStoredSession(tokens);
+      cfg.jwtToken = cfg.oauth.accessToken;
+      saveConfig(cfg);
+      const me = await fetchMe();
+      print.success(me ? `Logged in as ${meLabel(me)} (OAuth 2.1)` : 'Logged in! Session saved to ' + CONFIG_FILE);
+      return;
+    } catch (err) {
+      print.error(`Browser sign-in failed: ${err.message}`);
+      print.info('On a machine without a local browser, use: coinpay login --device');
+      process.exit(1);
+    }
+  }
   const cfg = loadConfig();
   const base = (cfg.baseUrl || 'https://coinpayportal.com/api').replace(/\/$/, '');
 
@@ -3848,6 +3901,7 @@ async function handleLogin() {
 function handleLogout() {
   const cfg = loadConfig();
   delete cfg.jwtToken;
+  delete cfg.oauth;
   saveConfig(cfg);
   print.success('Logged out — session removed from ' + CONFIG_FILE);
 }
@@ -4489,9 +4543,21 @@ async function handleLightning(subcommand, args, flags) {
   }
 }
 
+    // An OAuth 2.1 session's access token lasts an hour: rotate it before any
+    // command that might use it, keeping the new single-use refresh token.
+    if (!['login', 'logout', 'help', 'version', '--version', '-v'].includes(command)) {
+      const sessionCfg = loadConfig();
+      if (sessionCfg.oauth) {
+        const { ensureFreshSession } = await import('../src/oauth-login.js');
+        if (!(await ensureFreshSession(sessionCfg, saveConfig))) {
+          print.warn('Your CoinPay sign-in expired. Run: coinpay login');
+        }
+      }
+    }
+
     switch (command) {
       case 'login':
-        await handleLogin();
+        await handleLogin(flags);
         break;
 
       case 'logout':
@@ -4583,7 +4649,12 @@ async function handleLightning(subcommand, args, flags) {
         await serveStdio({
           version: VERSION,
           getClient: async () => {
-            const token = process.env.COINPAY_SESSION_TOKEN || loadConfig().jwtToken;
+            const cfg = loadConfig();
+            if (cfg.oauth) {
+              const { ensureFreshSession } = await import('../src/oauth-login.js');
+              await ensureFreshSession(cfg, saveConfig);
+            }
+            const token = process.env.COINPAY_SESSION_TOKEN || cfg.jwtToken;
             if (!token) throw new Error('Not logged in: run `coinpay login` (finance tools need the merchant session)');
             return new CoinPayClient({ apiKey: token, baseUrl: getBaseUrl(), timeout: 120000 });
           },
@@ -4602,6 +4673,17 @@ async function handleLightning(subcommand, args, flags) {
         handleSelfManage('update');
         break;
 
+      case 'self': {
+        const action = selfAction(subcommand);
+        if (!action) {
+          print.error(`Unknown self command: ${subcommand || '(none)'}`);
+          print.info('Available: coinpay self update|upgrade|remove|uninstall');
+          process.exit(1);
+        }
+        handleSelfManage(action);
+        break;
+      }
+
       case 'remove':
       case 'uninstall':
         handleSelfManage('remove');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.12.1",
+  "version": "0.15.0",
   "description": "CoinPay SDK & CLI \u2014 Accept cryptocurrency and card payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet, swap and a live finances dashboard",
   "type": "module",
   "main": "./src/index.js",
@@ -37,6 +37,10 @@
       "import": "./src/swap.js",
       "types": "./src/swap.d.ts"
     },
+    "./statements": {
+      "import": "./src/statements-fetch.js",
+      "types": "./src/statements-fetch.d.ts"
+    },
     "./x402": {
       "import": "./src/x402.js"
     },

package/src/client.js

@@ -31,6 +31,11 @@ export class CoinPayClient {
     this.lightning = new LightningClient(this);
   }
 
+  /** The API base this client talks to (read-only). */
+  get baseUrl() {
+    return this.#baseUrl;
+  }
+
   /**
    * Make an authenticated API request
    * @param {string} endpoint - API endpoint

package/src/finances-commands.js

@@ -123,7 +123,7 @@ function describeReport(report) {
   return parts.filter(Boolean).join(' · ');
 }
 
-const STATEMENT_FETCH_ACTIONS = new Set(['banks', 'login', 'fetch', 'assist', 'coverage', 'runs', 'local', 'retry']);
+const STATEMENT_FETCH_ACTIONS = new Set(['banks', 'login', 'fetch', 'assist', 'coverage', 'runs', 'local', 'retry', 'cloud']);
 
 function ago(iso) {
   if (!iso) return 'never';
@@ -132,6 +132,91 @@ function ago(iso) {
   return hours < 48 ? `${Math.round(hours)}h ago` : `${Math.round(hours / 24)}d ago`;
 }
 
+/**
+ * `coinpay finances statements cloud …`: the same statement fetching, run by
+ * CoinPay cloud with a bank session the merchant saved through CoinPay's
+ * cloud browser. Professional plan; free for admins.
+ */
+async function runCloudAction(rest, flags, { client, emit, progress }) {
+  const [sub = 'status', name] = rest;
+  const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  if (sub === 'status' || sub === 'banks') {
+    const data = await api.getCloudStatements(client);
+    const lines = [data.access.allowed ? `CoinPay cloud: ${data.access.message}` : `CoinPay cloud is not available: ${data.access.message}`, ''];
+    for (const bank of data.banks) {
+      const c = bank.cloud;
+      lines.push(`${bank.key}  ${bank.name}${bank.kind === 'tax' ? ' (tax documents)' : bank.kind === 'brokerage' ? ' (brokerage documents)' : ''}  ·  ${!c ? 'not connected' : c.state === 'login_needed' ? 'needs sign-in' : c.state}${c ? `  ·  last fetch ${ago(c.lastFetchAt)}${c.lastStatus ? ` (${c.lastStatus})` : ''}  ·  ${c.schedule}` : ''}`);
+    }
+    const next = data.banks.find((b) => !b.cloud || b.cloud.state !== 'active');
+    if (data.access.allowed && next) lines.push('', `Next: coinpay finances statements cloud connect ${next.key}`);
+    emit(data, lines.join('\n'));
+    return EXIT.OK;
+  }
+
+  if (sub === 'connect') {
+    if (!name) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements cloud connect <bank|ftb|irs|irs-business|webull> [--url <sign-in page>]');
+    const data = await api.connectCloudBank(client, { institutionKey: name, url: typeof flags.url === 'string' ? flags.url : undefined });
+    if (data.warning) progress(`warning: ${data.warning}`);
+    const { siteOrigin, openInBrowser } = await import('./oauth-login.js');
+    const viewer = new URL(data.viewerUrl, siteOrigin(client.baseUrl)).toString();
+    const opened = flags['no-open'] ? false : openInBrowser(viewer);
+    progress(`${opened ? 'Opened' : 'Open'} ${viewer}`);
+    progress('Sign in to your bank there, go to the page that lists your statements, and press Save. Waiting…');
+    for (;;) {
+      await pause(3000);
+      let live;
+      try {
+        live = await api.getCloudLiveSession(client, data.live.id);
+      } catch (err) {
+        if (err.status === 404) throw new CliExit(EXIT.FAILURE, 'The sign-in session is gone (the server restarted?). Run the command again.');
+        throw err;
+      }
+      if (live.status === 'saved') {
+        emit({ live }, `Saved. ${name} is connected to CoinPay cloud and its first fetch is queued: coinpay finances statements cloud status`);
+        return EXIT.OK;
+      }
+      if (['cancelled', 'expired', 'failed'].includes(live.status)) {
+        throw new CliExit(EXIT.FAILURE, `The sign-in session ended: ${live.status}${live.error ? ` (${live.error})` : ''}`);
+      }
+    }
+  }
+
+  if (sub === 'fetch') {
+    const data = await api.fetchCloudStatements(client, { institutionKey: name });
+    if (!flags.wait) {
+      emit(data, data.jobs.map((j) => `queued ${j.id} (${j.params?.institutionKey ?? ''})`).join('\n') + '\nFollow with: coinpay finances statements runs');
+      return EXIT.OK;
+    }
+    const jobs = new Map(data.jobs.map((j) => [j.id, j]));
+    const deadline = Date.now() + 20 * 60_000;
+    while (Date.now() < deadline && [...jobs.values()].some((j) => ['queued', 'running', 'waiting_for_budget'].includes(j.status))) {
+      await pause(5000);
+      for (const id of jobs.keys()) jobs.set(id, await api.getFinanceJob(client, id));
+    }
+    const done = [...jobs.values()];
+    emit({ jobs: done }, done.map((j) => `${j.params?.institutionKey ?? j.id}: ${j.status}${j.result ? `, ${j.result.imported ?? 0} imported, ${j.result.duplicates ?? 0} already had` : ''}${j.errorMessage ? ` (${j.errorMessage})` : ''}`).join('\n'));
+    return done.every((j) => j.status === 'completed') ? EXIT.OK : EXIT.STRICT;
+  }
+
+  if (sub === 'schedule') {
+    const value = rest[2];
+    if (!name || (value !== 'weekly' && value !== 'off')) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements cloud schedule <bank> weekly|off');
+    const data = await api.setCloudSchedule(client, name, value);
+    emit(data, `${name}: ${value === 'weekly' ? 'fetched every week' : 'schedule off'}`);
+    return EXIT.OK;
+  }
+
+  if (sub === 'forget' || sub === 'disconnect') {
+    if (!name) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements cloud forget <bank>');
+    const data = await api.disconnectCloudBank(client, name);
+    emit(data, data.note);
+    return EXIT.OK;
+  }
+
+  throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements cloud [status|connect <bank>|fetch [bank] [--wait]|schedule <bank> weekly|off|forget <bank>]');
+}
+
 /**
  * Downloading statements from the banks themselves (SimpleFIN has no
  * documents). Runs on this machine: each bank's session lives in a local
@@ -150,6 +235,7 @@ async function runStatementFetchAction(action, rest, flags, { client, out, emit,
   };
 
   try {
+    if (action === 'cloud') return await runCloudAction(rest, flags, { client, out, emit, progress });
     if (action === 'coverage') {
       const data = await api.getStatementCoverage(client, { months: months(flags.months, 12) });
       const mark = { have: '■', missing: '·', open: '○' };
@@ -177,7 +263,8 @@ async function runStatementFetchAction(action, rest, flags, { client, out, emit,
     }
 
     const bound = await sf.clientApi(client);
-    const institutions = sf.groupInstitutions(await bound.listAccounts());
+    const linked = sf.groupInstitutions(await bound.listAccounts());
+    const institutions = sf.withStandaloneSources(linked);
     if (action === 'banks') {
       const state = sf.loadLocal(home);
       let latest = [];
@@ -186,27 +273,65 @@ async function runStatementFetchAction(action, rest, flags, { client, out, emit,
       } catch {
         // An older deployment without the route still lists the banks.
       }
-      const rows = institutions.map((i) => ({ ...i, signedIn: sf.signedIn(i.key, home), local: state.institutions[i.key] || {}, lastRun: latest.find((r) => r.institutionKey === i.key) || null }));
+      const rows = institutions.map((i) => ({
+        ...i,
+        signedIn: sf.signedIn(i.key, home),
+        local: state.institutions[i.key] || {},
+        lastRun: latest.find((r) => r.institutionKey === i.key) || null,
+        throttle: sf.isTaxSource(i) ? sf.checkLocalThrottle(home, i.key) : null,
+      }));
+      const banks = rows.filter((b) => !sf.isTaxSource(b) && !sf.isBrokerageSource(b));
+      const taxRows = rows.filter((b) => sf.isTaxSource(b));
+      const brokerageRows = rows.filter((b) => sf.isBrokerageSource(b));
+      const line = (b) => `${b.key}  ${b.name}  ·  ${b.signedIn ? `signed in ${ago(b.local.loggedInAt)}` : 'not signed in'}  ·  last fetch ${b.lastRun ? `${b.lastRun.status} ${ago(b.lastRun.finishedAt)}` : 'never'}${b.throttle && !b.throttle.ok ? `  ·  waiting: ${b.throttle.message}` : ''}`;
       emit({ home, chrome, banks: rows }, [
-        ...rows.map((b) => `${b.key}  ${b.name}  ·  ${b.signedIn ? `signed in ${ago(b.local.loggedInAt)}` : 'not signed in'}  ·  last fetch ${b.lastRun ? `${b.lastRun.status} ${ago(b.lastRun.finishedAt)}` : 'never'}\n${b.accounts.map((a) => `    ${a.name}${a.last4 ? '' : '  (no last four digits: its statements may need filing by hand)'}`).join('\n')}`),
-        ...(rows.some((b) => !b.signedIn) ? ['', `Next: coinpay finances statements login ${rows.find((b) => !b.signedIn).key}`] : []),
+        ...banks.map((b) => `${line(b)}\n${b.accounts.map((a) => `    ${a.name}${a.last4 ? '' : '  (no last four digits: its statements may need filing by hand)'}`).join('\n')}`),
+        ...(banks.length ? [] : ['No linked banks.']),
+        '',
+        'Tax sources (notices, letters, transcripts -> Documents; at most 2 visits per 30 min, 4 per day):',
+        ...taxRows.map((b) => line(b)),
+        '',
+        'Brokerages (statements, trade confirmations, 1099s -> Documents):',
+        ...brokerageRows.map((b) => line(b)),
+        ...(banks.some((b) => !b.signedIn) ? ['', `Next: coinpay finances statements login ${banks.find((b) => !b.signedIn).key}`] : []),
         ...(chrome ? [] : ['', sf.NO_CHROME]),
       ].join('\n'));
       return EXIT.OK;
     }
     if (action === 'login' || action === 'assist') {
-      if (rest.length !== 1) throw new CliExit(EXIT.INVALID, `Usage: coinpay finances statements ${action} <bank>`);
+      if (rest.length !== 1) throw new CliExit(EXIT.INVALID, `Usage: coinpay finances statements ${action} <bank|ftb|irs|irs-business|webull>`);
       if (!chrome) throw new CliExit(EXIT.FAILURE, sf.NO_CHROME);
-      const institution = sf.pickInstitution(institutions, rest[0]);
+      const institution = sf.pickInstitution(linked, rest[0]);
+      const tax = sf.isTaxSource(institution);
+      const brokerage = sf.isBrokerageSource(institution);
       const state = sf.loadLocal(home);
       const local = (state.institutions[institution.key] ||= {});
       const urls = sf.startUrls(institution, local.start);
+      let onPageText;
+      if (tax) {
+        // Counted before the window opens. --force never lifts a lockout.
+        const verdict = sf.takeLocalAttempt(home, institution.key, action);
+        if (!verdict.ok) throw new CliExit(EXIT.STRICT, `${institution.name}: not opening, ${verdict.message}`);
+        const source = sf.taxSource(institution.key) || {};
+        let warned = false;
+        onPageText = (text) => {
+          const lock = sf.detectLockout(text);
+          if (!lock) return;
+          const until = sf.lockoutUntil(lock, new Date(), undefined, source.lockoutMinutes);
+          sf.recordLocalLockout(home, institution.key, until, `lockout page during ${action}`);
+          if (!warned) {
+            warned = true;
+            progress(`${institution.name} shows a locked account. Stop trying and close the window; CoinPay will not open it again before ${until}.`);
+          }
+        };
+        progress(`${institution.name}: sign in once, by hand. If a code arrives late, do not resubmit the form; close the window and wait. (${sf.TAX_THROTTLE.perWindow} visits per 30 minutes, ${sf.TAX_THROTTLE.perDay} per day.)`);
+      }
       const browser = await sf.openBrowser({ chrome, profile: sf.profileDir(institution.key, home), headless: false, force: flags.force === true });
       if (action === 'login') {
         const url = typeof flags.url === 'string' ? flags.url : urls.login;
         if (!url) throw new CliExit(EXIT.INVALID, `CoinPay has no site for ${institution.name}; pass --url with its sign-in page`);
         out(`Opening ${institution.name}. Sign in, go to the page that lists your statements, then close the window.`);
-        const last = await sf.loginWindow(browser, url);
+        const last = await sf.loginWindow(browser, url, { onPageText });
         await browser.close();
         local.loggedInAt = new Date().toISOString();
         if (last) local.start = last;
@@ -214,13 +339,22 @@ async function runStatementFetchAction(action, rest, flags, { client, out, emit,
         emit({ bank: institution.key, start: local.start || urls.fetch }, last ? `Saved. fetch will start at ${last}` : 'Saved. The window closed on a sign-in page, so fetch starts from the bank\'s known page.');
         return EXIT.OK;
       }
-      out(`Opening ${institution.name}. Download each statement you want; each is imported as it lands. Close the window when done.`);
+      out(tax
+        ? `Opening ${institution.name}. Sign in, open your notices, letters or transcripts, and download each PDF; each is filed under Documents (tax) as it lands. Close the window when done.`
+        : brokerage
+          ? `Opening ${institution.name}. Sign in, open its documents, and download each statement, trade confirmation or 1099; each is filed under Documents as it lands. Close the window when done.`
+          : `Opening ${institution.name}. Download each statement you want; each is imported as it lands. Close the window when done.`);
       let kept = 0;
       try {
         await sf.assistWindow(browser, {
           start: urls.fetch,
+          onPageText,
           onFile: async (download) => {
-            const result = await sf.keepStatement({ institution, download, state, home, importStatement: bound.importStatement, how: 'assist' });
+            const result = tax
+              ? await sf.keepTaxDocument({ institution, download, state, home, fileDocument: bound.fileDocument, how: 'assist' })
+              : brokerage
+                ? await sf.keepBrokerageDocument({ institution, download, state, home, fileDocument: bound.fileDocument, how: 'assist' })
+                : await sf.keepStatement({ institution, download, state, home, importStatement: bound.importStatement, how: 'assist' });
             if (result.status === 'imported') kept += 1;
             progress(`  ${result.status}: ${result.entry ? result.entry.path : result.name}${result.entry && result.entry.importError ? ` (${result.entry.importError})` : ''}`);
             sf.saveLocal(state, home);
@@ -229,7 +363,7 @@ async function runStatementFetchAction(action, rest, flags, { client, out, emit,
       } finally {
         await browser.close();
       }
-      emit({ bank: institution.key, imported: kept }, `${kept} imported`);
+      emit({ bank: institution.key, imported: kept }, tax ? `${kept} filed under Documents (tax)` : brokerage ? `${kept} filed under Documents` : `${kept} imported`);
       return EXIT.OK;
     }
     // fetch
@@ -240,7 +374,7 @@ async function runStatementFetchAction(action, rest, flags, { client, out, emit,
     const render = flags.render !== undefined ? Number(flags.render) : 25;
     if (!Number.isFinite(render) || render < 3 || render > 300) throw new CliExit(EXIT.INVALID, '--render is seconds, 3 to 300');
     const results = await sf.runStatementFetch({ api: bound, banks: rest, since, max, renderMs: render * 1000, headless: flags.headed !== true, chrome, home, log: progress, force: flags.force === true });
-    emit({ banks: results }, results.map((r) => `${r.bank}: ${r.status}, ${r.imported} imported, ${r.duplicates} already had, ${r.unmatched} unmatched${r.message ? ` (${r.message})` : ''}`).join('\n'));
+    emit({ banks: results }, results.map((r) => `${r.bank}: ${r.status}, ${r.imported} ${r.kind === 'bank' ? 'imported' : 'filed'}, ${r.duplicates} already had${r.kind !== 'bank' ? '' : `, ${r.unmatched} unmatched`}${r.message ? ` (${r.message})` : ''}`).join('\n'));
     return results.every((r) => r.status === 'ok' && r.failed === 0) ? EXIT.OK : EXIT.STRICT;
   } catch (err) {
     if (err instanceof sf.StatementFetchError) throw new CliExit(EXIT.INVALID, err.message);
@@ -540,7 +674,7 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
           return EXIT.OK;
         }
         if (STATEMENT_FETCH_ACTIONS.has(action)) return await runStatementFetchAction(action, args.slice(1), flags, { client, out, emit, progress });
-        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements [import <file>|list|get <id>|download <id>|reconcile <id>|delete <id>|banks|login <bank>|fetch [bank…]|assist <bank>|coverage|runs|local|retry]');
+        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements [import <file>|list|get <id>|download <id>|reconcile <id>|delete <id>|banks|login <bank>|fetch [bank…]|assist <bank>|coverage|runs|local|retry|cloud …]  (tax sources: ftb, irs, irs-business; brokerages: webull)');
       }
 
       case 'books': {
@@ -613,7 +747,7 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
           return EXIT.OK;
         }
         if (action === 'send') {
-          if (typeof flags.to !== 'string') throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances books send --to cpa@x.com,me@x.com --period 2026 [--scope business] [--format pdf,csv] [--message "…"]');
+          if (typeof flags.to !== 'string') throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances books send --to cpa@x.com,me@x.com --period 2026 [--scope business] [--format pdf,csv] [--message "…"] [--with-documents (your own address only)]');
           const period = typeof flags.period === 'string' ? flags.period : null;
           const from = typeof flags.from === 'string' ? flags.from : undefined;
           const toDate = typeof flags['to-date'] === 'string' ? flags['to-date'] : undefined;
@@ -625,8 +759,12 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
             formats: flags.format ? listFlag(flags.format) : undefined,
             message: typeof flags.message === 'string' ? flags.message : null,
             attach: flags['no-attach'] ? false : true,
+            withDocuments: flags['with-documents'] === true,
           });
-          emit(data, `Sent to ${data.sent.join(', ') || 'nobody'}${data.failed.length ? `; failed: ${data.failed.map((f) => `${f.to} (${f.error})`).join(', ')}` : ''}. ${data.rows} rows, ${data.unreviewed} unreviewed. Link (expires ${data.linkExpiresAt.slice(0, 10)}): ${data.linkUrl}`);
+          const docs = data.documents
+            ? ` Tax documents attached: ${data.documents.attached.length ? data.documents.attached.join(', ') : 'none'}.${data.documents.skipped.length ? ` Not attached (in CoinPay under Documents): ${data.documents.skipped.map((d) => `${d.title} (${d.reason})`).join(', ')}.` : ''}`
+            : '';
+          emit(data, `Sent to ${data.sent.join(', ') || 'nobody'}${data.failed.length ? `; failed: ${data.failed.map((f) => `${f.to} (${f.error})`).join(', ')}` : ''}. ${data.rows} rows, ${data.unreviewed} unreviewed.${docs} Link (expires ${data.linkExpiresAt.slice(0, 10)}): ${data.linkUrl}`);
           return data.sent.length > 0 ? EXIT.OK : EXIT.FAILURE;
         }
         if (action === 'summary' || action === 'export') {
@@ -649,10 +787,16 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
             return EXIT.OK;
           }
           const format = typeof flags.format === 'string' ? flags.format.toLowerCase() : 'csv';
-          const file = await api.exportBooks(client, { period: period || undefined, from, to, timezone, scope, format });
-          const output = typeof flags.output === 'string' ? flags.output : file.filename || `books-${period || 'range'}.${format}`;
+          const withDocuments = flags['with-documents'] === true;
+          const file = await api.exportBooks(client, { period: period || undefined, from, to, timezone, scope, format, withDocuments });
+          const output = typeof flags.output === 'string' ? flags.output : file.filename || `books-${period || 'range'}.${withDocuments ? 'zip' : format}`;
           const path = writeDownload(output, Buffer.from(file.bytes), { overwrite: flags.overwrite === true });
-          emit({ output: path, bytes: file.bytes.length, unreviewed: Number(file.headers['x-unreviewed-rows'] || 0) }, `Wrote ${path} (${file.bytes.length} bytes; ${file.headers['x-unreviewed-rows'] || 0} unreviewed rows)`);
+          const attachedDocs = Number(file.headers['x-documents-attached'] || 0);
+          const skippedDocs = Number(file.headers['x-documents-skipped'] || 0);
+          emit(
+            { output: path, bytes: file.bytes.length, unreviewed: Number(file.headers['x-unreviewed-rows'] || 0), ...(withDocuments ? { documentsAttached: attachedDocs, documentsSkipped: skippedDocs } : {}) },
+            `Wrote ${path} (${file.bytes.length} bytes; ${file.headers['x-unreviewed-rows'] || 0} unreviewed rows)${withDocuments ? `. ${attachedDocs} tax document(s) inside${skippedDocs ? `, ${skippedDocs} left out to stay under 8 MiB (listed in MANIFEST.txt)` : ''}` : ''}`,
+          );
           return EXIT.OK;
         }
         throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances books [queue|confirm <id>|confirm-all --yes|categorize|rules [add|delete]|summary|export|send]');