@profullstack/coinpay 0.11.2 → 0.12.0

package/CHANGELOG.md

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

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.2",
+  "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. */

package/src/mcp.js

@@ -0,0 +1,152 @@
+/**
+ * `coinpay mcp`: CoinPay as an MCP server over stdio.
+ *
+ * Newline-delimited JSON-RPC 2.0, no SDK dependency: initialize, ping,
+ * tools/list and tools/call are the whole surface. stdout carries protocol
+ * messages only; anything human goes to stderr.
+ *
+ * It runs on the merchant's machine with their `coinpay login` session, which
+ * is what lets `statements_fetch` work at all: the bank sessions behind it
+ * live in local Chrome profiles that CoinPay's servers never see.
+ */
+
+import { createInterface } from 'node:readline';
+
+import * as reports from './finances-reports.js';
+import { listFinanceAccounts } from './finances.js';
+import * as sf from './statements-fetch.js';
+
+export const PROTOCOL_VERSION = '2025-06-18';
+
+const text = (value) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] });
+
+/** Every tool: name, description, JSON schema, and a handler taking (args, ctx). */
+export const TOOLS = [
+  {
+    name: 'finance_accounts',
+    description: 'List the linked bank and card accounts (institution, name, kind, balance, id).',
+    inputSchema: { type: 'object', properties: { includeHidden: { type: 'boolean' } }, additionalProperties: false },
+    handler: async (args, { client }) => text({ accounts: await listFinanceAccounts(client, { includeHidden: args.includeHidden === true }) }),
+  },
+  {
+    name: 'statements_list',
+    description: 'List PDF statements in the CoinPay statement library, optionally for one account or period (2026-08, 2026-Q3).',
+    inputSchema: {
+      type: 'object',
+      properties: { accountId: { type: 'string' }, period: { type: 'string' }, limit: { type: 'integer', minimum: 1, maximum: 500 } },
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text({ statements: await reports.listFinanceStatements(client, { accountId: args.accountId, period: args.period, limit: args.limit }) }),
+  },
+  {
+    name: 'statements_coverage',
+    description: 'For each account, which of the last N months have a statement (have), which do not (missing), and the current month (open); plus the latest statement fetch per bank.',
+    inputSchema: { type: 'object', properties: { months: { type: 'integer', minimum: 1, maximum: 36 } }, additionalProperties: false },
+    handler: async (args, { client }) => text(await reports.getStatementCoverage(client, { months: args.months })),
+  },
+  {
+    name: 'statements_fetch_runs',
+    description: 'Recent statement fetch runs: per bank, ok / login_needed / no_statements / error, with counts.',
+    inputSchema: { type: 'object', properties: { limit: { type: 'integer', minimum: 1, maximum: 1000 } }, additionalProperties: false },
+    handler: async (args, { client }) => text(await reports.listStatementFetchRuns(client, { limit: args.limit })),
+  },
+  {
+    name: 'statements_banks',
+    description: 'The linked banks and whether each is signed in on this machine for statement downloads. A bank that is not must be signed in by a person: `coinpay finances statements login <bank>`.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    handler: async (_args, { client, home }) => {
+      const institutions = sf.groupInstitutions(await listFinanceAccounts(client));
+      const state = sf.loadLocal(home);
+      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] })),
+      });
+    },
+  },
+  {
+    name: 'statements_fetch',
+    description:
+      'Download every new PDF statement from the signed-in banks (or the ones named) in a headless browser on this machine and import each into the CoinPay statement library. Takes minutes. Banks needing a sign-in are reported, never signed in to.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        banks: { type: 'array', items: { type: 'string' }, description: 'Bank keys such as "chase"; all signed-in banks when omitted' },
+        since: { type: 'string', pattern: '^\\d{4}-(0[1-9]|1[0-2])$', description: 'Skip statements that closed before this month (YYYY-MM)' },
+        max: { type: 'integer', minimum: 1, maximum: 500, description: 'At most this many new statements per bank (default 24)' },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args, { client, home, log }) => {
+      const results = await sf.runStatementFetch({
+        api: await sf.clientApi(client),
+        banks: Array.isArray(args.banks) ? args.banks : [],
+        since: args.since || null,
+        max: args.max || 24,
+        home,
+        log,
+        client: 'coinpay-mcp',
+      });
+      return { ...text({ banks: results }), isError: false };
+    },
+  },
+];
+
+/** Answer one JSON-RPC message; null for a notification. */
+export async function handleMessage(message, ctx) {
+  const { id, method, params = {} } = message || {};
+  const reply = (result) => (id === undefined ? null : { jsonrpc: '2.0', id, result });
+  const fail = (code, msg) => (id === undefined ? null : { jsonrpc: '2.0', id, error: { code, message: msg } });
+
+  switch (method) {
+    case 'initialize':
+      return reply({
+        protocolVersion: typeof params.protocolVersion === 'string' ? params.protocolVersion : PROTOCOL_VERSION,
+        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>`.',
+      });
+    case 'notifications/initialized':
+    case 'notifications/cancelled':
+      return null;
+    case 'ping':
+      return reply({});
+    case 'tools/list':
+      return reply({ tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+    case 'tools/call': {
+      const tool = TOOLS.find((t) => t.name === params.name);
+      if (!tool) return fail(-32602, `Unknown tool: ${params.name}`);
+      try {
+        const client = await ctx.getClient();
+        return reply(await tool.handler(params.arguments || {}, { ...ctx, client }));
+      } catch (err) {
+        return reply({ ...text(`${err && err.message ? err.message : String(err)}${err && err.code ? ` (${err.code})` : ''}`), isError: true });
+      }
+    }
+    default:
+      return id === undefined ? null : fail(-32601, `Method not found: ${method}`);
+  }
+}
+
+/** Serve on stdin/stdout until stdin closes. Calls run concurrently; replies carry their id. */
+export async function serveStdio({ getClient, version, home = sf.statementsHome(), input = process.stdin, output = process.stdout, errOut = (line) => process.stderr.write(`${line}\n`) }) {
+  const ctx = { getClient, version, home, log: errOut };
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  const pending = new Set();
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      output.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } })}\n`);
+      continue;
+    }
+    const task = handleMessage(message, ctx).then((response) => {
+      if (response) output.write(`${JSON.stringify(response)}\n`);
+    });
+    pending.add(task);
+    task.finally(() => pending.delete(task));
+  }
+  await Promise.all(pending);
+}