@profullstack/coinpay 0.13.0 → 0.16.0

package/CHANGELOG.md

@@ -5,6 +5,81 @@ 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.16.0] - 2026-10-12
+
+### Added
+- `coinpay finances due [--days 7]`: what is due, overdue or not posted yet
+  across every linked account, projected from each recurring charge's own
+  cadence plus statement due days set on cards and loans.
+- `coinpay finances recurring`: every recurring charge with cadence, last and
+  next date and monthly cost.
+- `coinpay finances due-day <account-id> <1-31|clear> [--amount N|balance]`:
+  a card or loan's statement due day, which no bank feed carries.
+- `coinpay finances daily [show|on|off|send-now]`: the daily summary email
+  (due soon, new activity since the last one, balance sheet).
+- MCP: `finance_due_soon`, `finance_recurring`, `finance_summary`,
+  `finance_transactions`, `finance_set_due_day`, `finance_daily_summary`.
+- SDK: `getDueSoon`, `getDailySummary`, `setDailySummary`,
+  `deleteDailySummary`, `sendDailySummaryNow`, `setAccountDueDay`.
+
+### Fixed
+- `coinpay mcp` `tools/list` now carries `resultType`, `ttlMs` and
+  `cacheScope`; without them Claude Code rejected the whole list
+  ("connected · tools fetch failed").
+
+## [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,11 +521,18 @@ ${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 …)
+    due [--days 7]        What is due and overdue across every account (--days up to 60)
+    recurring             Every recurring charge detected, with next date and monthly cost
+    due-day <id> <1-31|clear>  A card/loan's statement due day (--amount 810.46, or balance)
+    daily [show|on|off|send-now]  Daily summary email: due soon, new activity, position (--hour 7 --to …)
 
   ${colors.bright}escrow${colors.reset}
     create                Create a new escrow
@@ -546,14 +571,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 +2725,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');
@@ -4326,7 +4359,12 @@ async function handleFinances(subcommand, args, flags) {
     case 'statements':
     case 'books':
     case 'payloads':
-    case 'digest': {
+    case 'digest':
+    case 'due':
+    case 'due-soon':
+    case 'recurring':
+    case 'due-day':
+    case 'daily': {
       const { client } = financesClient();
       const { runFinancesCommand } = await import('../src/finances-commands.js');
       const code = await runFinancesCommand(subcommand, args, flags, {
@@ -4340,7 +4378,7 @@ async function handleFinances(subcommand, args, flags) {
 
     default:
       print.error(`Unknown finances command: ${subcommand}`);
-      console.log('Usage: coinpay finances [tui|summary|accounts|ledger|connections|sync|connect|disconnect|backfill|jobs|coverage|report|reports|statements|books|payloads|digest]');
+      console.log('Usage: coinpay finances [tui|summary|accounts|ledger|connections|sync|connect|disconnect|backfill|jobs|coverage|report|reports|statements|books|payloads|digest|due|recurring|due-day|daily]');
       process.exit(1);
   }
 }
@@ -4644,6 +4682,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.16.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]');
@@ -787,6 +846,80 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
         throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances digest [show|set --days mon,fri --hour 8 --to a@x,b@y [--scope business]|off|delete|send-now]');
       }
 
+      case 'due':
+      case 'due-soon':
+      case 'recurring': {
+        const days = flags.days !== undefined ? Number(flags.days) : undefined;
+        if (days !== undefined && (!Number.isInteger(days) || days < 0 || days > 60)) throw new CliExit(EXIT.INVALID, '--days must be 0 to 60');
+        const d = await api.getDueSoon(client, { days, timezone: typeof flags.timezone === 'string' ? flags.timezone : undefined });
+        const cur = d.currency || 'USD';
+        const money = (n) => new Intl.NumberFormat('en-US', { style: 'currency', currency: cur }).format(n);
+        if (subcommand === 'recurring') {
+          if (json) { out(JSON.stringify(d.recurring, null, 2)); return EXIT.OK; }
+          const rows = [...d.recurring.charges].sort((a, b) => a.nextExpected.localeCompare(b.nextExpected));
+          out(`${rows.length} recurring charges · ${money(d.recurring.monthlyTotal)}/mo${d.recurring.monthlyDebtService ? ` (${money(d.recurring.monthlyDebtService)} debt service)` : ''}`);
+          for (const c of rows) {
+            out(`  next ${c.nextExpected.slice(0, 10)}  ${c.cadence.padEnd(9)} ${money(c.amount).padStart(11)}  ${c.payee}  · ${c.accountName}${c.isDebtService ? ' · debt' : ''}`);
+          }
+          return EXIT.OK;
+        }
+        if (json) { out(JSON.stringify(d, null, 2)); return EXIT.OK; }
+        const when = (i) => i.status === 'paid' ? 'paid' : i.status === 'awaiting' ? 'not yet?' : i.daysUntil === 0 ? 'today' : i.daysUntil === 1 ? 'tomorrow' : i.daysUntil < 0 ? `${-i.daysUntil}d LATE` : `in ${i.daysUntil}d`;
+        const amt = (i) => i.amount !== null ? money(i.amount) : i.owed !== null ? `bal ${money(i.owed)}` : 'statement';
+        out(`${d.today} (${d.timezone}) · ${money(d.totals.due)} due in ${d.horizonDays} days${d.totals.overdue ? ` · ${money(d.totals.overdue)} OVERDUE` : ''}${d.totals.unpriced ? ` · +${d.totals.unpriced} statement balance(s)` : ''}`);
+        if (d.items.length === 0 && d.paid.length === 0) out('  Nothing due.');
+        for (const i of [...d.items, ...d.paid]) {
+          out(`  ${i.dueOn}  ${when(i).padEnd(9)} ${amt(i).padStart(14)}  ${i.payee}  · ${i.accountName}${i.source === 'scheduled' ? ' · statement due' : ''}`);
+        }
+        if (d.missed.length) out(`  Not seen lately: ${d.missed.slice(0, 8).map((m) => `${m.payee} (expected ${m.expectedOn})`).join(', ')}`);
+        return EXIT.OK;
+      }
+
+      case 'due-day': {
+        const id = args[0];
+        const value = args[1];
+        if (!id || value === undefined) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances due-day <account-id> <1-31|clear> [--amount 810.46|--amount balance]  (ids: coinpay finances accounts)');
+        const day = value === 'clear' || value === 'off' ? null : Number(value);
+        if (day !== null && (!Number.isInteger(day) || day < 1 || day > 31)) throw new CliExit(EXIT.INVALID, 'The due day must be 1 to 31, or clear');
+        const amount = flags.amount === undefined ? undefined : flags.amount === 'balance' || flags.amount === true ? null : String(flags.amount);
+        const account = await api.setAccountDueDay(client, id, { day, amount });
+        emit({ account }, day === null ? `Cleared the due day on ${account.name}.` : `${account.name}: due on day ${day}${account.payment_due_amount != null ? `, ${account.payment_due_amount}` : ', statement balance'}.`);
+        return EXIT.OK;
+      }
+
+      case 'daily': {
+        const action = flags.off ? 'off' : args[0] || 'show';
+        const describe = (s) => s
+          ? `Daily summary ${s.active ? 'on' : 'off'} · ${String(s.hour).padStart(2, '0')}:00 ${s.timezone} · to ${s.recipients.join(', ')}${s.nextRunAt ? ` · next ${s.nextRunAt}` : ''}${s.lastSentAt ? ` · last ${s.lastSentAt}` : ''}`
+          : 'No daily summary configured. Turn it on with: coinpay finances daily on --hour 7 --to you@example.com';
+        if (action === 'show') {
+          const s = await api.getDailySummary(client);
+          emit({ schedule: s }, describe(s));
+          return EXIT.OK;
+        }
+        if (action === 'on' || action === 'set') {
+          const s = await api.setDailySummary(client, {
+            hour: flags.hour !== undefined ? Number(flags.hour) : undefined,
+            timezone: typeof flags.timezone === 'string' ? flags.timezone : undefined,
+            recipients: flags.to ? listFlag(flags.to) : undefined,
+            active: true,
+          });
+          emit({ schedule: s }, describe(s));
+          return EXIT.OK;
+        }
+        if (action === 'off' || action === 'delete') {
+          const data = await api.deleteDailySummary(client);
+          emit(data, 'Daily summary turned off.');
+          return EXIT.OK;
+        }
+        if (action === 'send-now') {
+          const data = await api.sendDailySummaryNow(client);
+          emit(data, `Sent to ${data.sent.join(', ') || 'nobody'} (${data.due} due, ${data.overdue} overdue)${data.failed.length ? `; failed: ${data.failed.map((f) => `${f.to} (${f.error})`).join(', ')}` : ''}`);
+          return data.sent.length > 0 ? EXIT.OK : EXIT.FAILURE;
+        }
+        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances daily [show|on --hour 7 --to a@x|off|send-now]');
+      }
+
       case 'payloads': {
         const action = args[0] || 'list';
         if (action === 'list') {
@@ -822,4 +955,4 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
   }
 }
 
-export const EXTENDED_SUBCOMMANDS = ['connect', 'disconnect', 'consent', 'backfill', 'jobs', 'coverage', 'report', 'reports', 'statements', 'books', 'payloads', 'digest'];
+export const EXTENDED_SUBCOMMANDS = ['connect', 'disconnect', 'consent', 'backfill', 'jobs', 'coverage', 'report', 'reports', 'statements', 'books', 'payloads', 'digest', 'due', 'due-soon', 'recurring', 'due-day', 'daily'];

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,
@@ -359,3 +395,44 @@ export function setWeeklyDigest(
 ): Promise<WeeklyDigest>;
 export function deleteWeeklyDigest(client: CoinPayClient): Promise<{ success: boolean }>;
 export function sendWeeklyDigestNow(client: CoinPayClient): Promise<SendOutcome>;
+
+export interface DueItem {
+  source: 'projected' | 'scheduled';
+  payee: string;
+  amount: number | null;
+  owed: number | null;
+  cadence: string;
+  dueOn: string;
+  daysUntil: number;
+  status: 'overdue' | 'awaiting' | 'today' | 'soon' | 'paid';
+  accountId: string;
+  accountName: string;
+  scope: 'business' | 'personal';
+  isDebtService: boolean;
+}
+
+export interface DueSoon {
+  timezone: string;
+  today: string;
+  horizonDays: number;
+  items: DueItem[];
+  paid: DueItem[];
+  missed: Array<{ payee: string; amount: number; expectedOn: string; lastSeen: string; accountName: string }>;
+  totals: { due: number; overdue: number; unpriced: number };
+  recurring: {
+    charges: Array<{ payee: string; amount: number; cadence: string; occurrences: number; lastSeen: string; nextExpected: string; monthlyEquivalent: number; scope: 'business' | 'personal'; isDebtService: boolean; accountId: string; accountName: string }>;
+    monthlyTotal: number;
+    monthlyDebtService: number;
+  };
+  currency: string | null;
+}
+
+export function getDueSoon(client: CoinPayClient, opts?: { days?: number; timezone?: string }): Promise<DueSoon>;
+export function getDailySummary(client: CoinPayClient): Promise<WeeklyDigest | null>;
+export function setDailySummary(
+  client: CoinPayClient,
+  opts?: { weekdays?: number[]; hour?: number; timezone?: string; recipients?: string[]; active?: boolean },
+): Promise<WeeklyDigest>;
+export function deleteDailySummary(client: CoinPayClient): Promise<{ success: boolean }>;
+export function sendDailySummaryNow(client: CoinPayClient): Promise<{ sent: string[]; failed: Array<{ to: string; error: string }>; due: number; overdue: number }>;
+export function setAccountDueDay(client: CoinPayClient, accountId: string, opts: { day: number | null; amount?: number | string | null }): Promise<Record<string, unknown>>;