@profullstack/coinpay 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.13.0] - 2026-10-04
+
+### Added
+- `coinpay login` signs in with OAuth 2.1: authorization code + PKCE over a
+  loopback redirect, as the public `coinpay-cli` client, with single-use
+  refresh tokens rotated before any command whose access token is about to
+  expire. `coinpay login --device` keeps the device flow for SSH.
+- `coinpay finances statements cloud [status|connect|fetch|schedule|forget]`:
+  CoinPay cloud statement fetching (Professional plan, free for admins).
+  `connect` opens CoinPay's cloud browser to sign in to the bank once; CoinPay
+  keeps the bank's session sealed and fetches every week.
+- MCP: `statements_cloud_status`, `statements_cloud_fetch`.
+- `@profullstack/coinpay/statements` export with types; `openBrowser` takes
+  `extraArgs` and `handleSignals`; `CoinPayClient#baseUrl` getter.
+
+### Fixed
+- The statement fetcher no longer attaches to Chrome's own omnibox page.
+
+## [0.12.1] - 2026-10-04
+
+### Fixed
+- `coinpay finances statements login|fetch|assist` no longer reports "profile is
+  open in another Chrome" after an interrupted run. A lock left by a process
+  that is gone, or now belongs to another program, is removed. Our own leftover
+  headless Chrome is stopped. A visible window is closed only with `--force`.
+  Ctrl+C or a crash now takes the Chrome it started down with it.
+
 ## [0.12.0] - 2026-10-04
 
 ### Added

package/bin/coinpay.js

@@ -165,6 +165,8 @@ const BOOLEAN_FLAGS = new Set([
   'wait',
   'strict',
   'headed',
+  'device',
+  'force',
   'setup-token-stdin',
   'overwrite',
   'no-pending',
@@ -379,7 +381,7 @@ ${colors.cyan}Commands:${colors.reset}
 
   ${colors.bright}auth${colors.reset}
     register              Register new merchant account
-    login                 Login to merchant account
+    login                 Sign in (OAuth 2.1 in your browser; --device on a machine without one)
     me                    Show current merchant info
 
   ${colors.bright}payment${colors.reset}
@@ -491,6 +493,10 @@ ${colors.cyan}Commands:${colors.reset}
     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
+    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 fetch [bank] [--wait]  Fetch now in the cloud; weekly by default
+    statements cloud schedule <bank> weekly|off | cloud forget <bank>
     books [queue]         Transactions awaiting category review (--status, --scope, --search)
     books confirm <id>    Confirm a row (--category, --tax, --scope, --note, --always makes a rule)
     books confirm-all     Accept every pending suggestion (--yes)
@@ -3780,7 +3786,26 @@ async function runInteractiveMenu() {
 // Headless login: ask the server for a device code, show a URL to approve on any
 // device, and poll until a merchant session token is minted and stored. No
 // password on this machine — works over SSH / on a server.
-async function handleLogin() {
+async function handleLogin(flags = {}) {
+  // OAuth 2.1 (authorization code + PKCE, loopback redirect, rotating refresh)
+  // unless asked for the device flow, which is what works over SSH.
+  if (!flags.device) {
+    const cfg = loadConfig();
+    const { loopbackLogin, toStoredSession } = await import('../src/oauth-login.js');
+    try {
+      const tokens = await loopbackLogin({ apiBase: cfg.baseUrl, log: (line) => console.log(line) });
+      cfg.oauth = toStoredSession(tokens);
+      cfg.jwtToken = cfg.oauth.accessToken;
+      saveConfig(cfg);
+      const me = await fetchMe();
+      print.success(me ? `Logged in as ${meLabel(me)} (OAuth 2.1)` : 'Logged in! Session saved to ' + CONFIG_FILE);
+      return;
+    } catch (err) {
+      print.error(`Browser sign-in failed: ${err.message}`);
+      print.info('On a machine without a local browser, use: coinpay login --device');
+      process.exit(1);
+    }
+  }
   const cfg = loadConfig();
   const base = (cfg.baseUrl || 'https://coinpayportal.com/api').replace(/\/$/, '');
 
@@ -3847,6 +3872,7 @@ async function handleLogin() {
 function handleLogout() {
   const cfg = loadConfig();
   delete cfg.jwtToken;
+  delete cfg.oauth;
   saveConfig(cfg);
   print.success('Logged out — session removed from ' + CONFIG_FILE);
 }
@@ -4488,9 +4514,21 @@ async function handleLightning(subcommand, args, flags) {
   }
 }
 
+    // An OAuth 2.1 session's access token lasts an hour: rotate it before any
+    // command that might use it, keeping the new single-use refresh token.
+    if (!['login', 'logout', 'help', 'version', '--version', '-v'].includes(command)) {
+      const sessionCfg = loadConfig();
+      if (sessionCfg.oauth) {
+        const { ensureFreshSession } = await import('../src/oauth-login.js');
+        if (!(await ensureFreshSession(sessionCfg, saveConfig))) {
+          print.warn('Your CoinPay sign-in expired. Run: coinpay login');
+        }
+      }
+    }
+
     switch (command) {
       case 'login':
-        await handleLogin();
+        await handleLogin(flags);
         break;
 
       case 'logout':
@@ -4582,7 +4620,12 @@ async function handleLightning(subcommand, args, flags) {
         await serveStdio({
           version: VERSION,
           getClient: async () => {
-            const token = process.env.COINPAY_SESSION_TOKEN || loadConfig().jwtToken;
+            const cfg = loadConfig();
+            if (cfg.oauth) {
+              const { ensureFreshSession } = await import('../src/oauth-login.js');
+              await ensureFreshSession(cfg, saveConfig);
+            }
+            const token = process.env.COINPAY_SESSION_TOKEN || cfg.jwtToken;
             if (!token) throw new Error('Not logged in: run `coinpay login` (finance tools need the merchant session)');
             return new CoinPayClient({ apiKey: token, baseUrl: getBaseUrl(), timeout: 120000 });
           },

package/package.json

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

package/src/client.js

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

package/src/finances-commands.js

@@ -123,7 +123,7 @@ function describeReport(report) {
   return parts.filter(Boolean).join(' · ');
 }
 
-const STATEMENT_FETCH_ACTIONS = new Set(['banks', 'login', 'fetch', 'assist', 'coverage', 'runs', 'local', 'retry']);
+const STATEMENT_FETCH_ACTIONS = new Set(['banks', 'login', 'fetch', 'assist', 'coverage', 'runs', 'local', 'retry', 'cloud']);
 
 function ago(iso) {
   if (!iso) return 'never';
@@ -132,6 +132,90 @@ function ago(iso) {
   return hours < 48 ? `${Math.round(hours)}h ago` : `${Math.round(hours / 24)}d ago`;
 }
 
+/**
+ * `coinpay finances statements cloud …`: the same statement fetching, run by
+ * CoinPay cloud with a bank session the merchant saved through CoinPay's
+ * cloud browser. Professional plan; free for admins.
+ */
+async function runCloudAction(rest, flags, { client, emit, progress }) {
+  const [sub = 'status', name] = rest;
+  const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+  if (sub === 'status' || sub === 'banks') {
+    const data = await api.getCloudStatements(client);
+    const lines = [data.access.allowed ? `CoinPay cloud: ${data.access.message}` : `CoinPay cloud is not available: ${data.access.message}`, ''];
+    for (const bank of data.banks) {
+      const c = bank.cloud;
+      lines.push(`${bank.key}  ${bank.name}  ·  ${!c ? 'not connected' : c.state === 'login_needed' ? 'needs sign-in' : c.state}${c ? `  ·  last fetch ${ago(c.lastFetchAt)}${c.lastStatus ? ` (${c.lastStatus})` : ''}  ·  ${c.schedule}` : ''}`);
+    }
+    const next = data.banks.find((b) => !b.cloud || b.cloud.state !== 'active');
+    if (data.access.allowed && next) lines.push('', `Next: coinpay finances statements cloud connect ${next.key}`);
+    emit(data, lines.join('\n'));
+    return EXIT.OK;
+  }
+
+  if (sub === 'connect') {
+    if (!name) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements cloud connect <bank> [--url <sign-in page>]');
+    const data = await api.connectCloudBank(client, { institutionKey: name, url: typeof flags.url === 'string' ? flags.url : undefined });
+    const { siteOrigin, openInBrowser } = await import('./oauth-login.js');
+    const viewer = new URL(data.viewerUrl, siteOrigin(client.baseUrl)).toString();
+    const opened = flags['no-open'] ? false : openInBrowser(viewer);
+    progress(`${opened ? 'Opened' : 'Open'} ${viewer}`);
+    progress('Sign in to your bank there, go to the page that lists your statements, and press Save. Waiting…');
+    for (;;) {
+      await pause(3000);
+      let live;
+      try {
+        live = await api.getCloudLiveSession(client, data.live.id);
+      } catch (err) {
+        if (err.status === 404) throw new CliExit(EXIT.FAILURE, 'The sign-in session is gone (the server restarted?). Run the command again.');
+        throw err;
+      }
+      if (live.status === 'saved') {
+        emit({ live }, `Saved. ${name} is connected to CoinPay cloud and its first fetch is queued: coinpay finances statements cloud status`);
+        return EXIT.OK;
+      }
+      if (['cancelled', 'expired', 'failed'].includes(live.status)) {
+        throw new CliExit(EXIT.FAILURE, `The sign-in session ended: ${live.status}${live.error ? ` (${live.error})` : ''}`);
+      }
+    }
+  }
+
+  if (sub === 'fetch') {
+    const data = await api.fetchCloudStatements(client, { institutionKey: name });
+    if (!flags.wait) {
+      emit(data, data.jobs.map((j) => `queued ${j.id} (${j.params?.institutionKey ?? ''})`).join('\n') + '\nFollow with: coinpay finances statements runs');
+      return EXIT.OK;
+    }
+    const jobs = new Map(data.jobs.map((j) => [j.id, j]));
+    const deadline = Date.now() + 20 * 60_000;
+    while (Date.now() < deadline && [...jobs.values()].some((j) => ['queued', 'running', 'waiting_for_budget'].includes(j.status))) {
+      await pause(5000);
+      for (const id of jobs.keys()) jobs.set(id, await api.getFinanceJob(client, id));
+    }
+    const done = [...jobs.values()];
+    emit({ jobs: done }, done.map((j) => `${j.params?.institutionKey ?? j.id}: ${j.status}${j.result ? `, ${j.result.imported ?? 0} imported, ${j.result.duplicates ?? 0} already had` : ''}${j.errorMessage ? ` (${j.errorMessage})` : ''}`).join('\n'));
+    return done.every((j) => j.status === 'completed') ? EXIT.OK : EXIT.STRICT;
+  }
+
+  if (sub === 'schedule') {
+    const value = rest[2];
+    if (!name || (value !== 'weekly' && value !== 'off')) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements cloud schedule <bank> weekly|off');
+    const data = await api.setCloudSchedule(client, name, value);
+    emit(data, `${name}: ${value === 'weekly' ? 'fetched every week' : 'schedule off'}`);
+    return EXIT.OK;
+  }
+
+  if (sub === 'forget' || sub === 'disconnect') {
+    if (!name) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements cloud forget <bank>');
+    const data = await api.disconnectCloudBank(client, name);
+    emit(data, data.note);
+    return EXIT.OK;
+  }
+
+  throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements cloud [status|connect <bank>|fetch [bank] [--wait]|schedule <bank> weekly|off|forget <bank>]');
+}
+
 /**
  * Downloading statements from the banks themselves (SimpleFIN has no
  * documents). Runs on this machine: each bank's session lives in a local
@@ -150,6 +234,7 @@ async function runStatementFetchAction(action, rest, flags, { client, out, emit,
   };
 
   try {
+    if (action === 'cloud') return await runCloudAction(rest, flags, { client, out, emit, progress });
     if (action === 'coverage') {
       const data = await api.getStatementCoverage(client, { months: months(flags.months, 12) });
       const mark = { have: '■', missing: '·', open: '○' };
@@ -201,7 +286,7 @@ async function runStatementFetchAction(action, rest, flags, { client, out, emit,
       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 });
+      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`);
@@ -239,7 +324,7 @@ async function runStatementFetchAction(action, rest, flags, { client, out, emit,
     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 });
+    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'));
     return results.every((r) => r.status === 'ok' && r.failed === 0) ? EXIT.OK : EXIT.STRICT;
   } catch (err) {

package/src/finances-reports.js

@@ -272,6 +272,40 @@ export async function getStatementCoverage(client, { months } = {}) {
   return call(client, `/finances/statements/coverage${query({ months })}`);
 }
 
+// ── Cloud statement fetching (Professional plan; free for admins) ──
+
+/** `{access, banks}`: whether cloud fetching is available, and each bank's cloud connection. */
+export async function getCloudStatements(client) {
+  return call(client, '/finances/statements/cloud');
+}
+
+/** Open a bank in CoinPay's cloud browser to sign in. Answers `{live, viewerUrl}`. */
+export async function connectCloudBank(client, { institutionKey, url } = {}) {
+  return call(client, '/finances/statements/cloud/connect', { method: 'POST', body: JSON.stringify({ institutionKey, url }) });
+}
+
+export async function getCloudLiveSession(client, liveId) {
+  const data = await call(client, `/finances/statements/cloud/live/${encodeURIComponent(liveId)}`);
+  return data.live;
+}
+
+export async function cancelCloudLiveSession(client, liveId) {
+  return call(client, `/finances/statements/cloud/live/${encodeURIComponent(liveId)}`, { method: 'DELETE' });
+}
+
+/** Queue cloud fetches for one bank or all connected ones. Answers `{jobs}`. */
+export async function fetchCloudStatements(client, { institutionKey } = {}) {
+  return call(client, '/finances/statements/cloud/fetch', { method: 'POST', body: JSON.stringify(institutionKey ? { institutionKey } : {}) });
+}
+
+export async function setCloudSchedule(client, institutionKey, schedule) {
+  return call(client, `/finances/statements/cloud/banks/${encodeURIComponent(institutionKey)}`, { method: 'PATCH', body: JSON.stringify({ schedule }) });
+}
+
+export async function disconnectCloudBank(client, institutionKey) {
+  return call(client, `/finances/statements/cloud/banks/${encodeURIComponent(institutionKey)}`, { method: 'DELETE' });
+}
+
 // ── Books ──
 
 /** Rows awaiting review (default) plus the category vocabularies. */

package/src/mcp.js

@@ -63,6 +63,23 @@ export const TOOLS = [
       });
     },
   },
+  {
+    name: 'statements_cloud_status',
+    description:
+      'CoinPay cloud statement fetching: whether this account has it (Professional plan, free for admins) and, per bank, whether a cloud session is connected, needs sign-in again, and when it last fetched. A bank must be connected by a person in the PWA or with `coinpay finances statements cloud connect <bank>`.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    handler: async (_args, { client }) => text(await reports.getCloudStatements(client)),
+  },
+  {
+    name: 'statements_cloud_fetch',
+    description: 'Queue a CoinPay cloud fetch of new PDF statements for one connected bank, or all of them. Runs on CoinPay servers; returns the jobs. Nothing runs on this machine.',
+    inputSchema: {
+      type: 'object',
+      properties: { bank: { type: 'string', description: 'Bank key such as "chase"; every connected bank when omitted' } },
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text(await reports.fetchCloudStatements(client, { institutionKey: args.bank })),
+  },
   {
     name: 'statements_fetch',
     description:

package/src/oauth-login.js

@@ -0,0 +1,174 @@
+/**
+ * `coinpay login` over OAuth 2.1: authorization code + PKCE, a loopback
+ * redirect, and rotating refresh tokens.
+ *
+ * The CLI is a public client (`coinpay-cli`, no secret). It listens on
+ * 127.0.0.1 at a free port, opens the browser at CoinPay's /api/oauth/authorize
+ * with an S256 code challenge and a random state, catches the redirect, checks
+ * the state, and exchanges the code with its verifier. The access token lasts
+ * an hour; the refresh token is single-use, so each refresh stores the new
+ * one. Over SSH, where the browser cannot reach this machine's loopback, the
+ * device flow (`coinpay login --device`) is the way in.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+
+export const CLI_CLIENT_ID = 'coinpay-cli';
+export const CLI_SCOPE = 'openid profile email merchant';
+
+const b64url = (buf) => Buffer.from(buf).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+
+/** A PKCE verifier (43+ chars of base64url) and its S256 challenge. */
+export function pkcePair() {
+  const verifier = b64url(randomBytes(32));
+  const challenge = b64url(createHash('sha256').update(verifier).digest());
+  return { verifier, challenge };
+}
+
+/** The site origin behind an API base such as https://coinpayportal.com/api. */
+export function siteOrigin(apiBase) {
+  return new URL(apiBase || 'https://coinpayportal.com/api').origin;
+}
+
+export function authorizeUrl({ origin, redirectUri, challenge, state, clientId = CLI_CLIENT_ID, scope = CLI_SCOPE }) {
+  const url = new URL('/api/oauth/authorize', origin);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('scope', scope);
+  url.searchParams.set('state', state);
+  url.searchParams.set('code_challenge', challenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  return url.toString();
+}
+
+async function tokenRequest(origin, params, fetchImpl = fetch) {
+  const res = await fetchImpl(new URL('/api/oauth/token', origin), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: new URLSearchParams(params).toString(),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok || !data.access_token) {
+    const err = new Error(data.error_description || data.error || `token endpoint answered ${res.status}`);
+    err.code = data.error || 'token_error';
+    throw err;
+  }
+  return data;
+}
+
+/** What the CLI keeps: the access token is also stored as `jwtToken`, which every command already sends. */
+export function toStoredSession(tokens, now = Date.now()) {
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token ?? null,
+    expiresAt: new Date(now + (Number(tokens.expires_in) || 3600) * 1000).toISOString(),
+    scope: tokens.scope ?? CLI_SCOPE,
+    clientId: CLI_CLIENT_ID,
+  };
+}
+
+export async function exchangeCode({ origin, code, verifier, redirectUri, clientId = CLI_CLIENT_ID, fetchImpl }) {
+  return tokenRequest(origin, { grant_type: 'authorization_code', code, code_verifier: verifier, redirect_uri: redirectUri, client_id: clientId }, fetchImpl);
+}
+
+export async function refreshTokens({ origin, refreshToken, clientId = CLI_CLIENT_ID, fetchImpl }) {
+  return tokenRequest(origin, { grant_type: 'refresh_token', refresh_token: refreshToken, client_id: clientId }, fetchImpl);
+}
+
+export function openInBrowser(url) {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const DONE_PAGE = (ok, message) => `<!doctype html><meta charset="utf-8"><title>CoinPay CLI</title>
+<body style="font-family:system-ui;background:#0b1120;color:#e5e7eb;display:grid;place-items:center;height:100vh;margin:0">
+<div><h1 style="font-size:20px">${ok ? 'Signed in to the CoinPay CLI' : 'Sign-in failed'}</h1><p>${message}</p></div></body>`;
+
+/**
+ * Run the whole loopback flow. Resolves with the token response.
+ * `open` is how the browser is launched; `log` prints the URL for a human.
+ */
+export async function loopbackLogin({ apiBase, open = openInBrowser, log = () => {}, timeoutMs = 5 * 60_000, fetchImpl } = {}) {
+  const origin = siteOrigin(apiBase);
+  const { verifier, challenge } = pkcePair();
+  const state = b64url(randomBytes(16));
+
+  let settle;
+  const result = new Promise((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  const server = createServer((req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    if (url.pathname !== '/callback') {
+      res.writeHead(404).end();
+      return;
+    }
+    const error = url.searchParams.get('error');
+    const code = url.searchParams.get('code');
+    if (url.searchParams.get('state') !== state) {
+      res.writeHead(400, { 'Content-Type': 'text/html' }).end(DONE_PAGE(false, 'The response did not match this login. Run coinpay login again.'));
+      settle.reject(new Error('state mismatch: the callback was not for this login'));
+      return;
+    }
+    if (error || !code) {
+      res.writeHead(400, { 'Content-Type': 'text/html' }).end(DONE_PAGE(false, error === 'access_denied' ? 'You declined.' : 'No code came back.'));
+      settle.reject(new Error(error === 'access_denied' ? 'access denied' : `authorization failed: ${error || 'no code'}`));
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'text/html' }).end(DONE_PAGE(true, 'You can close this tab and go back to the terminal.'));
+    settle.resolve(code);
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const redirectUri = `http://127.0.0.1:${server.address().port}/callback`;
+  const url = authorizeUrl({ origin, redirectUri, challenge, state });
+  const timer = setTimeout(() => settle.reject(new Error('timed out waiting for the browser sign-in')), timeoutMs);
+  try {
+    const opened = open(url);
+    log(opened ? `Opening your browser to sign in. If it did not open, visit:\n  ${url}` : `Open this URL to sign in:\n  ${url}`);
+    const code = await result;
+    return await exchangeCode({ origin, code, verifier, redirectUri, fetchImpl });
+  } finally {
+    clearTimeout(timer);
+    server.close();
+  }
+}
+
+/**
+ * Before any command: if the stored OAuth access token is within a minute of
+ * expiring, rotate it. Mutates and saves `cfg`. Returns false when the
+ * refresh token is no longer good (sign in again).
+ */
+export async function ensureFreshSession(cfg, saveConfig, { now = Date.now(), fetchImpl } = {}) {
+  const session = cfg.oauth;
+  if (!session || !session.refreshToken) return true;
+  if (Date.parse(session.expiresAt) - now > 60_000) return true;
+  try {
+    const tokens = await refreshTokens({ origin: siteOrigin(cfg.baseUrl), refreshToken: session.refreshToken, clientId: session.clientId || CLI_CLIENT_ID, fetchImpl });
+    cfg.oauth = toStoredSession(tokens, now);
+    cfg.jwtToken = cfg.oauth.accessToken;
+    saveConfig(cfg);
+    return true;
+  } catch (err) {
+    if (err.code === 'invalid_grant') {
+      delete cfg.oauth;
+      delete cfg.jwtToken;
+      saveConfig(cfg);
+      return false;
+    }
+    return true; // a network blip: let the command try with what it has
+  }
+}

package/src/statements-fetch.d.ts

@@ -0,0 +1,123 @@
+/** Types for `@profullstack/coinpay/statements` (src/statements-fetch.js). */
+
+export class StatementFetchError extends Error {}
+
+export interface FetcherAccount {
+  id: string;
+  name: string;
+  last4: string | null;
+  institution: string;
+}
+
+export interface Institution {
+  key: string;
+  name: string;
+  url: string | null;
+  accounts: FetcherAccount[];
+}
+
+export interface Period {
+  month: string;
+  from: string | null;
+  to: string | null;
+}
+
+export interface ImportSpan {
+  period?: string;
+  from?: string;
+  to?: string;
+  cycle?: 'custom';
+}
+
+export interface CdpEvent {
+  method: string;
+  params: Record<string, unknown>;
+  sessionId?: string;
+}
+
+export interface Cdp {
+  send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<Record<string, unknown>>;
+  on(listener: (event: CdpEvent) => void): () => void;
+  waitFor(method: string, sessionId: string, timeoutMs: number): Promise<boolean>;
+}
+
+export interface Browser {
+  cdp: Cdp;
+  exited: Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface Download {
+  bytes: Buffer;
+  suggestedName: string;
+  label: string;
+  context: string;
+  key: string | null;
+}
+
+export type PageStatus = 'ok' | 'login_needed' | 'no_statements';
+
+export function lastFour(name: string): string | null;
+export function slug(value: string): string;
+export function institutionKey(domain: string | null | undefined, name: string | null | undefined): string;
+export function groupInstitutions(accounts: ReadonlyArray<{ id: string; name: string; org_name?: string | null; org_domain?: string | null; is_hidden?: boolean }>): Institution[];
+export function pickInstitution(institutions: readonly Institution[], name: string): Institution;
+export const DRIVERS: ReadonlyArray<{ key: string; login: string; statements?: string }>;
+export function startUrls(institution: { key: string; url: string | null }, learnt?: string | null): { login: string | null; fetch: string | null };
+export function isSignInUrl(url: string): boolean;
+export function findDates(source: string | null | undefined): { date: string; precise: boolean }[];
+export function periodOf(...sources: ReadonlyArray<string | null | undefined>): Period | null;
+export function matchAccount(accounts: readonly FetcherAccount[], ...sources: ReadonlyArray<string | null | undefined>): FetcherAccount | null;
+export function importPeriod(period: Period | null): ImportSpan | null;
+export function candidateKey(candidate: { label: string; context: string; href: string | null }): string;
+export function isPdf(bytes: Uint8Array): boolean;
+export function sha256(bytes: Uint8Array): string;
+export function statementsHome(env?: Record<string, string | undefined>): string;
+export function profileDir(key: string, home?: string): string;
+export function signedIn(key: string, home?: string): boolean;
+export function findChrome(env?: Record<string, string | undefined>, home?: string): string | null;
+export const NO_CHROME: string;
+export function profileLock(profile: string): { host: string; pid: number } | null;
+export function releaseProfile(profile: string, options?: { force?: boolean }): Promise<'free' | 'stale' | 'stopped'>;
+export function preferPdfDownloads(profile: string): void;
+export function openBrowser(options: {
+  chrome: string;
+  profile: string;
+  headless?: boolean;
+  timeoutMs?: number;
+  env?: Record<string, string | undefined>;
+  force?: boolean;
+  extraArgs?: string[];
+  handleSignals?: boolean;
+}): Promise<Browser>;
+export const SIGNED_OUT: string;
+export const OPEN_STATEMENTS: string;
+export const COLLECT: string;
+export const SECOND_STEP: string;
+export const CLICK_RECORDER: string;
+export function clickScript(index: number): string;
+export function fetchInstitution(
+  browser: Browser,
+  options: {
+    start: string;
+    seen?: Set<string>;
+    since?: string | null;
+    max?: number;
+    renderMs?: number;
+    onFile: (download: Download) => Promise<void> | void;
+    log?: (line: string) => void;
+  },
+): Promise<{ status: PageStatus; url: string; candidates: number; silent: string[] }>;
+export function loginWindow(browser: Browser, url: string): Promise<string | null>;
+export function assistWindow(browser: Browser, options: { start: string; onFile: (download: Download) => Promise<void> | void }): Promise<number>;
+export function loadLocal(home?: string): { institutions: Record<string, Record<string, unknown>>; entries: Record<string, unknown>[] };
+export function saveLocal(state: unknown, home?: string): void;
+export function archive(home: string, institution: Institution, account: FetcherAccount | null, period: Period | null, suggestedName: string, bytes: Uint8Array): string;
+export function keepStatement(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+export function runStatementFetch(options: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+export function clientApi(client: unknown): Promise<{
+  listAccounts(): Promise<unknown[]>;
+  importStatement(options: Record<string, unknown>): Promise<unknown>;
+  reportRun(run: Record<string, unknown>): Promise<unknown>;
+}>;
+export function retryImports(options: Record<string, unknown>): Promise<{ imported: number; skipped: number; failed: number }>;

package/src/statements-fetch.js

@@ -23,10 +23,10 @@
  * download or PDF control) and says what it saw. Needs Node 22+ (WebSocket).
  */
 
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { accessSync, chmodSync, constants, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
+import { accessSync, chmodSync, constants, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, hostname, tmpdir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 
 export class StatementFetchError extends Error {
@@ -420,10 +420,83 @@ export function preferPdfDownloads(profile) {
  * cookies only reach disk then: a killed Chrome forgets a session the bank
  * refreshed during the run.
  */
-export async function openBrowser({ chrome, profile, headless = true, timeoutMs = 30_000, env = process.env }) {
+/**
+ * Who holds a profile. Chrome marks a profile in use with a SingletonLock
+ * symlink whose target is "<hostname>-<pid>" (Linux and macOS).
+ */
+export function profileLock(profile) {
+  try {
+    const target = readlinkSync(join(profile, 'SingletonLock'));
+    const dash = target.lastIndexOf('-');
+    const pid = Number(target.slice(dash + 1));
+    return dash > 0 && Number.isInteger(pid) ? { host: target.slice(0, dash), pid } : null;
+  } catch {
+    return null;
+  }
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+/** The command line of a process, or '' when it cannot be read. */
+function commandLine(pid) {
+  try {
+    return readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
+  } catch {
+    const ps = spawnSync('ps', ['-o', 'args=', '-p', String(pid)], { encoding: 'utf8' });
+    return ps.status === 0 ? ps.stdout : '';
+  }
+}
+
+function removeLock(profile) {
+  for (const name of ['SingletonLock', 'SingletonSocket', 'SingletonCookie']) rmSync(join(profile, name), { force: true });
+}
+
+/**
+ * Make sure no other Chrome holds `profile` before we start one on it.
+ *
+ * A login or fetch that was interrupted (Ctrl+C, a closed terminal, a crash)
+ * can leave Chrome running on the profile, or a lock pointing at a process
+ * that is gone. Chrome then hands every new launch to the old instance and
+ * exits, which looked like "open in another Chrome" forever. A dead or
+ * reused pid is a stale lock and is removed; our own leftover headless Chrome
+ * is stopped; a visible window is only closed with `force`.
+ */
+export async function releaseProfile(profile, { force = false } = {}) {
+  const lock = profileLock(profile);
+  if (!lock) return 'free';
+  if (lock.host !== hostname()) {
+    if (!force) throw new StatementFetchError(`the ${profile} profile is marked in use by ${lock.host}; if that machine is not using it, pass --force`);
+    removeLock(profile);
+    return 'stale';
+  }
+  const cmd = alive(lock.pid) ? commandLine(lock.pid) : '';
+  if (!cmd.includes(`--user-data-dir=${profile}`)) {
+    removeLock(profile);
+    return 'stale';
+  }
+  if (!cmd.includes('--headless') && !force) {
+    throw new StatementFetchError(`a Chrome window (pid ${lock.pid}) still has the ${basename(profile)} profile open; close it, or pass --force to close it for you`);
+  }
+  process.kill(lock.pid, 'SIGTERM');
+  for (let i = 0; i < 50 && alive(lock.pid); i += 1) await sleep(100);
+  if (alive(lock.pid)) process.kill(lock.pid, 'SIGKILL');
+  for (let i = 0; i < 20 && alive(lock.pid); i += 1) await sleep(100);
+  removeLock(profile);
+  return 'stopped';
+}
+
+export async function openBrowser({ chrome, profile, headless = true, timeoutMs = 30_000, env = process.env, force = false, extraArgs = [], handleSignals = true }) {
   if (typeof WebSocket === 'undefined') throw new StatementFetchError('statement fetching needs Node 22 or newer (it drives Chrome over a WebSocket)');
   if (!chrome || !isExecutable(chrome)) throw new StatementFetchError(chrome ? `${chrome} is not an executable` : NO_CHROME);
   mkdirSync(profile, { recursive: true, mode: 0o700 });
+  await releaseProfile(profile, { force });
   preferPdfDownloads(profile);
   const sandbox = !(env.CHROME_NO_SANDBOX || process.getuid?.() === 0);
   const args = [
@@ -435,10 +508,27 @@ export async function openBrowser({ chrome, profile, headless = true, timeoutMs
     '--disable-background-networking',
     '--window-size=1280,900',
     ...(sandbox ? [] : ['--no-sandbox']),
+    ...extraArgs,
     'about:blank',
   ];
   const child = spawn(chrome, args, { env, stdio: ['ignore', 'ignore', 'pipe'] });
   const exited = new Promise((resolve) => child.once('exit', () => resolve()));
+  // Never leave Chrome holding the profile when we go: an orphan is what
+  // makes the next run see the profile "open in another Chrome".
+  const onExit = () => { try { child.kill('SIGKILL'); } catch { /* gone */ } };
+  const onSignal = (signal) => {
+    onExit();
+    detach();
+    process.kill(process.pid, signal);
+  };
+  const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+  const detach = () => {
+    process.removeListener('exit', onExit);
+    for (const signal of signals) process.removeListener(signal, onSignal);
+  };
+  process.once('exit', onExit);
+  if (handleSignals) for (const signal of signals) process.once(signal, onSignal);
+  exited.then(detach);
   const url = await new Promise((resolve, reject) => {
     let stderr = '';
     const timer = setTimeout(() => reject(new StatementFetchError(`${chrome} did not start within ${timeoutMs / 1000}s\n${stderr}`)), timeoutMs);
@@ -452,8 +542,8 @@ export async function openBrowser({ chrome, profile, headless = true, timeoutMs
     });
     child.on('exit', (code) => {
       clearTimeout(timer);
-      const locked = /SingletonLock|ProcessSingleton/.test(stderr);
-      reject(new StatementFetchError(locked ? `the ${profile} profile is open in another Chrome; close that window first` : `${chrome} exited with ${code} before it was ready\n${stderr.trim()}`));
+      const locked = /SingletonLock|ProcessSingleton|existing browser session/i.test(stderr);
+      reject(new StatementFetchError(locked ? `another Chrome took over the ${basename(profile)} profile as this one started; run the command again, or pass --force` : `${chrome} exited with ${code} before it was ready\n${stderr.trim()}`));
     });
   }).catch((err) => {
     child.kill();
@@ -588,7 +678,7 @@ export const CLICK_RECORDER = `document.addEventListener('click', (event) => {
 
 async function attachPage(cdp) {
   const { targetInfos } = await cdp.send('Target.getTargets');
-  let targetId = (targetInfos.find((t) => t.type === 'page') || {}).targetId;
+  let targetId = (targetInfos.find((t) => t.type === 'page' && !String(t.url || '').startsWith('chrome')) || {}).targetId;
   if (!targetId) ({ targetId } = await cdp.send('Target.createTarget', { url: 'about:blank' }));
   const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true });
   await cdp.send('Page.enable', {}, sessionId);
@@ -847,7 +937,7 @@ export async function keepStatement({ institution, download, state, home, import
  * `api` carries `listAccounts()`, `importStatement(opts)` and `reportRun(run)`.
  * Returns one summary per bank; never throws for one bank's failure.
  */
-export async function runStatementFetch({ api, banks = [], since = null, max = 24, renderMs = 25_000, headless = true, chrome = findChrome(), home = statementsHome(), log = () => {}, client = 'coinpay-cli' }) {
+export async function runStatementFetch({ api, banks = [], since = null, max = 24, renderMs = 25_000, headless = true, chrome = findChrome(), home = statementsHome(), log = () => {}, client = 'coinpay-cli', force = false }) {
   const institutions = groupInstitutions(await api.listAccounts());
   if (!institutions.length) throw new StatementFetchError('no linked accounts; connect a bank in CoinPay first');
   const chosen = banks.length ? banks.map((name) => pickInstitution(institutions, name)) : institutions.filter((entry) => signedIn(entry.key, home));
@@ -868,7 +958,7 @@ export async function runStatementFetch({ api, banks = [], since = null, max = 2
         summary.status = 'login_needed';
         summary.message = `not signed in: coinpay finances statements login ${institution.key}`;
       } else {
-        browser = await openBrowser({ chrome, profile: profileDir(institution.key, home), headless });
+        browser = await openBrowser({ chrome, profile: profileDir(institution.key, home), headless, force });
         const seen = new Set(state.entries.filter((entry) => entry.institution === institution.key && entry.key).map((entry) => entry.key));
         const page = await fetchInstitution(browser, {
           start, seen, since, max, renderMs, log,