@profullstack/coinpay 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.10.0] - 2026-09-12
+
+### Added
+- `coinpay finances report`: monthly, quarterly and custom-period activity
+  reports generated server-side from an immutable snapshot, downloadable as
+  PDF, HTML, CSV or JSON (`--period 2026-08`, `--period 2026-Q2`, or
+  `--from/--to` with an exclusive end; `--account`, `--scope`, `--timezone`,
+  `--format`, `--output`, `--strict`, `--wait`, `--json`). Every report
+  states that it was generated by CoinPay from imported account data and is
+  not an institution-issued statement, and carries `local_export_complete`,
+  `provider_coverage` and `reconciliation_status`.
+- `coinpay finances backfill`, `jobs`, `coverage`: durable, resumable
+  calendar-period fetches in provider-safe chunks, with per-account coverage
+  derived from what was actually requested.
+- `coinpay finances statements import|list|get|download|reconcile|delete`:
+  keep original bank statements (PDF, user supplied, never parsed) beside an
+  account and period, and check their balances against a report revision
+  with exact decimal arithmetic.
+- `coinpay finances connect` (setup token prompted without echo or via
+  `--setup-token-stdin`), `disconnect`, `consent <id> on|off`.
+- SDK: `finances-reports` module (`createFinanceReport`, `waitForFinanceReport`,
+  `downloadFinanceReport`, `createBackfillJob`, `getFinanceCoverage`,
+  `importFinanceStatement`, `reconcileFinanceStatement`, ...), and
+  `CoinPayClient.requestBinary()` / `requestForm()` for downloads and uploads.
+- Exit codes for the new subcommands: 0 done or job accepted, 2 invalid
+  input, 3 strict/completeness rejection, 4 authentication, 5 provider or
+  storage failure. In `--json` mode stdout carries only the result.
+
+### Fixed
+- `listAllFinanceTransactions` now forwards `endDate`.
+
 ## [0.9.0] - 2026-09-05
 
 ### Added
@@ -31,6 +62,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Built from about six months of history rather than the dashboard window,
   because a monthly charge is invisible in thirty days of rows, and averaged
   over the history that exists rather than the history requested.
+- `coinpay finances scope <account-id> <business|personal|clear>`, and a `Side`
+  column on the accounts table. Which set of books an account belongs to was a
+  guess from its name, which reads "Business Checking" correctly and is blind to
+  a personal card carrying company spend. The correction is now stored in
+  `finance_accounts.scope_override`, wins over the guess, and survives a re-sync
+  — the same contract as `kind_override`. An overridden account is marked with a
+  trailing `*`, so a wrong split is traceable to a guess rather than a decision.
 - Plain-text `coinpay finances summary|accounts|ledger|connections|sync`
   (`--json` on all of them) for scripts and for Node older than 22.6.
 - SDK `finances` module, also importable as `@profullstack/coinpay/finances`:

package/README.md

@@ -697,6 +697,7 @@ coinpay finances                 # live dashboard (needs `coinpay login`)
 coinpay finances --days 90       # window for earnings / cashflow: 7, 30, 90, 365
 coinpay finances summary         # plain text, --json for machines
 coinpay finances position        # debt vs income, credits vs debits (also: debt)
+coinpay finances scope <id> business   # put an account on the company's books
 coinpay finances accounts        # linked bank & credit-card accounts (SimpleFIN / Plaid)
 coinpay finances ledger --search anthropic --limit 20
 coinpay finances connections     # institutions and their last sync
@@ -718,6 +719,13 @@ instalment, months to clear each balance at its current payment rate, debt-to-in
 debt-service ratio, months of cover, card utilisation, the recurring bills it found with
 their next due date, and a business-versus-personal split of all of it.
 
+The business/personal split starts as a guess from the account name, which gets
+"Business Checking (4672)" right and cannot see a personal card carrying company
+spend. Correct it with `coinpay finances scope <account-id> business|personal`,
+or `clear` to hand it back to the guess. The correction is stored separately from
+the derived value, so a re-sync cannot clobber it, and corrected accounts carry a
+trailing `*` in the `Side` column.
+
 Two things about those numbers. Transfers and card payments are excluded from both
 income and spending — a feed holding both a checking account and the card it pays
 contains every card payment twice, so counting raw credits as income inflates both

package/bin/coinpay.js

@@ -161,6 +161,14 @@ function createUnauthenticatedClient() {
 
 const BOOLEAN_FLAGS = new Set([
   'active',
+  // finances reports / statements
+  'wait',
+  'strict',
+  'setup-token-stdin',
+  'overwrite',
+  'no-pending',
+  'liability-positive',
+  'acknowledge',
   'plain',
   'no-stream',
   'hidden',
@@ -450,10 +458,26 @@ ${colors.cyan}Commands:${colors.reset}
     summary               Plain-text headline numbers (--json for machines)
     position              Debt vs income, credits vs debits, recurring bills
                             (also: coinpay finances debt)
+    scope <id> <side>     Put an account on the business or personal books
+                            (side: business | personal | clear)
     accounts              Linked bank and card accounts with balances
     ledger                Bank/card transactions (--limit, --search, --category, --account)
     connections           Linked institutions and their last sync
     sync                  Pull fresh balances from the bank bridge (--days)
+    connect               Link SimpleFIN: token prompted without echo, or --setup-token-stdin
+    disconnect <id>       Stop syncs and drop the credential; history stays (--yes)
+    consent <id> on|off   Opt a connection into a once-daily background sync
+    backfill              Fetch a calendar period in safe chunks (--period 2026-Q2 |
+                            --from/--to, --connection, --timezone, --wait, --json)
+    jobs [get|cancel <id>] Persisted sync/report jobs; reading one costs no request
+    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)
+    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
 
   ${colors.bright}escrow${colors.reset}
     create                Create a new escrow
@@ -3486,7 +3510,7 @@ const MENU_COMMANDS = [
 const SUBCOMMANDS = {
   config: [['set-key', 'Set your API key'], ['set-url', 'Set custom API URL'], ['show', 'Show current configuration']],
   auth: [['register', 'Register new merchant account'], ['login', 'Login to merchant account'], ['me', 'Show current merchant info']],
-  finances: [['tui', 'Live dashboard (default)'], ['summary', 'Headline numbers as text'], ['position', 'Debt vs income, credits vs debits'], ['accounts', 'Bank & card accounts'], ['ledger', 'Bank/card transactions'], ['connections', 'Linked institutions'], ['sync', 'Pull fresh bank data']],
+  finances: [['tui', 'Live dashboard (default)'], ['summary', 'Headline numbers as text'], ['position', 'Debt vs income, credits vs debits'], ['scope', 'Set an account business or personal'], ['accounts', 'Bank & card accounts'], ['ledger', 'Bank/card transactions'], ['connections', 'Linked institutions'], ['sync', 'Pull fresh bank data'], ['report', 'Monthly/quarterly activity report'], ['backfill', 'Fetch a calendar period'], ['statements', 'Original bank statements'], ['jobs', 'Sync and report jobs']],
   payment: [['create', 'Create a new payment'], ['get', 'Get payment details <id>'], ['list', 'List payments'], ['qr', 'Get payment QR code <id>']],
   invoice: [['create', 'Create a draft invoice'], ['list', 'List invoices'], ['get', 'Get invoice details <id>'], ['update', 'Update a draft invoice <id>'], ['publish', 'Publish an invoice <id>'], ['send', 'Send an invoice <id>'], ['delete', 'Delete a draft invoice <id>']],
   tokens: [['list', 'List checkout tokens']],
@@ -4023,6 +4047,58 @@ async function handleFinances(subcommand, args, flags) {
     case 'dashboard':
     case 'watch': {
       const { client, token, baseUrl } = financesClient();
+
+      // A document for somebody who bills by the hour. Every question it
+      // answers up front is a question nobody pays to have asked, so it
+      // defaults to the whole transaction list and a year of history.
+      if (flags.pdf || flags.report) {
+        const reportDays = Number.isFinite(parsedDays) && parsedDays > 0 ? parsedDays : 365;
+        const limit = Number.parseInt(String(flags.limit ?? ''), 10);
+        const snapshot = await fin.collectFinanceSnapshot(client, {
+          days: reportDays,
+          limit: Number.isFinite(limit) && limit > 0 ? limit : 5000,
+          businessId: flags['business-id'],
+          // Page the whole window. Asking for 5000 returns 500, and a report
+          // built on one page understates the period without saying so.
+          allTransactions: true,
+        });
+        const { buildFinanceReportHtml } = await import('../src/finances-report.js');
+        const html = buildFinanceReportHtml(snapshot, {
+          preparedFor: typeof flags.for === 'string' ? flags.for : '',
+          preparedBy: typeof flags.by === 'string' ? flags.by : '',
+          entity: typeof flags.entity === 'string' ? flags.entity : '',
+          includeTransactions: !flags['no-transactions'],
+          transactionLimit: 0,
+          title: typeof flags.title === 'string' ? flags.title : 'Financial summary',
+        });
+
+        const stamp = new Date().toISOString().slice(0, 10);
+        const base = typeof flags.pdf === 'string' && flags.pdf
+          ? String(flags.pdf).replace(/\.pdf$/i, '')
+          : `finances-${stamp}`;
+        const pdfPath = `${base}.pdf`;
+        const htmlOut = `${base}.html`;
+
+        const { writeFileSync } = await import('node:fs');
+        writeFileSync(htmlOut, html, 'utf8');
+
+        const { htmlToPdf, installHint } = await import('../src/pdf.js');
+        const result = await htmlToPdf(html, pdfPath);
+        if (result.ok) {
+          console.log(`Wrote ${pdfPath}`);
+          console.log(`       ${htmlOut}`);
+        } else {
+          // The HTML is the report. Losing the PDF is a downgrade, not a failure.
+          console.log(`Wrote ${htmlOut}`);
+          console.log('');
+          console.log('Could not render a PDF on this machine.');
+          console.log(installHint(result.tried));
+          console.log('');
+          console.log('Or open the HTML in a browser and print it to PDF.');
+        }
+        return;
+      }
+
       const wantsText = flags.plain || flags.json || !process.stdout.isTTY || !process.stdin.isTTY;
       if (wantsText) {
         const snapshot = await fin.collectFinanceSnapshot(client, { days, businessId: flags['business-id'] });
@@ -4073,6 +4149,30 @@ async function handleFinances(subcommand, args, flags) {
       return;
     }
 
+    case 'scope': {
+      // Which set of books an account belongs to. The name-derived guess is
+      // right about "Business Checking" and blind to a personal card carrying
+      // company spend, so the correction is stored and always wins.
+      const { client } = financesClient();
+      const accountId = args[0];
+      const value = (args[1] || '').toLowerCase();
+      if (!accountId) {
+        print.error('Usage: coinpay finances scope <account-id> <business|personal|clear>  (ids: coinpay finances accounts)');
+        process.exit(1);
+      }
+      const scope = value === 'clear' || value === 'auto' || value === '' ? null : value;
+      if (scope !== null && scope !== 'business' && scope !== 'personal') {
+        print.error(`Unknown scope '${value}'. Use business, personal, or clear.`);
+        process.exit(1);
+      }
+      const account = await fin.updateFinanceAccount(client, accountId, { scope });
+      if (flags.json) { print.json({ account }); return; }
+      print.success(
+        `${account.name} → ${account.effective_scope}${scope === null ? ' (derived from the name again)' : ''}`,
+      );
+      return;
+    }
+
     case 'accounts': {
       const { client } = financesClient();
       const accounts = await fin.listFinanceAccounts(client, { includeHidden: Boolean(flags.hidden) });
@@ -4084,6 +4184,7 @@ async function handleFinances(subcommand, args, flags) {
         { title: 'Institution', render: (a) => a.org_name || '—' },
         { title: 'Account', render: (a) => a.name },
         { title: 'Kind', render: (a) => a.effective_kind || a.kind },
+        { title: 'Side', render: (a) => `${a.effective_scope || '—'}${a.scope_override ? '*' : ''}` },
         { title: 'Balance', align: 'right', render: (a) => money(a.display_balance ?? a.balance ?? 0, a.currency || 'USD') },
         { title: 'Available', align: 'right', render: (a) => (a.available_balance == null ? '—' : money(a.available_balance, a.currency || 'USD')) },
         { title: 'As of', render: (a) => shortDate(a.balance_date) },
@@ -4162,9 +4263,29 @@ async function handleFinances(subcommand, args, flags) {
       return;
     }
 
+    case 'connect':
+    case 'disconnect':
+    case 'consent':
+    case 'backfill':
+    case 'jobs':
+    case 'coverage':
+    case 'report':
+    case 'reports':
+    case 'statements': {
+      const { client } = financesClient();
+      const { runFinancesCommand } = await import('../src/finances-commands.js');
+      const code = await runFinancesCommand(subcommand, args, flags, {
+        client,
+        out: (line) => console.log(line),
+        err: (line) => console.error(line),
+      });
+      if (code !== 0) process.exit(code);
+      return;
+    }
+
     default:
       print.error(`Unknown finances command: ${subcommand}`);
-      console.log('Usage: coinpay finances [tui|summary|accounts|ledger|connections|sync]');
+      console.log('Usage: coinpay finances [tui|summary|accounts|ledger|connections|sync|connect|disconnect|backfill|jobs|coverage|report|reports|statements]');
       process.exit(1);
   }
 }
@@ -4508,12 +4629,16 @@ async function handleOAuth(subcommand, args, flags) {
         description,
       });
 
+      // The API wraps the record: { success, client: { ..., client_secret }, warning }.
+      // Accept a bare record too so either shape prints.
+      const created = result.client ?? result;
+
       print.success('OAuth client created');
-      if (result.client_id) {
-        console.log(`\n  ${colors.bright}Client ID:${colors.reset}     ${result.client_id}`);
+      if (created.client_id) {
+        console.log(`\n  ${colors.bright}Client ID:${colors.reset}     ${created.client_id}`);
       }
-      if (result.client_secret) {
-        console.log(`  ${colors.bright}Client Secret:${colors.reset} ${colors.yellow}${result.client_secret}${colors.reset}`);
+      if (created.client_secret) {
+        console.log(`  ${colors.bright}Client Secret:${colors.reset} ${colors.yellow}${created.client_secret}${colors.reset}`);
         console.log();
         print.warn('Save the client secret — it is only shown once!');
       }
@@ -4531,13 +4656,15 @@ async function handleOAuth(subcommand, args, flags) {
       }
 
       const result = await client.getOAuthClient(id);
-
-      print.success(`OAuth Client: ${result.name || id}`);
-      if (result.client_id) print.info(`  Client ID: ${result.client_id}`);
-      if (result.description) print.info(`  Description: ${result.description}`);
-      if (result.redirect_uris) print.info(`  Redirect URIs: ${result.redirect_uris.join(', ')}`);
-      if (result.scopes) print.info(`  Scopes: ${Array.isArray(result.scopes) ? result.scopes.join(', ') : result.scopes}`);
-      if (result.created_at) print.info(`  Created: ${result.created_at}`);
+      // GET /oauth/clients/:id also wraps the record as { success, client }.
+      const found = result.client ?? result;
+
+      print.success(`OAuth Client: ${found.name || id}`);
+      if (found.client_id) print.info(`  Client ID: ${found.client_id}`);
+      if (found.description) print.info(`  Description: ${found.description}`);
+      if (found.redirect_uris) print.info(`  Redirect URIs: ${found.redirect_uris.join(', ')}`);
+      if (found.scopes) print.info(`  Scopes: ${Array.isArray(found.scopes) ? found.scopes.join(', ') : found.scopes}`);
+      if (found.created_at) print.info(`  Created: ${found.created_at}`);
 
       if (flags.json) print.json(result);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.9.0",
+  "version": "0.10.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",
@@ -58,6 +58,19 @@
     },
     "./finances-tui": {
       "import": "./src/finances-tui.js"
+    },
+    "./finances-reports": {
+      "types": "./src/finances-reports.d.ts",
+      "import": "./src/finances-reports.js",
+      "default": "./src/finances-reports.js"
+    },
+    "./finances-commands": {
+      "import": "./src/finances-commands.js",
+      "default": "./src/finances-commands.js"
+    },
+    "./finances-report": {
+      "import": "./src/finances-report.js",
+      "default": "./src/finances-report.js"
     }
   },
   "files": [
@@ -120,7 +133,7 @@
   "devDependencies": {
     "eslint": "^8.57.0",
     "prettier": "^3.4.1",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.11"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",

package/src/client.d.ts

@@ -313,6 +313,16 @@ export class CoinPayClient {
    * @param eventType  - Event type to simulate (default: `'payment.completed'`)
    */
   testWebhook(businessId: string, eventType?: string): Promise<Record<string, unknown>>;
+  /** Fetch a binary body (PDF, CSV) with its describing headers. */
+  requestBinary(endpoint: string, options?: RequestInit): Promise<{
+    bytes: Uint8Array;
+    contentType: string;
+    filename: string | null;
+    sha256: string | null;
+    headers: Record<string, string>;
+  }>;
+  /** POST a multipart form (file upload). */
+  requestForm(endpoint: string, form: FormData): Promise<any>;
 }
 
 export default CoinPayClient;

package/src/client.js

@@ -77,6 +77,97 @@ export class CoinPayClient {
     }
   }
 
+  /**
+   * Fetch a binary body (a PDF, a CSV) rather than JSON.
+   *
+   * `request()` always parses JSON, which a file download is not. This
+   * returns the bytes plus the headers that describe them; an error body
+   * is still parsed as JSON so its `code` survives.
+   * @param {string} endpoint - API endpoint
+   * @param {Object} [options] - Fetch options
+   * @returns {Promise<{bytes: Uint8Array, contentType: string, filename: string|null, sha256: string|null, headers: Record<string,string>}>}
+   */
+  async requestBinary(endpoint, options = {}) {
+    if (!this.#apiKey) {
+      throw new Error('API key is required for authenticated requests.');
+    }
+    const url = `${this.#baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.#timeout);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+        headers: { 'Authorization': `Bearer ${this.#apiKey}`, ...options.headers },
+      });
+      if (!response.ok) {
+        let data = {};
+        try { data = await response.json(); } catch { /* not JSON */ }
+        const structured = data && data.error && typeof data.error === 'object' ? data.error : null;
+        const error = new Error((structured && structured.message) || data.error || `HTTP ${response.status}`);
+        error.status = response.status;
+        error.response = data;
+        if (structured && structured.code) error.code = structured.code;
+        throw error;
+      }
+      const headers = {};
+      response.headers.forEach((value, key) => { headers[key] = value; });
+      const disposition = headers['content-disposition'] || '';
+      const match = /filename="?([^";]+)"?/i.exec(disposition);
+      return {
+        bytes: new Uint8Array(await response.arrayBuffer()),
+        contentType: headers['content-type'] || 'application/octet-stream',
+        filename: match ? match[1] : null,
+        sha256: headers['x-content-sha256'] || null,
+        headers,
+      };
+    } catch (error) {
+      if (error.name === 'AbortError') throw new Error(`Request timeout after ${this.#timeout}ms`);
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  /**
+   * POST a multipart form (a file upload). The browser/undici sets the
+   * boundary, so no Content-Type is forced here.
+   * @param {string} endpoint - API endpoint
+   * @param {FormData} form - The form to send
+   * @returns {Promise<Object>} API response
+   */
+  async requestForm(endpoint, form) {
+    if (!this.#apiKey) {
+      throw new Error('API key is required for authenticated requests.');
+    }
+    const url = `${this.#baseUrl}${endpoint}`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.#timeout);
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        body: form,
+        signal: controller.signal,
+        headers: { 'Authorization': `Bearer ${this.#apiKey}` },
+      });
+      const data = await response.json();
+      if (!response.ok) {
+        const structured = data && data.error && typeof data.error === 'object' ? data.error : null;
+        const error = new Error((structured && structured.message) || data.error || `HTTP ${response.status}`);
+        error.status = response.status;
+        error.response = data;
+        if (structured && structured.code) error.code = structured.code;
+        throw error;
+      }
+      return data;
+    } catch (error) {
+      if (error.name === 'AbortError') throw new Error(`Request timeout after ${this.#timeout}ms`);
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
   /**
    * Make an unauthenticated API request (for registration/login)
    * @param {string} endpoint - API endpoint