@profullstack/coinpay 0.12.1 → 0.15.0

package/src/finances-reports.d.ts

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

package/src/finances-reports.js

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

package/src/mcp.js

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

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,204 @@
+/** 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[];
+  /** 'tax' for an agency (FTB, IRS), 'brokerage' for a brokerage with no linked account (Webull); absent for a bank. */
+  kind?: 'tax' | 'brokerage';
+}
+
+export interface TaxSource {
+  key: string;
+  kind: 'tax';
+  name: string;
+  login: string;
+  lockoutMinutes: number;
+  cloudWarning?: string;
+}
+
+export interface BrokerageSource {
+  key: string;
+  kind: 'brokerage';
+  name: string;
+  login: string;
+  statements?: string;
+}
+
+export interface BrokerageDocumentInfo {
+  category: 'statement' | 'tax';
+  docType: 'form' | null;
+  taxYear: number | null;
+  periodLabel: string;
+  title: string;
+}
+
+export interface ThrottleLimits {
+  windowMs: number;
+  perWindow: number;
+  perDay: number;
+  defaultLockoutMinutes: number;
+  marginMinutes: number;
+}
+
+export type ThrottleVerdict = { ok: true } | { ok: false; reason: 'locked' | 'daily_limit' | 'window_limit'; retryAt: string; message: string };
+
+export interface TaxDocumentInfo {
+  docType: 'transcript' | 'notice' | 'letter' | 'form' | 'return' | 'other';
+  code: string | null;
+  taxYear: number | null;
+  noticeDate: string | null;
+  periodLabel: string;
+  title: string;
+}
+
+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' | 'locked';
+
+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 const HOST_KEYS: ReadonlyArray<[RegExp, string]>;
+export const TAX_SOURCES: readonly TaxSource[];
+export function taxSource(key: string): TaxSource | null;
+export const BROKERAGE_SOURCES: readonly BrokerageSource[];
+export function brokerageSource(key: string): BrokerageSource | null;
+export function isBrokerageSource(institution: { key: string; kind?: string; accounts?: readonly unknown[] } | null | undefined): boolean;
+export function sourceMode(institution: { key: string; kind?: string; accounts?: readonly unknown[] }): 'statements' | 'tax' | 'documents';
+export function standaloneSources(): Institution[];
+export function withStandaloneSources(institutions: readonly Institution[]): Institution[];
+export function isTaxSource(institution: { key: string; kind?: string; accounts?: readonly unknown[] } | null | undefined): boolean;
+export function keepCandidate(mode: 'statements' | 'tax' | 'documents', label: string, context: string, href: string | null): boolean;
+export function collectScript(mode?: 'statements' | 'tax' | 'documents'): string;
+export const COLLECT_TAX: string;
+export const OPEN_TAX_DOCS: string;
+export const COLLECT_DOCS: string;
+export const OPEN_DOCUMENTS: string;
+export const PAGE_TEXT: string;
+export function classifyTaxDocument(download: { label?: string; context?: string; suggestedName?: string }, fetchedAt?: Date): TaxDocumentInfo;
+export function keepTaxDocument(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+export function classifyBrokerageDocument(download: { label?: string; context?: string; suggestedName?: string }, fetchedAt?: Date): BrokerageDocumentInfo;
+export function keepBrokerageDocument(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+export const TAX_THROTTLE: ThrottleLimits;
+export function evaluateThrottle(source: { attempts?: ReadonlyArray<string | { at: string }>; lockedUntil?: string | null; lockReason?: string | null }, now?: Date, limits?: ThrottleLimits): ThrottleVerdict;
+export function detectLockout(text: string | null | undefined): { minutes: number | null } | null;
+export function lockoutUntil(found: { minutes: number | null } | null, now?: Date, limits?: ThrottleLimits, defaultMinutes?: number): string;
+export function throttlePath(home: string): string;
+export function loadThrottle(home: string): { sources: Record<string, { attempts: Array<{ at: string; kind: string }>; lockedUntil: string | null; lockReason: string | null }> };
+export function saveThrottle(ledger: unknown, home: string): void;
+export function checkLocalThrottle(home: string, key: string, now?: Date, limits?: ThrottleLimits): ThrottleVerdict;
+export function takeLocalAttempt(home: string, key: string, kind: string, now?: Date, limits?: ThrottleLimits): ThrottleVerdict;
+export function recordLocalLockout(home: string, key: string, until: string, reason?: string): unknown;
+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;
+    mode?: 'statements' | 'tax' | 'documents';
+    watchLockout?: boolean;
+    pauseMs?: number;
+  },
+): Promise<{ status: PageStatus; url: string; candidates: number; silent: string[]; lockout?: { minutes: number | null } }>;
+export function loginWindow(browser: Browser, url: string, options?: { onPageText?: (text: string) => unknown }): Promise<string | null>;
+export function assistWindow(browser: Browser, options: { start: string; onFile: (download: Download) => Promise<void> | void; onPageText?: (text: string) => unknown }): 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>;
+  fileDocument(options: Record<string, unknown>): Promise<{ document?: { id: string }; duplicate?: boolean }>;
+}>;
+export function retryImports(options: Record<string, unknown>): Promise<{ imported: number; skipped: number; failed: number }>;