@profullstack/coinpay 0.6.11 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ 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.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.
+- 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

@@ -240,6 +240,30 @@ const { payment, usage } = await client.createPayment({
 }
 ```
 
+#### `client.getTokens(params?)`
+
+List checkout-ready tokens for a business. Use this instead of hard-coding a coin list. Business wallets take priority; merchant global wallets are used as fallback.
+
+```javascript
+const { tokens } = await client.getTokens({
+  businessId: 'biz_123',
+  activeOnly: true,
+});
+
+for (const token of tokens) {
+  console.log(token.code); // "btc", "usdc_pol", ...
+}
+```
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `businessId` | `string` | JWT only | Optional with a business API key; if set, it must match the key scope |
+| `activeOnly` | `boolean` | — | Return active wallets only |
+
+#### `client.getSupportedCoins(params?)`
+
+Returns the lower-level `/api/supported-coins` shape with `coins` instead of token-picker `code` fields.
+
 ---
 
 #### `client.getPayment(paymentId)`
@@ -562,10 +586,87 @@ coinpay payment get pay_abc123
 # List payments
 coinpay payment list --business-id biz_123 --status pending --limit 10
 
+# List checkout tokens
+coinpay tokens list --business-id biz_123 --active-only
+
 # Get QR code
 coinpay payment qr pay_abc123
 ```
 
+### Invoices
+
+Invoice creation is draft-only. It does not send the invoice or move funds.
+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
+# Create a draft invoice
+coinpay invoice create \
+  --amount 250 \
+  --currency USD \
+  --client-id cli_001 \
+  --crypto-currency USDC \
+  --due-date 2026-09-01 \
+  --notes "August development"
+
+# Route eventual settlement through a saved wallet or a direct address
+coinpay invoice create --amount 250 --wallet-id wal_001
+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 \
+  --status sent \
+  --client-id cli_001 \
+  --date-from 2026-08-01 \
+  --date-to 2026-08-31
+
+# Use --json with any invoice command for machine-readable output
+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
@@ -589,6 +690,59 @@ 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 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.
+
+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
@@ -913,6 +1067,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.