@profullstack/coinpay 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,59 @@ 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

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',
@@ -176,6 +183,7 @@ const BOOLEAN_FLAGS = new Set([
   'no-model',
   'only-uncategorized',
   'no-attach',
+  'with-documents',
   'estimate-gaps',
   'plain',
   'no-stream',
@@ -379,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                 Sign in (OAuth 2.1 in your browser; --device on a machine without one)
+    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}
@@ -491,10 +503,16 @@ ${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>  Sign in once in CoinPay's cloud browser (opens your browser)
+    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)
@@ -503,10 +521,13 @@ ${colors.cyan}Commands:${colors.reset}
     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}
@@ -546,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)
@@ -2699,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');
@@ -4644,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.13.0",
+  "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",

package/src/finances-commands.js

@@ -146,7 +146,7 @@ async function runCloudAction(rest, flags, { client, emit, progress }) {
     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}  ·  ${!c ? 'not connected' : c.state === 'login_needed' ? 'needs sign-in' : c.state}${c ? `  ·  last fetch ${ago(c.lastFetchAt)}${c.lastStatus ? ` (${c.lastStatus})` : ''}  ·  ${c.schedule}` : ''}`);
+      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}`);
@@ -155,8 +155,9 @@ async function runCloudAction(rest, flags, { client, emit, progress }) {
   }
 
   if (sub === 'connect') {
-    if (!name) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements cloud connect <bank> [--url <sign-in page>]');
+    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);
@@ -262,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 = [];
@@ -271,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;
@@ -299,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);
@@ -314,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
@@ -325,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);
@@ -625,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': {
@@ -698,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;
@@ -710,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') {
@@ -734,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]');

package/src/finances-reports.d.ts

@@ -316,7 +316,43 @@ export function getBooksSummary(
   client: CoinPayClient,
   options?: PeriodSelection & { scope?: 'business' | 'personal' | 'all'; rows?: boolean },
 ): Promise<{ period: Record<string, unknown>; scope: string; lines: BooksSummaryLine[]; totals: Array<{ currency: string; income: string; expenses: string; net: string; excluded: string }>; rows: number; unreviewed: number; uncategorized: number; notice: string; transactions?: BooksRow[] }>;
-export function exportBooks(client: CoinPayClient, options?: PeriodSelection & { scope?: 'business' | 'personal' | 'all'; format?: 'csv' | 'pdf' | 'html' | 'json' }): Promise<BinaryResponse>;
+export function exportBooks(client: CoinPayClient, options?: PeriodSelection & { scope?: 'business' | 'personal' | 'all'; format?: 'csv' | 'pdf' | 'html' | 'json'; withDocuments?: boolean }): Promise<BinaryResponse>;
+
+export interface FinanceDocument {
+  id: string;
+  title: string;
+  category: 'report' | 'statement' | 'tax' | 'invoice' | 'other';
+  periodLabel: string | null;
+  notes: string | null;
+  filename: string | null;
+  contentType: string;
+  bytes: number;
+  source: 'upload' | 'api' | 'fetch' | 'cloud';
+  institutionKey: string | null;
+  taxYear: number | null;
+  docType: string | null;
+  uploadedBy: string | null;
+  createdAt: string;
+  downloadUrl: string;
+}
+export function uploadFinanceDocument(
+  client: CoinPayClient,
+  options: {
+    file: Uint8Array | Blob;
+    filename?: string;
+    title?: string;
+    category?: 'report' | 'statement' | 'tax' | 'invoice' | 'other';
+    periodLabel?: string | null;
+    notes?: string | null;
+    contentType?: string;
+    source?: 'fetch';
+    institutionKey?: string;
+    taxYear?: number | null;
+    docType?: string | null;
+  },
+): Promise<{ document: FinanceDocument; duplicate: boolean }>;
+export function listFinanceDocuments(client: CoinPayClient, options?: { category?: FinanceDocument['category']; limit?: number }): Promise<FinanceDocument[]>;
+export function getFinanceDocument(client: CoinPayClient, documentId: string): Promise<FinanceDocument>;
 export function listFinancePayloads(client: CoinPayClient, options?: { connectionId?: string; limit?: number; offset?: number }): Promise<{ payloads: Array<Record<string, unknown>>; total: number }>;
 export function downloadFinancePayload(client: CoinPayClient, payloadId: string): Promise<BinaryResponse>;
 
@@ -350,8 +386,8 @@ export function sendFinanceReportEmail(
 ): Promise<SendOutcome>;
 export function sendBooksEmail(
   client: CoinPayClient,
-  options: { to: string | string[]; period?: string; from?: string; toDate?: string; timezone?: string; scope?: 'business' | 'personal' | 'all'; formats?: string[]; message?: string | null; attach?: boolean; expiresInDays?: number },
-): Promise<SendOutcome & { unreviewed: number; rows: number }>;
+  options: { to: string | string[]; period?: string; from?: string; toDate?: string; timezone?: string; scope?: 'business' | 'personal' | 'all'; formats?: string[]; message?: string | null; attach?: boolean; expiresInDays?: number; withDocuments?: boolean },
+): Promise<SendOutcome & { unreviewed: number; rows: number; documents?: { attached: string[]; skipped: Array<{ title: string; bytes: number; reason: string }> } }>;
 export function getWeeklyDigest(client: CoinPayClient): Promise<WeeklyDigest | null>;
 export function setWeeklyDigest(
   client: CoinPayClient,

package/src/finances-reports.js

@@ -256,6 +256,43 @@ export async function reconcileFinanceStatement(client, statementId, {
   return data.reconciliation;
 }
 
+// ── Document library ──
+
+/**
+ * File a document (multipart POST /finances/documents). `file` is the bytes.
+ * Tax documents from the fetcher pass `category: 'tax'`, `source: 'fetch'`,
+ * `institutionKey`, `taxYear` and `docType`. Answers `{document, duplicate}`:
+ * the server keeps one copy per file (by sha256) and says when it had it.
+ */
+export async function uploadFinanceDocument(client, {
+  file, filename = 'document.pdf', title, category, periodLabel, notes, contentType = 'application/pdf', source, institutionKey, taxYear, docType,
+} = {}) {
+  if (!file) throw new Error('A file is required');
+  const form = new FormData();
+  const blob = file instanceof Blob ? file : new Blob([file], { type: contentType });
+  form.append('file', blob, filename);
+  form.append('title', title || filename);
+  if (category) form.append('category', category);
+  if (periodLabel) form.append('period', periodLabel);
+  if (notes) form.append('notes', notes);
+  if (source) form.append('source', source);
+  if (institutionKey) form.append('institutionKey', institutionKey);
+  if (taxYear !== undefined && taxYear !== null) form.append('taxYear', String(taxYear));
+  if (docType) form.append('docType', docType);
+  return client.requestForm('/finances/documents', form);
+}
+
+/** The document library, newest first; `category: 'tax'` for FTB/IRS notices, letters and transcripts. */
+export async function listFinanceDocuments(client, { category, limit } = {}) {
+  const data = await call(client, `/finances/documents${query({ category, limit })}`);
+  return data.documents || [];
+}
+
+export async function getFinanceDocument(client, documentId) {
+  const data = await call(client, `/finances/documents/${encodeURIComponent(documentId)}`);
+  return data.document;
+}
+
 /** Report one bank's statement fetch run (counts only). */
 export async function reportStatementFetchRun(client, run) {
   const data = await call(client, '/finances/statements/fetch-runs', { method: 'POST', body: JSON.stringify(run) });
@@ -351,9 +388,13 @@ export async function getBooksSummary(client, { period, from, to, timezone, scop
   return call(client, `/finances/books/summary${query({ period, from, to, timezone, scope, rows: rows ? 1 : undefined })}`);
 }
 
-/** The CPA pack as bytes. */
-export async function exportBooks(client, { period, from, to, timezone, scope, format = 'csv' } = {}) {
-  return client.requestBinary(`/finances/books/export${query({ period, from, to, timezone, scope, format })}`);
+/**
+ * The CPA pack as bytes. With `withDocuments` the answer is a ZIP: the pack
+ * plus the period's tax documents that fit in 8 MiB, and MANIFEST.txt naming
+ * what was left out.
+ */
+export async function exportBooks(client, { period, from, to, timezone, scope, format = 'csv', withDocuments = false } = {}) {
+  return client.requestBinary(`/finances/books/export${query({ period, from, to, timezone, scope, format, with_documents: withDocuments ? 1 : undefined })}`);
 }
 
 // ── Raw provider payloads ──
@@ -377,10 +418,10 @@ export async function sendFinanceReportEmail(client, reportId, { to, formats, me
 }
 
 /** Email the CPA pack for a period. `toDate` is the exclusive end for a custom range. */
-export async function sendBooksEmail(client, { to, period, from, toDate, timezone, scope, formats, message, attach, expiresInDays } = {}) {
+export async function sendBooksEmail(client, { to, period, from, toDate, timezone, scope, formats, message, attach, expiresInDays, withDocuments } = {}) {
   return call(client, '/finances/books/send', {
     method: 'POST',
-    body: JSON.stringify({ to, period, from, toDate, timezone, scope, formats, message, attach, expiresInDays }),
+    body: JSON.stringify({ to, period, from, toDate, timezone, scope, formats, message, attach, expiresInDays, withDocuments: withDocuments === true ? true : undefined }),
   });
 }
 

package/src/mcp.js

@@ -60,9 +60,39 @@ export const TOOLS = [
       return text({
         chrome: sf.findChrome(),
         banks: institutions.map((i) => ({ key: i.key, name: i.name, accounts: i.accounts.map((a) => a.name), signedIn: sf.signedIn(i.key, home), ...state.institutions[i.key] })),
+        // FTB and IRS need no linked bank; each is throttled (2 visits / 30 min, 4 / day).
+        taxSources: sf.standaloneSources().filter((s) => s.kind === 'tax').map((s) => ({ key: s.key, name: s.name, signedIn: sf.signedIn(s.key, home), throttle: sf.checkLocalThrottle(home, s.key), ...state.institutions[s.key] })),
+        // Brokerages with no linked account (Webull): statements, confirmations and 1099s go to Documents.
+        brokerages: sf.standaloneSources().filter((s) => s.kind === 'brokerage' && !institutions.some((i) => i.key === s.key)).map((s) => ({ key: s.key, name: s.name, signedIn: sf.signedIn(s.key, home), ...state.institutions[s.key] })),
       });
     },
   },
+  {
+    name: 'tax_documents_list',
+    description:
+      'Tax documents in the CoinPay document library: notices, letters and transcripts fetched from California FTB and the IRS (or uploaded), with tax year, type, source and period. Details only, not the files. Optionally one tax year or one source (ftb, irs, irs-business).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        taxYear: { type: 'integer', minimum: 1990, maximum: 2100 },
+        source: { type: 'string', description: 'ftb, irs or irs-business' },
+        limit: { type: 'integer', minimum: 1, maximum: 500 },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => {
+      const documents = (await reports.listFinanceDocuments(client, { category: 'tax', limit: args.limit }))
+        .filter((d) => args.taxYear === undefined || d.taxYear === args.taxYear)
+        .filter((d) => args.source === undefined || d.institutionKey === args.source);
+      return text({ documents });
+    },
+  },
+  {
+    name: 'tax_documents_get',
+    description: 'One document from the CoinPay document library by id: title, type, tax year, source, period, size, and its download path in CoinPay.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false },
+    handler: async (args, { client }) => text({ document: await reports.getFinanceDocument(client, args.id) }),
+  },
   {
     name: 'statements_cloud_status',
     description:
@@ -121,7 +151,7 @@ export async function handleMessage(message, ctx) {
         capabilities: { tools: {} },
         serverInfo: { name: 'coinpay', version: ctx.version || '0.0.0' },
         instructions:
-          'CoinPay finances. Statement PDFs come from the banks themselves (SimpleFIN has none): statements_coverage shows what is missing, statements_fetch downloads what is new on this machine. A bank marked login_needed needs a person to run `coinpay finances statements login <bank>`.',
+          'CoinPay finances. Statement PDFs come from the banks themselves (SimpleFIN has none): statements_coverage shows what is missing, statements_fetch downloads what is new on this machine. A bank marked login_needed needs a person to run `coinpay finances statements login <bank>`. Tax notices, letters and transcripts (California FTB, IRS) are in tax_documents_list; tax data stays on CoinPay surfaces and is never sent elsewhere.',
       });
     case 'notifications/initialized':
     case 'notifications/cancelled':