@profullstack/coinpay 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,83 @@ 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
+- `coinpay finances` (aliases `coinpay money`, `coinpay tui`): a live terminal
+  dashboard built on `@profullstack/hqtui`. Seven screens — Overview, Bank &
+  Cards, Ledger, Crypto, Cards, Invoices & Escrow, Debt & Income — showing
+  gross volume, commission
+  paid, processor fees, refunds, net earnings, bank assets and liabilities,
+  cashflow, credit-card balances from the SimpleFIN/Plaid feeds, the ledger,
+  crypto and card payment tables, invoices outstanding/overdue and escrow held.
+  Refreshes on a timer and subscribes to the payments SSE stream so crypto
+  payment events appear live. `s` syncs the bank feed on demand.
+- **Debt & Income** screen (`7`), and `coinpay finances position` (aliases
+  `debt`, `income`) as text. Income against spending per month, credits against
+  debits, total owed split into revolving and instalment, months to clear each
+  balance at its current payment rate, debt-to-income, debt-service ratio,
+  months of cover, card utilisation, detected recurring bills with their next
+  due date, and a business-versus-personal split of all of it — so the same
+  feed reads for a company or a person.
+  Transfers and card payments are excluded from both income and spending: a
+  feed holding both a checking account and the card it pays counts every card
+  payment twice otherwise. The raw sides remain visible as gross credits and
+  gross debits.
+  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`:
+  `getFinanceSummary`, `listFinanceAccounts`, `listFinanceTransactions`,
+  `listFinanceConnections`, `syncFinances`, `getDashboardStats`,
+  `getFinanceAnalytics`, `listCryptoPayments`, `listCardTransactions`,
+  `listCardPayouts`, the pure `buildFinanceSnapshot()`, `collectFinanceSnapshot()`
+  and `subscribeToPayments()` (SSE with reconnect).
+
+### Changed
+- New dependency `@profullstack/hqtui` (zero runtime deps of its own). The
+  dashboard needs Node 22.6+; every other command still runs on Node 20.
+
 ## [0.6.11] - 2026-03-19
 
 ### Added

package/README.md

@@ -596,9 +596,9 @@ coinpay payment qr pay_abc123
 ### Invoices
 
 Invoice creation is draft-only. It does not send the invoice or move funds.
-The create command prints the public `/now/{invoiceId}` payment link so it can be
-copied into chat. The payment page becomes available after the invoice is sent.
-Create's JSON output includes the same link as `shareUrl`.
+Drafts do not have a public payment link. Publish the draft to create payment
+details for manual sharing, or send it to create payment details and email the
+client.
 When using a business-scoped API key, --business-id may be omitted.
 
 ```bash
@@ -618,6 +618,29 @@ coinpay invoice create --amount 250 --merchant-wallet-address 0xabc123
 # Get invoice details
 coinpay invoice get inv_abc123
 
+# Update editable fields on a draft. Use --notes= to clear existing notes.
+coinpay invoice update inv_abc123 \
+  --amount 275 \
+  --due-date 2026-09-15 \
+  --notes "Updated scope"
+
+# Publish creates real payment details without emailing the client. It asks for
+# confirmation and prints a live /now/{invoiceId} link for manual chat sharing.
+coinpay invoice publish inv_abc123
+
+# Non-interactive publish requires explicit confirmation.
+coinpay invoice publish inv_abc123 --yes --json
+
+# Send creates real payment details and emails the client. The command asks for
+# confirmation and prints the same /now/{invoiceId} link for manual chat sharing.
+coinpay invoice send inv_abc123
+
+# Non-interactive send requires explicit confirmation. JSON stays on stdout.
+coinpay invoice send inv_abc123 --yes --json
+
+# Permanently delete a draft invoice (also asks for confirmation).
+coinpay invoice delete inv_abc123
+
 # List invoices. Date filters apply to created_at and --date-to includes that day.
 coinpay invoice list \
   --business-id biz_123 \
@@ -630,6 +653,20 @@ coinpay invoice list \
 coinpay invoice list --status paid --json
 ```
 
+Only draft invoices can be updated or deleted. Draft and overdue invoices can
+be sent; sending an overdue invoice issues new payment details and emails the
+client again. Only drafts can be published. `--yes` skips the confirmation for
+publish/send/delete, and is required when any of those commands runs without a
+terminal or with `--json`.
+
+`--wallet-id` updates the invoice's stored wallet reference. To change the
+actual settlement destination, use `--merchant-wallet-address` (or change the
+crypto currency and let the server resolve the configured payee).
+
+The CLI does not post invoice links to `/chat` automatically. Copy the printed
+share link into chat manually. Treat `COINPAY_API_KEY` and `~/.coinpay.json` as
+sensitive: either credential can authorize invoice updates, sends, and deletes.
+
 ### Businesses
 
 ```bash
@@ -653,6 +690,67 @@ coinpay webhook logs biz_123
 coinpay webhook test biz_123 --event payment.completed
 ```
 
+### Finances — your money in one place
+
+```bash
+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
+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
+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**.
+`r` refreshes, `s`
+syncs the bank feed, `w` cycles the window, `p` pauses, `?` shows help, `q` quits. It
+refreshes every 30 seconds (`--interval`) and listens to the payments event stream, so
+a crypto payment shows up the moment it is detected.
+
+**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,
+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
+sides by the whole card-payment volume. The untouched totals stay on screen as gross
+credits and gross debits, so the netting is auditable. And the figures come from about
+six months of history rather than the dashboard window (`w` does not move them), because
+a monthly charge cannot be seen in thirty days of rows; the per-month averages divide by
+the history that actually exists, which for a recently linked feed is much less than six
+months.
+
+It is built on [@profullstack/hqtui](https://hqtui.com) and needs Node 22.6+; the
+plain-text subcommands work on Node 20. Bank data needs the merchant session from
+`coinpay login` (business API keys are refused on purpose).
+
+From the SDK:
+
+```js
+import { CoinPayClient } from '@profullstack/coinpay';
+import { collectFinanceSnapshot } from '@profullstack/coinpay/finances';
+
+const client = new CoinPayClient({ apiKey: sessionToken });
+const snapshot = await collectFinanceSnapshot(client, { days: 30 });
+console.log(snapshot.earnings.netUsd, snapshot.bank.liabilities, snapshot.invoices.totals.overdue);
+```
+
 ---
 
 ## Webhook Integration
@@ -977,6 +1075,41 @@ Tests use [Vitest](https://vitest.dev/) with mocked `fetch` — no API key neede
 
 ---
 
+
+## TaskMarket delegation (x402 v2)
+
+`@profullstack/coinpay/taskmarket` lets an agent or user create and fund a
+[TaskMarket](https://taskmarket.dev) task from inside a CoinPay-powered app,
+using the standard x402 v2 transfer-authorization flow this SDK already speaks.
+
+```js
+import { createTask, discoverTasks, getTask, listSubmissions } from '@profullstack/coinpay/taskmarket';
+
+// Browse open work (public endpoint)
+const open = await discoverTasks({ status: 'open', limit: 25, mode: 'bounty' });
+
+// Create + fund a task. The wallet signs the EIP-712 transfer authorization
+// itself; this module never sees a private key.
+const { taskId } = await createTask(
+  { title: 'Fix my parser bug', description: 'Repro + expected output attached in the linked issue.', reward: 2500000 },
+  {
+    signer: myWalletSigner, // { address, signTypedData({domain, types, primaryType, message}) }
+    capabilities: ['eip155:8453'],
+    spendingLimitUsd: 10,                 // hard cap; refuses anything above
+    authorize: async (d) => confirm(`Send ${d.amount} ${d.asset} to ${d.payTo}?`),
+  }
+);
+
+// Track it and present submissions for human review (never auto-accept)
+const live = await getTask(taskId);
+const submissions = await listSubmissions(taskId);
+```
+
+Safety: no keys ever enter the module; every payment needs fresh `authorize()`
+consent; `spendingLimitUsd` is enforced against the quoted amount in base
+units; after a payment with unknown settlement the caller is told to verify
+with `getTask` instead of retrying blindly.
+
 ## License
 
 [MIT](./LICENSE) © Profullstack, Inc.