@profullstack/coinpay 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.12.0] - 2026-10-04
+
+### Added
+- `coinpay finances statements banks|login|fetch|assist|coverage|runs|local|retry`:
+  download the original PDF statements behind every linked account from the
+  banks themselves (SimpleFIN has none) and import them into the statement
+  library with their account and period. Bank sessions stay in local Chrome
+  profiles; `fetch` exits 3 when a bank needs signing in again.
+- `coinpay mcp`: a stdio MCP server with finance and statement tools,
+  including `statements_fetch`.
+- SDK: `reportStatementFetchRun`, `listStatementFetchRuns`, `getStatementCoverage`.
+
+## [0.11.2] - 2026-09-16
+
+### Added
+- Invoice creation and due dates remain visible in the finance TUI table;
+  selected invoices show created, due, sent and paid dates in the detail panel.
+- Right-side details for selected accounts, ledger rows, crypto and card
+  payments, invoices, escrows and debt accounts.
+
+### Fixed
+- Row clicks select the correct record after scrolling or resizing. Keyboard
+  navigation follows the last selected invoice or escrow table.
+
 ## [0.11.0] - 2026-09-12
 
 ### Added

package/README.md

@@ -758,6 +758,32 @@ const snapshot = await collectFinanceSnapshot(client, { days: 30 });
 console.log(snapshot.earnings.netUsd, snapshot.bank.liabilities, snapshot.invoices.totals.overdue);
 ```
 
+#### Statements from the banks
+
+SimpleFIN carries transactions, not the PDF statements. The CLI downloads
+them from each bank on your machine and files them in the statement library:
+
+```bash
+coinpay finances statements login chase    # once per bank, in a window; no password is stored
+coinpay finances statements fetch          # every new statement, imported with its account and period
+coinpay finances statements coverage       # which account-months are still missing
+```
+
+Each bank's session lives in a local Chrome profile under
+`~/.coinpay/statements`. `fetch` exits 3 when a bank needs signing in again.
+Needs Node 22+ and Chrome or Chromium. See
+[docs/STATEMENTS.md](https://github.com/profullstack/coinpayportal/blob/master/docs/STATEMENTS.md).
+
+### MCP
+
+```bash
+claude mcp add coinpay -- coinpay mcp
+```
+
+`coinpay mcp` is a stdio MCP server using your `coinpay login` session. Tools:
+`finance_accounts`, `statements_list`, `statements_coverage`,
+`statements_fetch_runs`, `statements_banks` and `statements_fetch`.
+
 ---
 
 ## Webhook Integration

package/bin/coinpay.js

@@ -164,6 +164,7 @@ const BOOLEAN_FLAGS = new Set([
   // finances reports / statements
   'wait',
   'strict',
+  'headed',
   'setup-token-stdin',
   'overwrite',
   'no-pending',
@@ -483,6 +484,13 @@ ${colors.cyan}Commands:${colors.reset}
     statements import <pdf>  Keep an original bank statement (--account, --period|--from/--to)
     statements list|get|download|reconcile|delete
                           Statement library; reconcile takes --report --opening --closing --currency
+    statements banks      Linked banks: signed in for statement downloads? last fetch?
+    statements login <bank>  Sign in once in a window (no password is stored; Chrome profile on this machine)
+    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 coverage   Which account-months have a statement (--months 12)
+    statements runs|local|retry  Fetch history, the local archive, re-import what failed
     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)
@@ -534,6 +542,8 @@ ${colors.cyan}Commands:${colors.reset}
 
   ${colors.bright}self${colors.reset}
     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
@@ -4566,6 +4576,20 @@ async function handleLightning(subcommand, args, flags) {
         await handleFinances(subcommand, args, flags);
         break;
 
+      case 'mcp': {
+        // stdout is the protocol channel: nothing else may print to it.
+        const { serveStdio } = await import('../src/mcp.js');
+        await serveStdio({
+          version: VERSION,
+          getClient: async () => {
+            const token = process.env.COINPAY_SESSION_TOKEN || loadConfig().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 });
+          },
+        });
+        break;
+      }
+
       case 'tui':
       case 'dashboard':
         await handleFinances('tui', [subcommand, ...args].filter(Boolean), flags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.11.1",
+  "version": "0.12.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

@@ -123,6 +123,131 @@ function describeReport(report) {
   return parts.filter(Boolean).join(' · ');
 }
 
+const STATEMENT_FETCH_ACTIONS = new Set(['banks', 'login', 'fetch', 'assist', 'coverage', 'runs', 'local', 'retry']);
+
+function ago(iso) {
+  if (!iso) return 'never';
+  const hours = (Date.now() - Date.parse(iso)) / 3_600_000;
+  if (hours < 1) return 'just now';
+  return hours < 48 ? `${Math.round(hours)}h ago` : `${Math.round(hours / 24)}d ago`;
+}
+
+/**
+ * Downloading statements from the banks themselves (SimpleFIN has no
+ * documents). Runs on this machine: each bank's session lives in a local
+ * Chrome profile under ~/.coinpay/statements and never reaches CoinPay.
+ * `fetch` exits 3 when any bank needs signing in again or showed nothing.
+ */
+async function runStatementFetchAction(action, rest, flags, { client, out, emit, progress }) {
+  const sf = await import('./statements-fetch.js');
+  const home = sf.statementsHome();
+  const chrome = typeof flags.chrome === 'string' ? flags.chrome : sf.findChrome();
+  const months = (value, fallback) => {
+    if (value === undefined) return fallback;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > 36) throw new CliExit(EXIT.INVALID, '--months is a whole number from 1 to 36');
+    return n;
+  };
+
+  try {
+    if (action === 'coverage') {
+      const data = await api.getStatementCoverage(client, { months: months(flags.months, 12) });
+      const mark = { have: '■', missing: '·', open: '○' };
+      const lines = data.accounts.map((a) => `${a.months.map((m) => mark[m.state]).join('')}  ${a.institutionKey}  ${a.accountName}${a.missing ? `  (${a.missing} missing)` : ''}`);
+      const fetchers = (data.fetchers || []).map((r) => `${r.institutionKey}: ${r.status} ${ago(r.finishedAt)}${r.message ? ` (${r.message})` : ''}`);
+      emit(data, [`${data.months[0]} … ${data.months[data.months.length - 1]}   ■ have  · missing  ○ this month`, ...lines, '', `${data.missing} account-months missing`, ...(fetchers.length ? ['', 'Last fetch per bank:', ...fetchers] : ['', 'No statement fetch has run yet: coinpay finances statements banks'])].join('\n'));
+      return EXIT.OK;
+    }
+    if (action === 'runs') {
+      const data = await api.listStatementFetchRuns(client, { limit: flags.limit ? Number(flags.limit) : undefined });
+      emit(data, data.runs.length ? data.runs.map((r) => `${r.finishedAt}  ${r.institutionKey}  ${r.status}  ${r.filed} imported, ${r.duplicates} had, ${r.unmatched} unmatched${r.message ? `  ${r.message}` : ''}`).join('\n') : 'No statement fetch has run yet.');
+      return EXIT.OK;
+    }
+    if (action === 'local') {
+      const state = sf.loadLocal(home);
+      emit({ home, entries: state.entries }, state.entries.length
+        ? state.entries.map((e) => `${e.statementId ? 'imported ' : 'local    '} ${e.path}${e.importError ? `  (${e.importError})` : ''}`).join('\n')
+        : `Nothing downloaded yet (${home})`);
+      return EXIT.OK;
+    }
+    if (action === 'retry') {
+      const result = await sf.retryImports({ api: await sf.clientApi(client), home, log: progress });
+      emit(result, `${result.imported} imported, ${result.skipped} skipped (no account or period), ${result.failed} failed`);
+      return result.failed ? EXIT.FAILURE : EXIT.OK;
+    }
+
+    const bound = await sf.clientApi(client);
+    const institutions = sf.groupInstitutions(await bound.listAccounts());
+    if (action === 'banks') {
+      const state = sf.loadLocal(home);
+      let latest = [];
+      try {
+        latest = (await api.listStatementFetchRuns(client, { limit: 200 })).latest || [];
+      } 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 }));
+      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}`] : []),
+        ...(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 (!chrome) throw new CliExit(EXIT.FAILURE, sf.NO_CHROME);
+      const institution = sf.pickInstitution(institutions, rest[0]);
+      const state = sf.loadLocal(home);
+      const local = (state.institutions[institution.key] ||= {});
+      const urls = sf.startUrls(institution, local.start);
+      const browser = await sf.openBrowser({ chrome, profile: sf.profileDir(institution.key, home), headless: false });
+      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);
+        await browser.close();
+        local.loggedInAt = new Date().toISOString();
+        if (last) local.start = last;
+        sf.saveLocal(state, home);
+        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.`);
+      let kept = 0;
+      try {
+        await sf.assistWindow(browser, {
+          start: urls.fetch,
+          onFile: async (download) => {
+            const result = 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);
+          },
+        });
+      } finally {
+        await browser.close();
+      }
+      emit({ bank: institution.key, imported: kept }, `${kept} imported`);
+      return EXIT.OK;
+    }
+    // fetch
+    const since = typeof flags.since === 'string' ? flags.since : null;
+    if (since && !/^\d{4}-(0[1-9]|1[0-2])$/.test(since)) throw new CliExit(EXIT.INVALID, '--since is YYYY-MM');
+    const max = flags.max !== undefined ? Number(flags.max) : 24;
+    if (!Number.isInteger(max) || max < 1 || max > 500) throw new CliExit(EXIT.INVALID, '--max is a whole number from 1 to 500');
+    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 });
+    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'));
+    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);
+    throw err;
+  }
+}
+
 /**
  * Run one subcommand. `ctx` supplies the client and the output channels.
  * @returns {Promise<number>} an exit code
@@ -414,7 +539,8 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
           emit(data, data.note);
           return EXIT.OK;
         }
-        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements [import <file>|list|get <id>|download <id>|reconcile <id>|delete <id>]');
+        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]');
       }
 
       case 'books': {

package/src/finances-reports.js

@@ -256,6 +256,22 @@ export async function reconcileFinanceStatement(client, statementId, {
   return data.reconciliation;
 }
 
+/** 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) });
+  return data.run;
+}
+
+/** `{latest, runs}`: the newest fetch run per bank, and the recent history. */
+export async function listStatementFetchRuns(client, { limit } = {}) {
+  return call(client, `/finances/statements/fetch-runs${query({ limit })}`);
+}
+
+/** Which of the last `months` months have a statement, per account, plus each bank's latest fetch. */
+export async function getStatementCoverage(client, { months } = {}) {
+  return call(client, `/finances/statements/coverage${query({ months })}`);
+}
+
 // ── Books ──
 
 /** Rows awaiting review (default) plus the category vocabularies. */