@profullstack/coinpay 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.11.0] - 2026-09-12
+
+### Added
+- `coinpay finances books queue|confirm|confirm-all|categorize|rules|summary|export|send`:
+  every transaction auto-categorised (rules, heuristics, and Claude when the
+  server has a key) with a review queue, an "always" flag that turns a
+  correction into a rule, a tax summary by year/quarter/month in exact
+  arithmetic, and the CPA pack as CSV/PDF/HTML/JSON.
+- `coinpay finances payloads list|download`: every raw provider response,
+  exactly as received.
+- `coinpay finances reports send <id> --to …` and `books send --to …`: email
+  a report or the pack with attachments plus an expiring no-login link.
+- `coinpay finances digest set|show|off|send-now`: a weekly digest on chosen
+  weekdays at a chosen local hour.
+- `coinpay finances consent <id> on|off`: opt a connection into the
+  30-minute background sync.
+- SDK: `finances-reports` gained the books, payloads, email and digest
+  functions with declarations.
+
 ## [0.10.0] - 2026-09-12
 
 ### Added

package/README.md

@@ -704,7 +704,7 @@ coinpay finances connections     # institutions and their last sync
 coinpay finances sync            # pull fresh balances (rate-limited by the bank bridge)
 ```
 
-The dashboard has seven screens (`1`–`7`, `Tab`): **Overview** (gross volume, crypto vs
+The dashboard has seven screens (`1`–`7`, `←`/`→`): **Overview** (gross volume, crypto vs
 cards, commission paid, processor fees, refunds, net earnings, bank position, cashflow,
 invoices, escrow, payouts, a volume-vs-commission graph and a live feed), **Bank &
 Cards**, **Ledger**, **Crypto**, **Cards**, **Invoices & Escrow**, **Debt & Income**.
@@ -713,6 +713,13 @@ syncs the bank feed, `w` cycles the window, `p` pauses, `?` shows help, `q` quit
 refreshes every 30 seconds (`--interval`) and listens to the payments event stream, so
 a crypto payment shows up the moment it is detected.
 
+Click **⧉ MD** on a summary pane to copy Markdown. The header copy button exports
+status, including bank connection health and detailed source errors. Each pane
+carries its displayed window, snapshot timestamp, stream status and partial-data
+warnings. Transaction rows and the live event log are excluded. Tab / Shift+Tab
+focus controls; Enter / Space copies the focused summary. Clipboard writes use
+OSC 52 and require terminal support, including when connected over SSH.
+
 **Debt & Income** is the basic-accounting view, and it reads the same for a company or
 a person: income against spending per month, total owed split into revolving and
 instalment, months to clear each balance at its current payment rate, debt-to-income,

package/bin/coinpay.js

@@ -169,6 +169,11 @@ const BOOLEAN_FLAGS = new Set([
   'no-pending',
   'liability-positive',
   'acknowledge',
+  'always',
+  'no-model',
+  'only-uncategorized',
+  'no-attach',
+  'estimate-gaps',
   'plain',
   'no-stream',
   'hidden',
@@ -473,11 +478,22 @@ ${colors.cyan}Commands:${colors.reset}
     coverage              What part of a period was ever fetched (--period, --account)
     report                Monthly/quarterly/custom activity report (--period 2026-08 |
                             --from/--to; --account, --scope, --timezone, --format pdf|csv|html|json,
-                            --output <file>, --strict, --wait, --json)
+                            --output <file>, --strict, --estimate-gaps, --wait, --json)
     reports [get|download|delete <id>]  Report history and downloads
     statements import <pdf>  Keep an original bank statement (--account, --period|--from/--to)
     statements list|get|download|reconcile|delete
                           Statement library; reconcile takes --report --opening --closing --currency
+    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)
+    books categorize      Rules, heuristics, then the model over unreviewed rows (--wait)
+    books rules [add|delete]  Merchant category rules
+    books summary         Totals by tax category (--period 2026|2026-Q3|2026-08, --scope)
+    books export          CPA pack (--period, --scope, --format csv|pdf|html|json, --output)
+    payloads [list|download <id>]  Raw provider responses, exactly as received
+    reports send <id>     Email a report (--to a@x,b@y, --format pdf,csv, --message, --no-attach)
+    books send            Email the CPA pack (--to, --period, --scope, --format)
+    digest [show|set|off|send-now]  Weekly digest email (--days mon,fri --hour 8 --to …)
 
   ${colors.bright}escrow${colors.reset}
     create                Create a new escrow
@@ -4271,7 +4287,10 @@ async function handleFinances(subcommand, args, flags) {
     case 'coverage':
     case 'report':
     case 'reports':
-    case 'statements': {
+    case 'statements':
+    case 'books':
+    case 'payloads':
+    case 'digest': {
       const { client } = financesClient();
       const { runFinancesCommand } = await import('../src/finances-commands.js');
       const code = await runFinancesCommand(subcommand, args, flags, {
@@ -4285,7 +4304,7 @@ async function handleFinances(subcommand, args, flags) {
 
     default:
       print.error(`Unknown finances command: ${subcommand}`);
-      console.log('Usage: coinpay finances [tui|summary|accounts|ledger|connections|sync|connect|disconnect|backfill|jobs|coverage|report|reports|statements]');
+      console.log('Usage: coinpay finances [tui|summary|accounts|ledger|connections|sync|connect|disconnect|backfill|jobs|coverage|report|reports|statements|books|payloads|digest]');
       process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "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",
@@ -139,7 +139,7 @@
     "@inquirer/prompts": "^8.3.0",
     "@noble/curves": "^1.6.0",
     "@noble/hashes": "^1.5.0",
-    "@profullstack/hqtui": "^0.1.11",
+    "@profullstack/hqtui": "^0.6.3",
     "@scure/bip32": "^1.5.0",
     "@scure/bip39": "^1.4.0"
   }

package/src/finances-commands.js

@@ -247,6 +247,7 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
           includePendingAppendix: flags['no-pending'] ? false : true,
           formats: [format, 'json'],
           strict,
+          estimateGaps: flags['estimate-gaps'] === true,
           idempotencyKey: typeof flags['idempotency-key'] === 'string' ? flags['idempotency-key'] : undefined,
         });
         let report = created.report;
@@ -295,6 +296,18 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
           emit(data, data.reports.length ? data.reports.map(describeReport).join('\n') : 'No reports yet.');
           return EXIT.OK;
         }
+        if (action === 'send') {
+          const id = args[1];
+          if (!id || typeof flags.to !== 'string') throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances reports send <report-id> --to cpa@x.com,me@x.com [--format pdf,csv] [--message "…"] [--no-attach]');
+          const data = await api.sendFinanceReportEmail(client, id, {
+            to: listFlag(flags.to),
+            formats: flags.format ? listFlag(flags.format) : undefined,
+            message: typeof flags.message === 'string' ? flags.message : null,
+            attach: flags['no-attach'] ? false : true,
+          });
+          emit(data, `Sent to ${data.sent.join(', ') || 'nobody'}${data.failed.length ? `; failed: ${data.failed.map((f) => `${f.to} (${f.error})`).join(', ')}` : ''}. Attached: ${data.attached.join(', ') || 'none'}. Link (expires ${data.linkExpiresAt.slice(0, 10)}): ${data.linkUrl}`);
+          return data.sent.length > 0 ? EXIT.OK : EXIT.FAILURE;
+        }
         if (action === 'get' || action === 'download' || action === 'delete') {
           const id = args[1];
           if (!id) throw new CliExit(EXIT.INVALID, `Usage: coinpay finances reports ${action} <report-id>`);
@@ -316,7 +329,7 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
           emit({ report: data.report, output: path, bytes: file.bytes.length, sha256: file.sha256 }, `Wrote ${path} (${file.bytes.length} bytes)`);
           return EXIT.OK;
         }
-        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances reports [list|get <id>|download <id>|delete <id>]');
+        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances reports [list|get <id>|download <id>|send <id>|delete <id>]');
       }
 
       case 'statements': {
@@ -404,6 +417,184 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
         throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances statements [import <file>|list|get <id>|download <id>|reconcile <id>|delete <id>]');
       }
 
+      case 'books': {
+        const action = args[0] || 'queue';
+        if (action === 'queue' || action === 'list') {
+          const scope = typeof flags.scope === 'string' ? flags.scope : undefined;
+          const data = await api.listBooksQueue(client, {
+            status: typeof flags.status === 'string' ? flags.status : 'unreviewed',
+            scope,
+            accountId: typeof flags.account === 'string' ? flags.account : undefined,
+            search: typeof flags.search === 'string' ? flags.search : undefined,
+            limit: flags.limit ? Number(flags.limit) : undefined,
+            offset: flags.offset ? Number(flags.offset) : undefined,
+          });
+          emit(
+            data,
+            [`${data.unreviewed} row(s) awaiting review${data.modelEnabled ? '' : ' (model pass off: no ANTHROPIC_API_KEY on the server)'}`]
+              .concat(data.rows.map((r) => `${r.id}  ${(r.posted || '').slice(0, 10)}  ${r.amount} ${r.currency}  ${(r.payee || r.description || '').slice(0, 40).padEnd(40)}  ${r.category || '-'} / ${r.taxCategoryLabel} / ${r.scope}  [${r.suggestion ? r.suggestion.by : r.categorySource} ${Math.round(((r.categoryConfidence ?? (r.suggestion && r.suggestion.confidence) ?? 0)) * 100)}%]`))
+              .join('\n'),
+          );
+          return EXIT.OK;
+        }
+        if (action === 'confirm') {
+          const id = args[1];
+          if (!id) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances books confirm <transaction-id> [--category c] [--tax t] [--scope business|personal] [--note …] [--always]');
+          const row = await api.reviewBooksTransaction(client, id, {
+            category: typeof flags.category === 'string' ? flags.category : undefined,
+            taxCategory: typeof flags.tax === 'string' ? flags.tax : undefined,
+            scope: typeof flags.scope === 'string' ? flags.scope : undefined,
+            note: typeof flags.note === 'string' ? flags.note : undefined,
+            createRule: flags.always === true,
+          });
+          emit({ transaction: row }, `Confirmed ${row.id}: ${row.category || '-'} / ${row.taxCategoryLabel} / ${row.scope}${flags.always ? ' (rule created)' : ''}`);
+          return EXIT.OK;
+        }
+        if (action === 'confirm-all') {
+          const data = await api.listBooksQueue(client, { status: 'unreviewed', limit: 500 });
+          if (!data.rows.length) { emit({ reviewed: 0 }, 'Nothing to confirm.'); return EXIT.OK; }
+          if (!flags.yes) throw new CliExit(EXIT.INVALID, `This accepts the suggestion on ${data.rows.length} row(s). Re-run with --yes.`);
+          const result = await api.bulkReviewBooks(client, data.rows.map((r) => r.id));
+          emit(result, `Confirmed ${result.reviewed} row(s) as suggested.`);
+          return EXIT.OK;
+        }
+        if (action === 'categorize') {
+          const data = await api.categorizeBooks(client, { useModel: flags['no-model'] ? false : true, onlyUncategorized: flags['only-uncategorized'] === true });
+          progress(`Queued ${describeJob(data.job)}${data.modelEnabled ? '' : ' (model pass off: no ANTHROPIC_API_KEY on the server)'}`);
+          let job = data.job;
+          if (flags.wait) job = await api.waitForFinanceJob(client, job.id, { onProgress: (j) => progress(describeJob(j)) });
+          const r = job.result || {};
+          emit({ job }, job.status === 'completed' ? `Examined ${r.examined ?? 0}: ${r.fromRules ?? 0} by rule, ${r.fromModel ?? 0} by model, ${r.autoAccepted ?? 0} accepted, ${r.queued ?? 0} for review` : describeJob(job));
+          return job.status === 'failed' ? EXIT.FAILURE : EXIT.OK;
+        }
+        if (action === 'rules') {
+          const sub = args[1];
+          if (sub === 'add') {
+            const pattern = args[2];
+            if (!pattern || typeof flags.category !== 'string') throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances books rules add "<pattern>" --category c [--tax t] [--scope s] [--field payee|description] [--match exact|contains]');
+            const rule = await api.createBooksRule(client, { pattern, category: flags.category, taxCategory: typeof flags.tax === 'string' ? flags.tax : undefined, scope: typeof flags.scope === 'string' ? flags.scope : undefined, matchField: typeof flags.field === 'string' ? flags.field : 'payee', matchType: typeof flags.match === 'string' ? flags.match : 'exact' });
+            emit({ rule }, `Rule ${rule.id}: ${rule.match_field} ${rule.match_type} "${rule.pattern}" → ${rule.category}`);
+            return EXIT.OK;
+          }
+          if (sub === 'delete') {
+            if (!args[2]) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances books rules delete <rule-id>');
+            const data = await api.deleteBooksRule(client, args[2]);
+            emit(data, 'Rule deleted.');
+            return EXIT.OK;
+          }
+          const rules = await api.listBooksRules(client);
+          emit({ rules }, rules.length ? rules.map((r) => `${r.id}  ${r.match_field} ${r.match_type} "${r.pattern}" → ${r.category}${r.tax_category ? ' / ' + r.tax_category : ''}${r.scope ? ' / ' + r.scope : ''}`).join('\n') : 'No rules.');
+          return EXIT.OK;
+        }
+        if (action === 'send') {
+          if (typeof flags.to !== 'string') throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances books send --to cpa@x.com,me@x.com --period 2026 [--scope business] [--format pdf,csv] [--message "…"]');
+          const period = typeof flags.period === 'string' ? flags.period : null;
+          const from = typeof flags.from === 'string' ? flags.from : undefined;
+          const toDate = typeof flags['to-date'] === 'string' ? flags['to-date'] : undefined;
+          if (!period && !(from && toDate)) throw new CliExit(EXIT.INVALID, 'Pass --period 2026 (or 2026-Q3, 2026-08) or --from/--to-date');
+          const data = await api.sendBooksEmail(client, {
+            to: listFlag(flags.to), period: period || undefined, from, toDate,
+            timezone: typeof flags.timezone === 'string' ? flags.timezone : undefined,
+            scope: typeof flags.scope === 'string' ? flags.scope : 'business',
+            formats: flags.format ? listFlag(flags.format) : undefined,
+            message: typeof flags.message === 'string' ? flags.message : null,
+            attach: flags['no-attach'] ? false : true,
+          });
+          emit(data, `Sent to ${data.sent.join(', ') || 'nobody'}${data.failed.length ? `; failed: ${data.failed.map((f) => `${f.to} (${f.error})`).join(', ')}` : ''}. ${data.rows} rows, ${data.unreviewed} unreviewed. Link (expires ${data.linkExpiresAt.slice(0, 10)}): ${data.linkUrl}`);
+          return data.sent.length > 0 ? EXIT.OK : EXIT.FAILURE;
+        }
+        if (action === 'summary' || action === 'export') {
+          const period = typeof flags.period === 'string' ? flags.period : typeof flags.year === 'string' || typeof flags.year === 'number' ? String(flags.year) : null;
+          const from = typeof flags.from === 'string' ? flags.from : undefined;
+          const to = typeof flags.to === 'string' ? flags.to : undefined;
+          if (!period && !(from && to)) throw new CliExit(EXIT.INVALID, 'Pass --period 2026 (or 2026-Q3, 2026-08) or --from/--to');
+          const scope = typeof flags.scope === 'string' ? flags.scope : 'business';
+          const timezone = typeof flags.timezone === 'string' ? flags.timezone : undefined;
+          if (action === 'summary') {
+            const data = await api.getBooksSummary(client, { period: period || undefined, from, to, timezone, scope });
+            emit(
+              data,
+              [`${data.period.label} · ${scope} · ${data.rows} rows (${data.unreviewed} unreviewed, ${data.uncategorized} uncategorised)`]
+                .concat(data.totals.map((t) => `${t.currency}: income ${t.income} · expenses ${t.expenses} · net ${t.net} · excluded ${t.excluded}`))
+                .concat(data.lines.map((l) => `  ${l.label.padEnd(32)} ${l.currency} ${l.total.padStart(14)}  (${l.rows})${l.excluded ? '  excluded' : ''}`))
+                .concat([data.notice])
+                .join('\n'),
+            );
+            return EXIT.OK;
+          }
+          const format = typeof flags.format === 'string' ? flags.format.toLowerCase() : 'csv';
+          const file = await api.exportBooks(client, { period: period || undefined, from, to, timezone, scope, format });
+          const output = typeof flags.output === 'string' ? flags.output : file.filename || `books-${period || 'range'}.${format}`;
+          const path = writeDownload(output, Buffer.from(file.bytes), { overwrite: flags.overwrite === true });
+          emit({ output: path, bytes: file.bytes.length, unreviewed: Number(file.headers['x-unreviewed-rows'] || 0) }, `Wrote ${path} (${file.bytes.length} bytes; ${file.headers['x-unreviewed-rows'] || 0} unreviewed rows)`);
+          return EXIT.OK;
+        }
+        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances books [queue|confirm <id>|confirm-all --yes|categorize|rules [add|delete]|summary|export|send]');
+      }
+
+      case 'digest': {
+        const action = args[0] || 'show';
+        const DAY_NAMES = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+        const describe = (s) => s
+          ? `${s.active ? 'on' : 'off'} · ${s.weekdays.map((d) => DAY_NAMES[d]).join(',')} at ${String(s.hour).padStart(2, '0')}:00 ${s.timezone} · ${s.scope} · to ${s.recipients.join(', ')}${s.nextRunAt ? ` · next ${s.nextRunAt}` : ''}${s.lastSentAt ? ` · last ${s.lastSentAt}` : ''}`
+          : 'No weekly digest configured. Set one with: coinpay finances digest set --days mon,fri --hour 8 --to you@example.com';
+        if (action === 'show') {
+          const s = await api.getWeeklyDigest(client);
+          emit({ schedule: s }, describe(s));
+          return EXIT.OK;
+        }
+        if (action === 'set' || action === 'on') {
+          const days = flags.days ? listFlag(flags.days).map((d) => { const i = DAY_NAMES.indexOf(d.toLowerCase().slice(0, 3)); return i === -1 ? Number(d) : i; }) : undefined;
+          if (days && days.some((d) => !Number.isInteger(d) || d < 0 || d > 6)) throw new CliExit(EXIT.INVALID, '--days takes names like mon,fri or numbers 0 (Sunday) to 6');
+          const s = await api.setWeeklyDigest(client, {
+            weekdays: days,
+            hour: flags.hour !== undefined ? Number(flags.hour) : undefined,
+            timezone: typeof flags.timezone === 'string' ? flags.timezone : undefined,
+            recipients: flags.to ? listFlag(flags.to) : undefined,
+            scope: typeof flags.scope === 'string' ? flags.scope : undefined,
+            formats: flags.format ? listFlag(flags.format) : undefined,
+            active: true,
+          });
+          emit({ schedule: s }, describe(s));
+          return EXIT.OK;
+        }
+        if (action === 'off' || action === 'pause') {
+          const s = await api.setWeeklyDigest(client, { active: false });
+          emit({ schedule: s }, describe(s));
+          return EXIT.OK;
+        }
+        if (action === 'delete') {
+          const data = await api.deleteWeeklyDigest(client);
+          emit(data, 'Weekly digest removed.');
+          return EXIT.OK;
+        }
+        if (action === 'send-now') {
+          const data = await api.sendWeeklyDigestNow(client);
+          emit(data, `Sent to ${data.sent.join(', ') || 'nobody'}${data.failed.length ? `; failed: ${data.failed.map((f) => `${f.to} (${f.error})`).join(', ')}` : ''}`);
+          return data.sent.length > 0 ? EXIT.OK : EXIT.FAILURE;
+        }
+        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances digest [show|set --days mon,fri --hour 8 --to a@x,b@y [--scope business]|off|delete|send-now]');
+      }
+
+      case 'payloads': {
+        const action = args[0] || 'list';
+        if (action === 'list') {
+          const data = await api.listFinancePayloads(client, { connectionId: typeof flags.connection === 'string' ? flags.connection : undefined, limit: flags.limit ? Number(flags.limit) : undefined });
+          emit(data, data.payloads.length ? data.payloads.map((p) => `${p.id}  ${p.fetchedAt}  ${p.provider}  ${p.requestClass}  ${p.accounts} accounts / ${p.transactions} tx / ${p.errors} errors  ${p.bytes} bytes`).join('\n') : 'No archived payloads yet.');
+          return EXIT.OK;
+        }
+        if (action === 'download') {
+          const id = args[1];
+          if (!id) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances payloads download <payload-id> --output <file.json>');
+          const file = await api.downloadFinancePayload(client, id);
+          const output = typeof flags.output === 'string' ? flags.output : file.filename || `${id}.json`;
+          const path = writeDownload(output, Buffer.from(file.bytes), { overwrite: flags.overwrite === true });
+          emit({ output: path, bytes: file.bytes.length, sha256: file.sha256 }, `Wrote ${path} (${file.bytes.length} bytes, as received from the provider)`);
+          return EXIT.OK;
+        }
+        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances payloads [list|download <id>]');
+      }
+
       default:
         return null;
     }
@@ -420,4 +611,4 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
   }
 }
 
-export const EXTENDED_SUBCOMMANDS = ['connect', 'disconnect', 'consent', 'backfill', 'jobs', 'coverage', 'report', 'reports', 'statements'];
+export const EXTENDED_SUBCOMMANDS = ['connect', 'disconnect', 'consent', 'backfill', 'jobs', 'coverage', 'report', 'reports', 'statements', 'books', 'payloads', 'digest'];

package/src/finances-reports.d.ts

@@ -5,7 +5,7 @@ export type ReconciliationStatus = 'not_attempted' | 'unavailable' | 'mismatch'
 export type ReportFormat = 'pdf' | 'html' | 'csv' | 'json';
 export type ReportStatus = 'queued' | 'generating' | 'ready' | 'failed' | 'superseded' | 'deleted';
 export type JobStatus = 'queued' | 'running' | 'waiting_for_budget' | 'partial' | 'failed' | 'completed' | 'cancelled';
-export type JobKind = 'backfill' | 'refresh' | 'scheduled_sync' | 'report';
+export type JobKind = 'backfill' | 'refresh' | 'scheduled_sync' | 'report' | 'categorize' | 'email_report';
 
 /** Thrown by every call here when the server answers with its structured error body. */
 export interface FinanceApiError extends Error {
@@ -196,6 +196,8 @@ export function createFinanceReport(
     includePendingAppendix?: boolean;
     formats?: ReportFormat[];
     strict?: boolean;
+    /** Fill the days before the first observed posting with a labelled extrapolation. */
+    estimateGaps?: boolean;
     idempotencyKey?: string;
   },
 ): Promise<{ report: FinanceReport; job: FinanceJob }>;
@@ -241,3 +243,119 @@ export function reconcileFinanceStatement(
     acknowledge?: boolean;
   },
 ): Promise<FinanceReconciliation>;
+
+export interface BooksRow {
+  id: string;
+  accountId: string;
+  accountName: string;
+  orgName: string | null;
+  currency: string;
+  posted: string | null;
+  amount: string;
+  payee: string | null;
+  description: string | null;
+  memo: string | null;
+  category: string | null;
+  categorySource: 'auto' | 'rule' | 'model' | 'user';
+  categoryConfidence: number | null;
+  taxCategory: string | null;
+  taxCategoryLabel: string;
+  scope: 'business' | 'personal' | string;
+  scopeOverride: string | null;
+  accountScope: string;
+  reviewedAt: string | null;
+  note: string | null;
+  suggestion: { category: string | null; taxCategory: string | null; confidence: number | null; by: string | null } | null;
+}
+
+export interface BooksRule {
+  id: string;
+  match_field: 'payee' | 'description';
+  match_type: 'exact' | 'contains';
+  pattern: string;
+  category: string;
+  tax_category: string | null;
+  scope: 'business' | 'personal' | null;
+  hits: number;
+  active: boolean;
+  created_at: string;
+}
+
+export interface BooksSummaryLine {
+  taxCategory: string;
+  label: string;
+  currency: string;
+  total: string;
+  rows: number;
+  excluded: boolean;
+  income: boolean;
+}
+
+export function listBooksQueue(
+  client: CoinPayClient,
+  options?: { status?: 'unreviewed' | 'reviewed' | 'all'; scope?: 'business' | 'personal' | 'all'; accountId?: string; search?: string; start?: string; end?: string; limit?: number; offset?: number },
+): Promise<{ rows: BooksRow[]; total: number; unreviewed: number; categories: string[]; taxCategories: Array<{ id: string; label: string }>; modelEnabled: boolean }>;
+export function reviewBooksTransaction(
+  client: CoinPayClient,
+  transactionId: string,
+  options?: { category?: string | null; taxCategory?: string | null; scope?: 'business' | 'personal' | null; note?: string | null; createRule?: boolean },
+): Promise<BooksRow>;
+export function bulkReviewBooks(
+  client: CoinPayClient,
+  ids: string[],
+  options?: { category?: string | null; taxCategory?: string | null; scope?: 'business' | 'personal' | null; createRule?: boolean },
+): Promise<{ reviewed: number }>;
+export function categorizeBooks(client: CoinPayClient, options?: { useModel?: boolean; onlyUncategorized?: boolean }): Promise<{ job: FinanceJob; modelEnabled: boolean }>;
+export function listBooksRules(client: CoinPayClient): Promise<BooksRule[]>;
+export function createBooksRule(
+  client: CoinPayClient,
+  options: { matchField?: 'payee' | 'description'; matchType?: 'exact' | 'contains'; pattern: string; category: string; taxCategory?: string | null; scope?: 'business' | 'personal' | null },
+): Promise<BooksRule>;
+export function deleteBooksRule(client: CoinPayClient, ruleId: string): Promise<{ success: boolean }>;
+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 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>;
+
+export interface SendOutcome {
+  sent: string[];
+  failed: Array<{ to: string; error: string }>;
+  attached: string[];
+  linkUrl: string;
+  linkExpiresAt: string;
+}
+
+export interface WeeklyDigest {
+  id: string;
+  kind: 'weekly_digest';
+  weekdays: number[];
+  hour: number;
+  timezone: string;
+  recipients: string[];
+  scope: 'business' | 'personal' | 'all';
+  formats: string[];
+  active: boolean;
+  lastSentAt: string | null;
+  nextRunAt: string | null;
+  createdAt: string;
+}
+
+export function sendFinanceReportEmail(
+  client: CoinPayClient,
+  reportId: string,
+  options: { to: string | string[]; formats?: ReportFormat[]; message?: string | null; attach?: boolean; expiresInDays?: number },
+): 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 }>;
+export function getWeeklyDigest(client: CoinPayClient): Promise<WeeklyDigest | null>;
+export function setWeeklyDigest(
+  client: CoinPayClient,
+  options?: { weekdays?: number[]; hour?: number; timezone?: string; recipients?: string[]; scope?: 'business' | 'personal' | 'all'; formats?: string[]; active?: boolean },
+): Promise<WeeklyDigest>;
+export function deleteWeeklyDigest(client: CoinPayClient): Promise<{ success: boolean }>;
+export function sendWeeklyDigestNow(client: CoinPayClient): Promise<SendOutcome>;

package/src/finances-reports.js

@@ -156,12 +156,12 @@ export async function getFinanceCoverage(client, { period, from, to, timezone, a
  * use `waitForFinanceReport` to block until it is ready.
  */
 export async function createFinanceReport(client, {
-  period, from, to, timezone, accountIds, scope, includeHidden, includePendingAppendix, formats, strict, idempotencyKey,
+  period, from, to, timezone, accountIds, scope, includeHidden, includePendingAppendix, formats, strict, estimateGaps, idempotencyKey,
 } = {}) {
   return call(client, '/finances/reports', {
     method: 'POST',
     headers: headersWith(idempotencyKey),
-    body: JSON.stringify({ period, from, to, timezone, accountIds, scope, includeHidden, includePendingAppendix, formats, strict }),
+    body: JSON.stringify({ period, from, to, timezone, accountIds, scope, includeHidden, includePendingAppendix, formats, strict, estimateGaps }),
   });
 }
 
@@ -255,3 +255,102 @@ export async function reconcileFinanceStatement(client, statementId, {
   });
   return data.reconciliation;
 }
+
+// ── Books ──
+
+/** Rows awaiting review (default) plus the category vocabularies. */
+export async function listBooksQueue(client, { status, scope, accountId, search, start, end, limit, offset } = {}) {
+  return call(client, `/finances/books/queue${query({ status, scope, account: accountId, search, start, end, limit, offset })}`);
+}
+
+/** Confirm one row. Omitted fields keep the row's current values. */
+export async function reviewBooksTransaction(client, transactionId, { category, taxCategory, scope, note, createRule } = {}) {
+  const data = await call(client, `/finances/books/transactions/${encodeURIComponent(transactionId)}`, {
+    method: 'PATCH',
+    body: JSON.stringify({ category, taxCategory, scope, note, createRule }),
+  });
+  return data.transaction;
+}
+
+/** Confirm many rows; with no category given each row's suggestion is accepted. */
+export async function bulkReviewBooks(client, ids, { category, taxCategory, scope, createRule } = {}) {
+  return call(client, '/finances/books/bulk', { method: 'POST', body: JSON.stringify({ ids, category, taxCategory, scope, createRule }) });
+}
+
+/** Queue an auto-categorisation run over unreviewed rows. Answers with the job. */
+export async function categorizeBooks(client, { useModel = true, onlyUncategorized = false } = {}) {
+  return call(client, '/finances/books/categorize', { method: 'POST', body: JSON.stringify({ useModel, onlyUncategorized }) });
+}
+
+export async function listBooksRules(client) {
+  const data = await call(client, '/finances/books/rules');
+  return data.rules || [];
+}
+
+export async function createBooksRule(client, { matchField = 'payee', matchType = 'exact', pattern, category, taxCategory, scope } = {}) {
+  const data = await call(client, '/finances/books/rules', { method: 'POST', body: JSON.stringify({ matchField, matchType, pattern, category, taxCategory, scope }) });
+  return data.rule;
+}
+
+export async function deleteBooksRule(client, ruleId) {
+  return call(client, `/finances/books/rules/${encodeURIComponent(ruleId)}`, { method: 'DELETE' });
+}
+
+/** Totals by tax category for a year (`2026`), quarter or month. */
+export async function getBooksSummary(client, { period, from, to, timezone, scope, rows } = {}) {
+  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 })}`);
+}
+
+// ── Raw provider payloads ──
+
+export async function listFinancePayloads(client, { connectionId, limit, offset } = {}) {
+  return call(client, `/finances/payloads${query({ connection: connectionId, limit, offset })}`);
+}
+
+export async function downloadFinancePayload(client, payloadId) {
+  return client.requestBinary(`/finances/payloads/${encodeURIComponent(payloadId)}/download`);
+}
+
+// ── Email ──
+
+/** Email a ready report: attachments plus an expiring no-login link. */
+export async function sendFinanceReportEmail(client, reportId, { to, formats, message, attach, expiresInDays } = {}) {
+  return call(client, `/finances/reports/${encodeURIComponent(reportId)}/send`, {
+    method: 'POST',
+    body: JSON.stringify({ to, formats, message, attach, expiresInDays }),
+  });
+}
+
+/** 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 } = {}) {
+  return call(client, '/finances/books/send', {
+    method: 'POST',
+    body: JSON.stringify({ to, period, from, toDate, timezone, scope, formats, message, attach, expiresInDays }),
+  });
+}
+
+export async function getWeeklyDigest(client) {
+  const data = await call(client, '/finances/email-schedules');
+  return data.schedule;
+}
+
+export async function setWeeklyDigest(client, { weekdays, hour, timezone, recipients, scope, formats, active } = {}) {
+  const data = await call(client, '/finances/email-schedules', {
+    method: 'POST',
+    body: JSON.stringify({ weekdays, hour, timezone, recipients, scope, formats, active }),
+  });
+  return data.schedule;
+}
+
+export async function deleteWeeklyDigest(client) {
+  return call(client, '/finances/email-schedules', { method: 'DELETE' });
+}
+
+export async function sendWeeklyDigestNow(client) {
+  return call(client, '/finances/email-schedules/send-now', { method: 'POST', body: '{}' });
+}

package/src/finances-tui.js

@@ -95,7 +95,7 @@ function num(v) {
 
 // ── State ──
 
-function createState(days) {
+export function createState(days) {
   return {
     tab: 0,
     days,
@@ -732,6 +732,111 @@ function positionScreen(ui, state, theme) {
 
 const SCREENS = [overviewScreen, bankScreen, ledgerScreen, cryptoScreen, cardsScreen, invoicesScreen, positionScreen];
 
+/** Context exported with each pane; the displayed snapshot can lag the requested window. */
+export function financeMarkdownContext(state) {
+  const s = state.snapshot;
+  return [
+    `CoinPay Finances · ${TABS[state.tab]}`,
+    `Payment business filter: ${state.businessId || 'all businesses'}; bank data is merchant-wide`,
+    `Displayed window: ${s?.windowDays ?? state.days} days`,
+    ...(s && s.windowDays !== state.days ? [`Requested window: ${state.days} days (refresh pending)`] : []),
+    `Snapshot: ${s?.generatedAt || 'not loaded'}`,
+    `Updates: ${state.loading ? 'refreshing' : state.paused ? 'paused' : 'live'}`,
+    `Payment stream: ${state.liveStatus}`,
+    ...(state.error ? [`Refresh failed: ${state.error}`] : []),
+    ...Object.entries(s?.errors || {}).map(([source, error]) => `Source unavailable — ${source}: ${error}`),
+    ...(s?.crypto.partial ? ['Crypto details cover a partial page.'] : []),
+    ...(s?.card.partial ? ['Card details, processor fees and refunds cover a partial page.'] : []),
+    ...(s?.position ? [`Debt & Income: ${s.position.observedDays ?? s.position.lookbackDays} days observed; independent of the dashboard window.`] : []),
+  ].join('\n');
+}
+
+/** Status can be copied without including any live payment or transaction rows. */
+export function financeStatusMarkdown(state, markdownText) {
+  return [
+    '## CoinPay status',
+    markdownText(financeMarkdownContext(state)),
+    `Bank sync: ${state.syncing ? 'running' : 'idle'}`,
+    ...(state.notice ? [markdownText(state.notice)] : []),
+    ...(state.snapshot?.bank.connections || []).map((c) => markdownText(
+      `${c.label || c.provider || 'Bank connection'}: ${c.is_active ? 'active' : 'inactive'}; last sync ${c.last_synced_at || 'never'} (${c.last_sync_status || 'unknown'})${c.last_sync_error ? `; ${c.last_sync_error}` : ''}`,
+    )),
+  ].join('\n\n') + '\n';
+}
+
+/** Draw the same summary controls in production and headless interaction tests. */
+export function renderFinancesTui(ui, state, t, { height, interval = 30, markdownText }) {
+  ui.row({ size: 1 }, (header) => {
+    header.text(' CoinPay ', { fg: t.title, bold: true, size: 10 });
+    header.tabs({
+      tabs: TABS.map((name, i) => `${i + 1} ${name}`),
+      active: state.tab,
+      onSelect: (index) => { state.tab = index; },
+    });
+    const right = [
+      state.paused ? 'paused' : state.loading ? 'loading…' : `${state.days}d`,
+      state.lastRefresh ? `updated ${ago(state.lastRefresh)}` : 'starting',
+      clock(),
+    ].join('  ');
+    header.text(`${right} `, { fg: state.paused ? t.warning : state.error ? t.danger : t.success, align: 'right' });
+    header.copyButton({ markdown: () => financeStatusMarkdown(state, markdownText), width: 6 });
+  });
+  ui.spacer(1);
+
+  ui.column({ size: height - 4 }, (body) => {
+    if (!state.snapshot) {
+      body.panel({ title: 'Finances' }, (p) => {
+        p.text(state.error ? `Could not load: ${state.error}` : 'Loading your numbers…', { fg: state.error ? t.danger : t.muted });
+        if (state.error) p.text('Press r to retry, q to quit.', { fg: t.muted });
+      });
+      return;
+    }
+    SCREENS[state.tab](body, state, t);
+  });
+
+  ui.spacer(1);
+  const errorCount = state.snapshot ? Object.keys(state.snapshot.errors).length : 0;
+  ui.statusBar({
+    items: [
+      { key: '1-7', label: 'Screen' },
+      { key: 'r', label: 'Refresh' },
+      { key: 's', label: state.syncing ? 'Syncing…' : 'Sync bank', active: state.syncing },
+      { key: 'w', label: `Window ${state.days}d` },
+      { key: 'p', label: state.paused ? 'Resume' : 'Pause', active: state.paused },
+      { key: '?', label: 'Help' },
+      { key: 'q', label: 'Quit' },
+    ],
+    right: [
+      ...(errorCount ? [{ label: `${errorCount} source${errorCount > 1 ? 's' : ''} unavailable`, color: t.warning }] : []),
+      { label: state.liveStatus, color: state.liveStatus === 'stream connected' ? t.success : t.muted },
+    ],
+  });
+
+  if (state.showHelp) {
+    ui.modal({
+      title: 'CoinPay Finances — Help',
+      width: 66,
+      height: 22,
+      message:
+        '1-7, ←/→ switch screens.\n' +
+        'r refreshes now; refresh also runs every ' + Math.max(5, interval) + 's.\n' +
+        's pulls fresh bank balances and transactions (rate-limited\n' +
+        '  by the bank bridge, so it is never automatic).\n' +
+        'w cycles the window: 7 → 30 → 90 → 365 days.\n' +
+        'p pauses the timer. ↑/↓ j/k, PgUp/PgDn, Home/End scroll.\n' +
+        'Mouse: click tabs, scroll tables.\n\n' +
+        '⧉ MD copies a summary. Tab focuses, Enter copies.\n\n' +
+        'Commission paid = platform fees on crypto + card payments.\n' +
+        'Net earnings = gross − commission − processor fees − refunds.\n' +
+        'Debt & Income covers 180 days regardless of w, and excludes\n' +
+        '  transfers and card payments from both sides.\n\n' +
+        'Esc or Close dismisses help.',
+      buttons: [{ label: 'Close', onPress: () => { state.showHelp = false; } }],
+      onDismiss: () => { state.showHelp = false; },
+    });
+  }
+}
+
 // ── App ──
 
 async function loadHqtui() {
@@ -755,8 +860,13 @@ async function loadHqtui() {
  */
 export async function runFinancesTui({ client, baseUrl, token, days = 30, interval = 30, businessId, limit = 100, theme } = {}) {
   const hqtui = await loadHqtui();
-  const app = await hqtui.createApp({ fps: 30, theme: theme || 'dark', quitKeys: ['ctrl+c', 'q'] });
   const state = createState(days);
+  state.businessId = businessId;
+  const app = await hqtui.createApp({
+    fps: 30, theme: theme || 'dark', quitKeys: ['ctrl+c', 'q'],
+    copyMarkdown: true,
+    markdownContext: () => financeMarkdownContext(state),
+  });
 
   let refreshing = false;
   let refreshTimer = null;
@@ -867,7 +977,6 @@ export async function runFinancesTui({ client, baseUrl, token, days = 30, interv
       return;
     }
     switch (name) {
-      case 'tab':
       case 'right':
       case 'l':
         state.tab = event.shift ? (state.tab + TABS.length - 1) % TABS.length : (state.tab + 1) % TABS.length;
@@ -925,74 +1034,7 @@ export async function runFinancesTui({ client, baseUrl, token, days = 30, interv
     app.invalidate();
   });
 
-  app.render(({ ui, theme: t, height }) => {
-    ui.row({ size: 1 }, (header) => {
-      header.text(' CoinPay ', { fg: t.title, bold: true, size: 10 });
-      header.tabs({
-        tabs: TABS.map((name, i) => `${i + 1} ${name}`),
-        active: state.tab,
-        onSelect: (index) => { state.tab = index; },
-      });
-      const right = [
-        state.paused ? 'paused' : state.loading ? 'loading…' : `${state.days}d`,
-        state.lastRefresh ? `updated ${ago(state.lastRefresh)}` : 'starting',
-        clock(),
-      ].join('  ');
-      header.text(`${right} `, { fg: state.paused ? t.warning : state.error ? t.danger : t.success, align: 'right' });
-    });
-    ui.spacer(1);
-
-    ui.column({ size: height - 4 }, (body) => {
-      if (!state.snapshot) {
-        body.panel({ title: 'Finances' }, (p) => {
-          p.text(state.error ? `Could not load: ${state.error}` : 'Loading your numbers…', { fg: state.error ? t.danger : t.muted });
-          if (state.error) p.text('Press r to retry, q to quit.', { fg: t.muted });
-        });
-        return;
-      }
-      SCREENS[state.tab](body, state, t);
-    });
-
-    ui.spacer(1);
-    const errorCount = state.snapshot ? Object.keys(state.snapshot.errors).length : 0;
-    ui.statusBar({
-      items: [
-        { key: '1-7', label: 'Screen' },
-        { key: 'r', label: 'Refresh' },
-        { key: 's', label: state.syncing ? 'Syncing…' : 'Sync bank', active: state.syncing },
-        { key: 'w', label: `Window ${state.days}d` },
-        { key: 'p', label: state.paused ? 'Resume' : 'Pause', active: state.paused },
-        { key: '?', label: 'Help' },
-        { key: 'q', label: 'Quit' },
-      ],
-      right: [
-        ...(errorCount ? [{ label: `${errorCount} source${errorCount > 1 ? 's' : ''} unavailable`, color: t.warning }] : []),
-        { label: state.liveStatus, color: state.liveStatus === 'stream connected' ? t.success : t.muted },
-      ],
-    });
-
-    if (state.showHelp) {
-      ui.modal({
-        title: 'CoinPay Finances — Help',
-        width: 66,
-        height: 20,
-        message:
-          '1-7, Tab, ←/→ switch screens.\n' +
-          'r refreshes now; refresh also runs every ' + Math.max(5, interval) + 's.\n' +
-          's pulls fresh bank balances and transactions (rate-limited\n' +
-          '  by the bank bridge, so it is never automatic).\n' +
-          'w cycles the window: 7 → 30 → 90 → 365 days.\n' +
-          'p pauses the timer. ↑/↓ j/k, PgUp/PgDn, Home/End scroll.\n' +
-          'Mouse: click tabs, scroll tables.\n\n' +
-          'Commission paid = platform fees on crypto + card payments.\n' +
-          'Net earnings = gross − commission − processor fees − refunds.\n' +
-          'Debt & Income covers 180 days regardless of w, and excludes\n' +
-          '  transfers and card payments from both sides.\n\n' +
-          'Press any key to close.',
-        buttons: [{ label: 'Close', focused: true }],
-      });
-    }
-  });
+  app.render(({ ui, theme: t, height }) => renderFinancesTui(ui, state, t, { height, interval, markdownText: hqtui.markdownText }));
 
   app.on('exit', () => {
     clearInterval(poll);