@profullstack/coinpay 0.10.0 → 0.11.0

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/bin/coinpay.js

@@ -169,6 +169,10 @@ const BOOLEAN_FLAGS = new Set([
   'no-pending',
   'liability-positive',
   'acknowledge',
+  'always',
+  'no-model',
+  'only-uncategorized',
+  'no-attach',
   'plain',
   'no-stream',
   'hidden',
@@ -478,6 +482,17 @@ ${colors.cyan}Commands:${colors.reset}
     statements import <pdf>  Keep an original bank statement (--account, --period|--from/--to)
     statements list|get|download|reconcile|delete
                           Statement library; reconcile takes --report --opening --closing --currency
+    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 +4286,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 +4303,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.0",
   "description": "CoinPay SDK & CLI \u2014 Accept cryptocurrency and card payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet, swap and a live finances dashboard",
   "type": "module",
   "main": "./src/index.js",

package/src/finances-commands.js

@@ -295,6 +295,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 +328,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 +416,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 +610,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 {
@@ -241,3 +241,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

@@ -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: '{}' });
+}