@profullstack/coinpay 0.13.0 → 0.16.0

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) });
@@ -351,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 ──
@@ -377,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 }),
   });
 }
 
@@ -404,3 +445,42 @@ export async function deleteWeeklyDigest(client) {
 export async function sendWeeklyDigestNow(client) {
   return call(client, '/finances/email-schedules/send-now', { method: 'POST', body: '{}' });
 }
+
+/** Charges due across every account: projected recurring charges plus statement due days. */
+export async function getDueSoon(client, { days, timezone } = {}) {
+  const params = new URLSearchParams();
+  if (days !== undefined) params.set('days', String(days));
+  if (timezone) params.set('timezone', timezone);
+  const qs = params.toString();
+  const data = await call(client, `/finances/due-soon${qs ? `?${qs}` : ''}`);
+  return data.dueSoon;
+}
+
+export async function getDailySummary(client) {
+  const data = await call(client, '/finances/email-schedules?kind=daily_summary');
+  return data.schedule;
+}
+
+export async function setDailySummary(client, { weekdays, hour, timezone, recipients, active } = {}) {
+  const data = await call(client, '/finances/email-schedules', {
+    method: 'POST',
+    body: JSON.stringify({ kind: 'daily_summary', weekdays, hour, timezone, recipients, active }),
+  });
+  return data.schedule;
+}
+
+export async function deleteDailySummary(client) {
+  return call(client, '/finances/email-schedules?kind=daily_summary', { method: 'DELETE' });
+}
+
+export async function sendDailySummaryNow(client) {
+  return call(client, '/finances/email-schedules/send-now?kind=daily_summary', { method: 'POST', body: '{}' });
+}
+
+/** Set (or clear with day null) a card or loan's statement due day and fixed amount. */
+export async function setAccountDueDay(client, accountId, { day, amount } = {}) {
+  const body = { payment_due_day: day ?? null };
+  if (amount !== undefined) body.payment_due_amount = amount;
+  const data = await call(client, `/finances/accounts/${encodeURIComponent(accountId)}`, { method: 'PATCH', body: JSON.stringify(body) });
+  return data.account;
+}

package/src/mcp.js

@@ -13,7 +13,7 @@
 import { createInterface } from 'node:readline';
 
 import * as reports from './finances-reports.js';
-import { listFinanceAccounts } from './finances.js';
+import { getFinanceSummary, listFinanceAccounts, listFinanceTransactions } from './finances.js';
 import * as sf from './statements-fetch.js';
 
 export const PROTOCOL_VERSION = '2025-06-18';
@@ -28,6 +28,88 @@ export const TOOLS = [
     inputSchema: { type: 'object', properties: { includeHidden: { type: 'boolean' } }, additionalProperties: false },
     handler: async (args, { client }) => text({ accounts: await listFinanceAccounts(client, { includeHidden: args.includeHidden === true }) }),
   },
+  {
+    name: 'finance_due_soon',
+    description:
+      'What is due across every linked account: overdue, today and the next N days. Projected from each recurring charge\'s own cadence, plus statement due days set on cards and loans. Also lists charges that stopped appearing ("missed") and paid-this-cycle statements.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'integer', minimum: 0, maximum: 60, description: 'Horizon in days (default 7)' },
+        timezone: { type: 'string', description: 'IANA zone for "today"; defaults to the saved finance timezone' },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => {
+      const { recurring, ...due } = await reports.getDueSoon(client, { days: args.days, timezone: args.timezone });
+      return text({ ...due, recurringMonthlyTotal: recurring.monthlyTotal });
+    },
+  },
+  {
+    name: 'finance_recurring',
+    description: 'Every recurring charge detected across all accounts (subscriptions, bills, loan and card payments): cadence, typical amount, last and next date, monthly equivalent.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    handler: async (_args, { client }) => text((await reports.getDueSoon(client, { days: 0 })).recurring),
+  },
+  {
+    name: 'finance_summary',
+    description: 'Balance sheet (assets, debt, net by currency), cashflow for the window, top spending categories, and the debt-and-income position.',
+    inputSchema: { type: 'object', properties: { days: { type: 'integer', minimum: 1, maximum: 3650, description: 'Cashflow window (default 30)' } }, additionalProperties: false },
+    handler: async (args, { client }) => text(await getFinanceSummary(client, { days: args.days || 30 })),
+  },
+  {
+    name: 'finance_transactions',
+    description: 'The bank and card ledger, newest first. Filter by account id, text search, category or date range (YYYY-MM-DD).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        accountId: { type: 'string' },
+        search: { type: 'string' },
+        category: { type: 'string' },
+        startDate: { type: 'string' },
+        endDate: { type: 'string' },
+        limit: { type: 'integer', minimum: 1, maximum: 500 },
+        offset: { type: 'integer', minimum: 0 },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text(await listFinanceTransactions(client, { ...args, limit: args.limit || 50 })),
+  },
+  {
+    name: 'finance_set_due_day',
+    description: 'Set or clear a card or loan\'s statement due day (1-31, null clears) and optionally a fixed monthly amount (null = statement balance). Puts the account on the due-soon list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        accountId: { type: 'string' },
+        day: { type: ['integer', 'null'], minimum: 1, maximum: 31 },
+        amount: { type: ['number', 'string', 'null'] },
+      },
+      required: ['accountId', 'day'],
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text({ account: await reports.setAccountDueDay(client, args.accountId, { day: args.day, amount: args.amount }) }),
+  },
+  {
+    name: 'finance_daily_summary',
+    description: 'The daily summary email (due soon, new activity, position): show it, turn it on (optionally hour 0-23 and recipients), turn it off, or send one now.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['show', 'on', 'off', 'send_now'] },
+        hour: { type: 'integer', minimum: 0, maximum: 23 },
+        to: { type: 'array', items: { type: 'string' }, maxItems: 5 },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => {
+      if (args.action === 'on') return text({ schedule: await reports.setDailySummary(client, { hour: args.hour, recipients: args.to, active: true }) });
+      if (args.action === 'off') return text(await reports.deleteDailySummary(client));
+      if (args.action === 'send_now') return text(await reports.sendDailySummaryNow(client));
+      return text({ schedule: await reports.getDailySummary(client) });
+    },
+  },
   {
     name: 'statements_list',
     description: 'List PDF statements in the CoinPay statement library, optionally for one account or period (2026-08, 2026-Q3).',
@@ -60,9 +142,39 @@ 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:
@@ -121,7 +233,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. finance_due_soon answers "what is due" across every account; finance_recurring lists subscriptions and bills; finance_summary is the balance sheet. 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':
@@ -129,7 +241,9 @@ export async function handleMessage(message, ctx) {
     case 'ping':
       return reply({});
     case 'tools/list':
-      return reply({ tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+      // Claude Code's client (revision 2026-07-28) rejects a whole list that
+      // lacks these three cache fields, showing "tools fetch failed".
+      return reply({ tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })), resultType: 'complete', ttlMs: 0, cacheScope: 'private' });
     case 'tools/call': {
       const tool = TOOLS.find((t) => t.name === params.name);
       if (!tool) return fail(-32602, `Unknown tool: ${params.name}`);

package/src/statements-fetch.d.ts

@@ -14,6 +14,52 @@ export interface Institution {
   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 {
@@ -55,7 +101,7 @@ export interface Download {
   key: string | null;
 }
 
-export type PageStatus = 'ok' | 'login_needed' | 'no_statements';
+export type PageStatus = 'ok' | 'login_needed' | 'no_statements' | 'locked';
 
 export function lastFour(name: string): string | null;
 export function slug(value: string): string;
@@ -63,6 +109,37 @@ export function institutionKey(domain: string | null | undefined, name: 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 }[];
@@ -106,10 +183,13 @@ export function fetchInstitution(
     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[] }>;
-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>;
+): 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;
@@ -119,5 +199,6 @@ 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 }>;