@profullstack/coinpay 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.17.0] - 2026-10-17
+
+### Added
+- Itemised invoices: `createInvoice` / `updateInvoice` take `lineItems`
+  (description, quantity, unit price, optional tax rate) and a `discount`
+  (`percent` or `fixed`, applied before tax). The server computes the total;
+  `amount` is only for single-amount invoices.
+- `coinpay invoice create --item "Desc|qty|price[|tax %[|tax name]]"`
+  (repeatable) and `--discount 10%` / `--discount 25`.
+- Saved products/services and tax rates: `coinpay item list|create|delete`,
+  `coinpay tax-rate list|create|delete`; SDK `listInvoiceItems`,
+  `createInvoiceItem`, `deleteInvoiceItem`, `listTaxRates`, `createTaxRate`,
+  `deleteTaxRate`.
+
+## [0.16.0] - 2026-10-12
+
+### Added
+- `coinpay finances due [--days 7]`: what is due, overdue or not posted yet
+  across every linked account, projected from each recurring charge's own
+  cadence plus statement due days set on cards and loans.
+- `coinpay finances recurring`: every recurring charge with cadence, last and
+  next date and monthly cost.
+- `coinpay finances due-day <account-id> <1-31|clear> [--amount N|balance]`:
+  a card or loan's statement due day, which no bank feed carries.
+- `coinpay finances daily [show|on|off|send-now]`: the daily summary email
+  (due soon, new activity since the last one, balance sheet).
+- MCP: `finance_due_soon`, `finance_recurring`, `finance_summary`,
+  `finance_transactions`, `finance_set_due_day`, `finance_daily_summary`.
+- SDK: `getDueSoon`, `getDailySummary`, `setDailySummary`,
+  `deleteDailySummary`, `sendDailySummaryNow`, `setAccountDueDay`.
+
+### Fixed
+- `coinpay mcp` `tools/list` now carries `resultType`, `ttlMs` and
+  `cacheScope`; without them Claude Code rejected the whole list
+  ("connected · tools fetch failed").
+
 ## [0.15.0] - 2026-10-07
 
 ### Added

package/bin/coinpay.js

@@ -24,6 +24,12 @@ import {
   sendInvoice,
   updateInvoice,
   InvoiceStatus,
+  listTaxRates,
+  createTaxRate,
+  deleteTaxRate,
+  listInvoiceItems,
+  createInvoiceItem,
+  deleteInvoiceItem,
 } from '../src/invoices.js';
 import { readFileSync, writeFileSync, existsSync, unlinkSync, chmodSync } from 'fs';
 import { execSync, spawn } from 'child_process';
@@ -206,8 +212,18 @@ const BOOLEAN_FLAGS = new Set([
 /**
  * Parse command line arguments
  */
+// Flags that may be given more than once collect into an array.
+const REPEATABLE_FLAGS = new Set(['item']);
+
 function parseArgs(args) {
   const result = { command: null, subcommand: null, args: [], flags: {} };
+  const setFlag = (name, value) => {
+    if (REPEATABLE_FLAGS.has(name) && value !== true) {
+      result.flags[name] = [...(Array.isArray(result.flags[name]) ? result.flags[name] : []), value];
+    } else {
+      result.flags[name] = value;
+    }
+  };
   
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -215,14 +231,14 @@ function parseArgs(args) {
     if (arg.startsWith('--')) {
       const eqIdx = arg.indexOf('=');
       if (eqIdx !== -1) {
-        result.flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+        setFlag(arg.slice(2, eqIdx), arg.slice(eqIdx + 1));
       } else {
         const name = arg.slice(2);
         const next = args[i + 1];
         if (BOOLEAN_FLAGS.has(name)) {
           result.flags[name] = true;
         } else if (next && !next.startsWith('-')) {
-          result.flags[name] = next;
+          setFlag(name, next);
           i++;
         } else {
           result.flags[name] = true;
@@ -289,6 +305,40 @@ function isValidDate(value) {
   );
 }
 
+function parseItemFlags(values) {
+  return values.map((value) => {
+    const [description, qty, price, tax, taxName] = String(value).split('|').map((p) => p.trim());
+    const quantity = Number(qty);
+    const unitPrice = parseNonNegativeAmount(price);
+    const taxRate = tax ? Number(tax) : null;
+    if (!description || !(quantity > 0) || unitPrice === null || (tax && !(taxRate >= 0 && taxRate <= 100))) {
+      print.error('--item must look like "Description|qty|unit price[|tax %[|tax name]]", got: ' + value);
+      process.exit(1);
+    }
+    return {
+      description,
+      quantity,
+      unit_price: unitPrice,
+      ...(taxRate ? { tax_rate: taxRate, tax_name: taxName || null } : {}),
+    };
+  });
+}
+
+function parseNonNegativeAmount(value) {
+  if (typeof value !== 'string' || !/^\d+(\.\d{1,2})?$/.test(value)) return null;
+  return Number(value);
+}
+
+/** "10%" is a percent discount, "25" a fixed one in the invoice currency. */
+function parseDiscountFlag(value) {
+  const match = /^(\d+(?:\.\d+)?)(%?)$/.exec(String(value).trim());
+  if (!match || !(Number(match[1]) > 0)) {
+    print.error('--discount must be a percent like 10% or a fixed amount like 25');
+    process.exit(1);
+  }
+  return { type: match[2] ? 'percent' : 'fixed', value: Number(match[1]) };
+}
+
 function requireFlagValues(flags, names) {
   for (const name of names) {
     if (flags[name] === true) {
@@ -325,6 +375,10 @@ function invoiceForOutput(data, fallbackId) {
     clientId: invoice.clientId ?? invoice.client_id,
     currency: invoice.currency,
     amount: invoice.amount,
+    lineItems: invoice.lineItems ?? invoice.line_items ?? null,
+    subtotal: invoice.subtotal ?? null,
+    discountTotal: invoice.discountTotal ?? invoice.discount_total ?? null,
+    taxTotal: invoice.taxTotal ?? invoice.tax_total ?? null,
     cryptoCurrency: invoice.cryptoCurrency ?? invoice.crypto_currency,
     cryptoAmount: invoice.cryptoAmount ?? invoice.crypto_amount,
     status: invoice.status,
@@ -403,7 +457,9 @@ ${colors.cyan}Commands:${colors.reset}
     qr <id>               Get payment QR code
 
   ${colors.bright}invoice${colors.reset}
-    create                Create a draft invoice (--amount required)
+    create                Create a draft invoice (--amount, or one or more
+                          --item "Desc|qty|price[|tax %[|tax name]]" and
+                          an optional --discount 10% / --discount 25)
       --wallet-id <id>    Route settlement through a saved wallet
       --merchant-wallet-address <address>
                             Route settlement to a direct address
@@ -415,6 +471,17 @@ ${colors.cyan}Commands:${colors.reset}
     delete <id>           Permanently delete a draft invoice
       --yes               Skip confirmation for publish/send/delete
 
+  ${colors.bright}item${colors.reset}
+    list                  Saved products/services (--business-id)
+    create                Save one: --name, --price [--unit hour] [--description]
+                          [--tax-rate-id <id>]
+    delete <id>           Delete a saved item (issued invoices keep their copy)
+
+  ${colors.bright}tax-rate${colors.reset}
+    list                  Saved tax rates (--business-id)
+    create                Save one: --name "CA Sales Tax" --rate 8.25 [--default]
+    delete <id>           Delete a saved tax rate
+
   ${colors.bright}tokens${colors.reset}
     list                  List checkout tokens (--business-id, --active-only)
 
@@ -529,6 +596,10 @@ ${colors.cyan}Commands:${colors.reset}
                             --with-documents attaches the period's tax documents within
                             8 MiB; only to your own address)
     digest [show|set|off|send-now]  Weekly digest email (--days mon,fri --hour 8 --to …)
+    due [--days 7]        What is due and overdue across every account (--days up to 60)
+    recurring             Every recurring charge detected, with next date and monthly cost
+    due-day <id> <1-31|clear>  A card/loan's statement due day (--amount 810.46, or balance)
+    daily [show|on|off|send-now]  Daily summary email: due soon, new activity, position (--hour 7 --to …)
 
   ${colors.bright}escrow${colors.reset}
     create                Create a new escrow
@@ -1064,6 +1135,15 @@ function printInvoiceDetails(invoice, { shareUrl } = {}) {
   console.log('\n' + colors.bright + label + colors.reset);
   print.info('ID: ' + invoice.id);
   print.info('Status: ' + (invoice.status || 'unknown'));
+  if (Array.isArray(invoice.lineItems) && invoice.lineItems.length > 0) {
+    for (const line of invoice.lineItems) {
+      const tax = line.tax_rate ? ' +' + line.tax_rate + '% ' + (line.tax_name || 'tax') : '';
+      print.info('  ' + line.description.split('\n')[0] + ': ' + line.quantity + ' x ' + line.unit_price + ' = ' + line.amount + tax);
+    }
+    print.info('Subtotal: ' + invoice.subtotal);
+    if (Number(invoice.discountTotal) > 0) print.info('Discount: -' + invoice.discountTotal);
+    if (Number(invoice.taxTotal) > 0) print.info('Tax: ' + invoice.taxTotal);
+  }
   print.info('Amount: ' + invoice.amount + ' ' + (invoice.currency || ''));
   if (invoice.businessId) print.info('Business: ' + invoice.businessId);
   if (invoice.clientId) print.info('Client: ' + invoice.clientId);
@@ -1084,6 +1164,92 @@ function printInvoiceDetails(invoice, { shareUrl } = {}) {
 /**
  * Invoice commands
  */
+async function handleCatalog(kind, subcommand, args, flags) {
+  const client = createClient();
+  const isItem = kind === 'item';
+  requireFlagValues(flags, ['business-id', 'name', 'price', 'unit', 'description', 'tax-rate-id', 'rate']);
+
+  switch (subcommand) {
+    case 'list': {
+      const rows = isItem
+        ? await listInvoiceItems(client, { businessId: flags['business-id'] })
+        : await listTaxRates(client, { businessId: flags['business-id'] });
+      if (flags.json) {
+        print.json(rows);
+        break;
+      }
+      if (rows.length === 0) {
+        print.info(isItem ? 'No saved items' : 'No saved tax rates');
+        break;
+      }
+      for (const row of rows) {
+        print.info(
+          isItem
+            ? row.id + '  ' + row.name + '  ' + row.unit_price + (row.unit ? ' / ' + row.unit : '')
+            : row.id + '  ' + row.name + '  ' + row.rate + '%' + (row.is_default ? '  (default)' : '')
+        );
+      }
+      break;
+    }
+
+    case 'create': {
+      if (!flags.name) {
+        print.error('--name is required');
+        process.exit(1);
+      }
+      let row;
+      if (isItem) {
+        const unitPrice = parseNonNegativeAmount(flags.price);
+        if (unitPrice === null) {
+          print.error('--price must be a decimal with at most two decimal places');
+          process.exit(1);
+        }
+        row = await createInvoiceItem(client, {
+          businessId: flags['business-id'],
+          name: flags.name,
+          unitPrice,
+          description: flags.description,
+          unit: flags.unit,
+          taxRateId: flags['tax-rate-id'],
+        });
+      } else {
+        const rate = Number(flags.rate);
+        if (flags.rate === undefined || !(rate >= 0 && rate <= 100)) {
+          print.error('--rate must be a percent between 0 and 100');
+          process.exit(1);
+        }
+        row = await createTaxRate(client, {
+          businessId: flags['business-id'],
+          name: flags.name,
+          rate,
+          isDefault: flags.default === true || flags.default === 'true',
+        });
+      }
+      if (flags.json) {
+        print.json(row);
+        break;
+      }
+      print.success((isItem ? 'Item' : 'Tax rate') + ' saved: ' + row.id);
+      break;
+    }
+
+    case 'delete': {
+      if (args.length !== 1) {
+        print.error('Usage: coinpay ' + kind + ' delete <id>');
+        process.exit(1);
+      }
+      if (isItem) await deleteInvoiceItem(client, args[0]);
+      else await deleteTaxRate(client, args[0]);
+      print.success('Deleted ' + args[0]);
+      break;
+    }
+
+    default:
+      print.error('Usage: coinpay ' + kind + ' <list|create|delete>');
+      process.exit(1);
+  }
+}
+
 async function handleInvoice(subcommand, args, flags) {
   const client = createClient();
 
@@ -1099,12 +1265,23 @@ async function handleInvoice(subcommand, args, flags) {
         'notes',
         'wallet-id',
         'merchant-wallet-address',
+        'item',
+        'discount',
       ]);
 
-      const amount = parsePositiveAmount(flags.amount);
-      if (amount === null) {
+      // --item "Description|qty|unit price[|tax %[|tax name]]", repeatable.
+      const lineItems = flags.item === undefined ? undefined : parseItemFlags(flags.item);
+      const discount = flags.discount === undefined ? undefined : parseDiscountFlag(flags.discount);
+      if (discount && !lineItems) {
+        print.error('--discount applies to itemised invoices; add one or more --item');
+        process.exit(1);
+      }
+
+      const amount = lineItems ? undefined : parsePositiveAmount(flags.amount);
+      if (!lineItems && amount === null) {
         print.error('--amount must be a positive decimal with at most two decimal places');
         print.info('Example: coinpay invoice create --amount 125 --currency USD --notes "Consulting"');
+        print.info('Or itemise: coinpay invoice create --item "Design|3|100" --item "Hosting|1|19.99|8.25|CA tax"');
         process.exit(1);
       }
 
@@ -1126,6 +1303,8 @@ async function handleInvoice(subcommand, args, flags) {
         clientId: flags['client-id'],
         currency: currency.toUpperCase(),
         amount,
+        lineItems,
+        discount,
         cryptoCurrency: cryptoCurrency?.toUpperCase(),
         dueDate,
         notes: flags.notes,
@@ -4355,7 +4534,12 @@ async function handleFinances(subcommand, args, flags) {
     case 'statements':
     case 'books':
     case 'payloads':
-    case 'digest': {
+    case 'digest':
+    case 'due':
+    case 'due-soon':
+    case 'recurring':
+    case 'due-day':
+    case 'daily': {
       const { client } = financesClient();
       const { runFinancesCommand } = await import('../src/finances-commands.js');
       const code = await runFinancesCommand(subcommand, args, flags, {
@@ -4369,7 +4553,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|books|payloads|digest]');
+      console.log('Usage: coinpay finances [tui|summary|accounts|ledger|connections|sync|connect|disconnect|backfill|jobs|coverage|report|reports|statements|books|payloads|digest|due|recurring|due-day|daily]');
       process.exit(1);
   }
 }
@@ -4580,6 +4764,11 @@ async function handleLightning(subcommand, args, flags) {
         await handleInvoice(subcommand, args, flags);
         break;
 
+      case 'item':
+      case 'tax-rate':
+        await handleCatalog(command, subcommand, args, flags);
+        break;
+
       case 'tokens':
         await handleTokens(subcommand, args, flags);
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.15.0",
+  "version": "0.17.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

@@ -846,6 +846,80 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
         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 'due':
+      case 'due-soon':
+      case 'recurring': {
+        const days = flags.days !== undefined ? Number(flags.days) : undefined;
+        if (days !== undefined && (!Number.isInteger(days) || days < 0 || days > 60)) throw new CliExit(EXIT.INVALID, '--days must be 0 to 60');
+        const d = await api.getDueSoon(client, { days, timezone: typeof flags.timezone === 'string' ? flags.timezone : undefined });
+        const cur = d.currency || 'USD';
+        const money = (n) => new Intl.NumberFormat('en-US', { style: 'currency', currency: cur }).format(n);
+        if (subcommand === 'recurring') {
+          if (json) { out(JSON.stringify(d.recurring, null, 2)); return EXIT.OK; }
+          const rows = [...d.recurring.charges].sort((a, b) => a.nextExpected.localeCompare(b.nextExpected));
+          out(`${rows.length} recurring charges · ${money(d.recurring.monthlyTotal)}/mo${d.recurring.monthlyDebtService ? ` (${money(d.recurring.monthlyDebtService)} debt service)` : ''}`);
+          for (const c of rows) {
+            out(`  next ${c.nextExpected.slice(0, 10)}  ${c.cadence.padEnd(9)} ${money(c.amount).padStart(11)}  ${c.payee}  · ${c.accountName}${c.isDebtService ? ' · debt' : ''}`);
+          }
+          return EXIT.OK;
+        }
+        if (json) { out(JSON.stringify(d, null, 2)); return EXIT.OK; }
+        const when = (i) => i.status === 'paid' ? 'paid' : i.status === 'awaiting' ? 'not yet?' : i.daysUntil === 0 ? 'today' : i.daysUntil === 1 ? 'tomorrow' : i.daysUntil < 0 ? `${-i.daysUntil}d LATE` : `in ${i.daysUntil}d`;
+        const amt = (i) => i.amount !== null ? money(i.amount) : i.owed !== null ? `bal ${money(i.owed)}` : 'statement';
+        out(`${d.today} (${d.timezone}) · ${money(d.totals.due)} due in ${d.horizonDays} days${d.totals.overdue ? ` · ${money(d.totals.overdue)} OVERDUE` : ''}${d.totals.unpriced ? ` · +${d.totals.unpriced} statement balance(s)` : ''}`);
+        if (d.items.length === 0 && d.paid.length === 0) out('  Nothing due.');
+        for (const i of [...d.items, ...d.paid]) {
+          out(`  ${i.dueOn}  ${when(i).padEnd(9)} ${amt(i).padStart(14)}  ${i.payee}  · ${i.accountName}${i.source === 'scheduled' ? ' · statement due' : ''}`);
+        }
+        if (d.missed.length) out(`  Not seen lately: ${d.missed.slice(0, 8).map((m) => `${m.payee} (expected ${m.expectedOn})`).join(', ')}`);
+        return EXIT.OK;
+      }
+
+      case 'due-day': {
+        const id = args[0];
+        const value = args[1];
+        if (!id || value === undefined) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances due-day <account-id> <1-31|clear> [--amount 810.46|--amount balance]  (ids: coinpay finances accounts)');
+        const day = value === 'clear' || value === 'off' ? null : Number(value);
+        if (day !== null && (!Number.isInteger(day) || day < 1 || day > 31)) throw new CliExit(EXIT.INVALID, 'The due day must be 1 to 31, or clear');
+        const amount = flags.amount === undefined ? undefined : flags.amount === 'balance' || flags.amount === true ? null : String(flags.amount);
+        const account = await api.setAccountDueDay(client, id, { day, amount });
+        emit({ account }, day === null ? `Cleared the due day on ${account.name}.` : `${account.name}: due on day ${day}${account.payment_due_amount != null ? `, ${account.payment_due_amount}` : ', statement balance'}.`);
+        return EXIT.OK;
+      }
+
+      case 'daily': {
+        const action = flags.off ? 'off' : args[0] || 'show';
+        const describe = (s) => s
+          ? `Daily summary ${s.active ? 'on' : 'off'} · ${String(s.hour).padStart(2, '0')}:00 ${s.timezone} · to ${s.recipients.join(', ')}${s.nextRunAt ? ` · next ${s.nextRunAt}` : ''}${s.lastSentAt ? ` · last ${s.lastSentAt}` : ''}`
+          : 'No daily summary configured. Turn it on with: coinpay finances daily on --hour 7 --to you@example.com';
+        if (action === 'show') {
+          const s = await api.getDailySummary(client);
+          emit({ schedule: s }, describe(s));
+          return EXIT.OK;
+        }
+        if (action === 'on' || action === 'set') {
+          const s = await api.setDailySummary(client, {
+            hour: flags.hour !== undefined ? Number(flags.hour) : undefined,
+            timezone: typeof flags.timezone === 'string' ? flags.timezone : undefined,
+            recipients: flags.to ? listFlag(flags.to) : undefined,
+            active: true,
+          });
+          emit({ schedule: s }, describe(s));
+          return EXIT.OK;
+        }
+        if (action === 'off' || action === 'delete') {
+          const data = await api.deleteDailySummary(client);
+          emit(data, 'Daily summary turned off.');
+          return EXIT.OK;
+        }
+        if (action === 'send-now') {
+          const data = await api.sendDailySummaryNow(client);
+          emit(data, `Sent to ${data.sent.join(', ') || 'nobody'} (${data.due} due, ${data.overdue} overdue)${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 daily [show|on --hour 7 --to a@x|off|send-now]');
+      }
+
       case 'payloads': {
         const action = args[0] || 'list';
         if (action === 'list') {
@@ -881,4 +955,4 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
   }
 }
 
-export const EXTENDED_SUBCOMMANDS = ['connect', 'disconnect', 'consent', 'backfill', 'jobs', 'coverage', 'report', 'reports', 'statements', 'books', 'payloads', 'digest'];
+export const EXTENDED_SUBCOMMANDS = ['connect', 'disconnect', 'consent', 'backfill', 'jobs', 'coverage', 'report', 'reports', 'statements', 'books', 'payloads', 'digest', 'due', 'due-soon', 'recurring', 'due-day', 'daily'];

package/src/finances-reports.d.ts

@@ -395,3 +395,44 @@ export function setWeeklyDigest(
 ): Promise<WeeklyDigest>;
 export function deleteWeeklyDigest(client: CoinPayClient): Promise<{ success: boolean }>;
 export function sendWeeklyDigestNow(client: CoinPayClient): Promise<SendOutcome>;
+
+export interface DueItem {
+  source: 'projected' | 'scheduled';
+  payee: string;
+  amount: number | null;
+  owed: number | null;
+  cadence: string;
+  dueOn: string;
+  daysUntil: number;
+  status: 'overdue' | 'awaiting' | 'today' | 'soon' | 'paid';
+  accountId: string;
+  accountName: string;
+  scope: 'business' | 'personal';
+  isDebtService: boolean;
+}
+
+export interface DueSoon {
+  timezone: string;
+  today: string;
+  horizonDays: number;
+  items: DueItem[];
+  paid: DueItem[];
+  missed: Array<{ payee: string; amount: number; expectedOn: string; lastSeen: string; accountName: string }>;
+  totals: { due: number; overdue: number; unpriced: number };
+  recurring: {
+    charges: Array<{ payee: string; amount: number; cadence: string; occurrences: number; lastSeen: string; nextExpected: string; monthlyEquivalent: number; scope: 'business' | 'personal'; isDebtService: boolean; accountId: string; accountName: string }>;
+    monthlyTotal: number;
+    monthlyDebtService: number;
+  };
+  currency: string | null;
+}
+
+export function getDueSoon(client: CoinPayClient, opts?: { days?: number; timezone?: string }): Promise<DueSoon>;
+export function getDailySummary(client: CoinPayClient): Promise<WeeklyDigest | null>;
+export function setDailySummary(
+  client: CoinPayClient,
+  opts?: { weekdays?: number[]; hour?: number; timezone?: string; recipients?: string[]; active?: boolean },
+): Promise<WeeklyDigest>;
+export function deleteDailySummary(client: CoinPayClient): Promise<{ success: boolean }>;
+export function sendDailySummaryNow(client: CoinPayClient): Promise<{ sent: string[]; failed: Array<{ to: string; error: string }>; due: number; overdue: number }>;
+export function setAccountDueDay(client: CoinPayClient, accountId: string, opts: { day: number | null; amount?: number | string | null }): Promise<Record<string, unknown>>;

package/src/finances-reports.js

@@ -445,3 +445,42 @@ export async function deleteWeeklyDigest(client) {
 export async function sendWeeklyDigestNow(client) {
   return call(client, '/finances/email-schedules/send-now', { method: 'POST', body: '{}' });
 }
+
+/** Charges due across every account: projected recurring charges plus statement due days. */
+export async function getDueSoon(client, { days, timezone } = {}) {
+  const params = new URLSearchParams();
+  if (days !== undefined) params.set('days', String(days));
+  if (timezone) params.set('timezone', timezone);
+  const qs = params.toString();
+  const data = await call(client, `/finances/due-soon${qs ? `?${qs}` : ''}`);
+  return data.dueSoon;
+}
+
+export async function getDailySummary(client) {
+  const data = await call(client, '/finances/email-schedules?kind=daily_summary');
+  return data.schedule;
+}
+
+export async function setDailySummary(client, { weekdays, hour, timezone, recipients, active } = {}) {
+  const data = await call(client, '/finances/email-schedules', {
+    method: 'POST',
+    body: JSON.stringify({ kind: 'daily_summary', weekdays, hour, timezone, recipients, active }),
+  });
+  return data.schedule;
+}
+
+export async function deleteDailySummary(client) {
+  return call(client, '/finances/email-schedules?kind=daily_summary', { method: 'DELETE' });
+}
+
+export async function sendDailySummaryNow(client) {
+  return call(client, '/finances/email-schedules/send-now?kind=daily_summary', { method: 'POST', body: '{}' });
+}
+
+/** Set (or clear with day null) a card or loan's statement due day and fixed amount. */
+export async function setAccountDueDay(client, accountId, { day, amount } = {}) {
+  const body = { payment_due_day: day ?? null };
+  if (amount !== undefined) body.payment_due_amount = amount;
+  const data = await call(client, `/finances/accounts/${encodeURIComponent(accountId)}`, { method: 'PATCH', body: JSON.stringify(body) });
+  return data.account;
+}

package/src/index.d.ts

@@ -55,9 +55,20 @@ export {
   sendInvoice,
   getInvoicePaymentData,
   InvoiceStatus,
+  listTaxRates,
+  createTaxRate,
+  deleteTaxRate,
+  listInvoiceItems,
+  createInvoiceItem,
+  deleteInvoiceItem,
 } from './invoices.js';
 export type {
   Invoice,
+  InvoiceLine,
+  InvoiceLineInput,
+  InvoiceDiscount,
+  TaxRate,
+  InvoiceItem,
   InvoiceStatusType,
   CreateInvoiceParams,
   ListInvoicesParams,

package/src/index.js

@@ -82,6 +82,12 @@ import {
   sendInvoice,
   getInvoicePaymentData,
   InvoiceStatus,
+  listTaxRates,
+  createTaxRate,
+  deleteTaxRate,
+  listInvoiceItems,
+  createInvoiceItem,
+  deleteInvoiceItem,
 } from './invoices.js';
 
 // Wallet exports
@@ -231,6 +237,12 @@ export {
   sendInvoice,
   getInvoicePaymentData,
   InvoiceStatus,
+  listTaxRates,
+  createTaxRate,
+  deleteTaxRate,
+  listInvoiceItems,
+  createInvoiceItem,
+  deleteInvoiceItem,
   
   // Wallet
   WalletClient,

package/src/invoices.d.ts

@@ -10,6 +10,27 @@ export const InvoiceStatus: {
 
 export type InvoiceStatusType = (typeof InvoiceStatus)[keyof typeof InvoiceStatus];
 
+export interface InvoiceLineInput {
+  description: string;
+  quantity: number;
+  unit_price: number;
+  tax_rate?: number | null;
+  tax_name?: string | null;
+  item_id?: string | null;
+}
+
+export interface InvoiceLine extends Required<InvoiceLineInput> {
+  /** quantity x unit_price, before discount and tax */
+  amount: number;
+  discount: number;
+  tax: number;
+}
+
+export interface InvoiceDiscount {
+  type: 'percent' | 'fixed';
+  value: number;
+}
+
 export interface Invoice {
   id: string;
   invoiceNumber?: string;
@@ -17,6 +38,11 @@ export interface Invoice {
   clientId?: string;
   currency?: string;
   amount?: number;
+  lineItems?: InvoiceLine[] | null;
+  subtotal?: number | null;
+  discount?: InvoiceDiscount | null;
+  discountTotal?: number | null;
+  taxTotal?: number | null;
   cryptoCurrency?: string;
   cryptoAmount?: string | number;
   status?: InvoiceStatusType;
@@ -36,7 +62,10 @@ export interface CreateInvoiceParams {
   businessId?: string;
   clientId?: string;
   currency: string;
-  amount: number;
+  /** Required unless lineItems is given; the server computes itemised totals. */
+  amount?: number;
+  lineItems?: InvoiceLineInput[];
+  discount?: InvoiceDiscount;
   cryptoCurrency?: string;
   dueDate?: string;
   notes?: string;
@@ -54,6 +83,9 @@ export interface ListInvoicesParams {
 
 export interface UpdateInvoiceParams {
   amount?: number;
+  /** Replace the lines; null turns itemising off. */
+  lineItems?: InvoiceLineInput[] | null;
+  discount?: InvoiceDiscount | null;
   currency?: string;
   cryptoCurrency?: string;
   dueDate?: string;
@@ -76,3 +108,42 @@ export function deleteInvoice(client: CoinPayClient, id: string): Promise<Record
 export function publishInvoice(client: CoinPayClient, id: string): Promise<Record<string, unknown>>;
 export function sendInvoice(client: CoinPayClient, id: string): Promise<Record<string, unknown>>;
 export function getInvoicePaymentData(client: CoinPayClient, id: string): Promise<Record<string, unknown>>;
+
+export interface TaxRate {
+  id: string;
+  business_id: string;
+  name: string;
+  rate: number;
+  is_default: boolean;
+}
+
+export interface InvoiceItem {
+  id: string;
+  business_id: string;
+  name: string;
+  description: string | null;
+  unit_price: number;
+  unit: string | null;
+  tax_rate_id: string | null;
+  archived: boolean;
+}
+
+export function listTaxRates(client: CoinPayClient, options?: { businessId?: string }): Promise<TaxRate[]>;
+export function createTaxRate(
+  client: CoinPayClient,
+  options: { businessId?: string; name: string; rate: number; isDefault?: boolean }
+): Promise<TaxRate>;
+export function deleteTaxRate(client: CoinPayClient, id: string): Promise<Record<string, unknown>>;
+export function listInvoiceItems(client: CoinPayClient, options?: { businessId?: string }): Promise<InvoiceItem[]>;
+export function createInvoiceItem(
+  client: CoinPayClient,
+  options: {
+    businessId?: string;
+    name: string;
+    unitPrice: number;
+    description?: string;
+    unit?: string;
+    taxRateId?: string;
+  }
+): Promise<InvoiceItem>;
+export function deleteInvoiceItem(client: CoinPayClient, id: string): Promise<Record<string, unknown>>;

package/src/invoices.js

@@ -35,7 +35,10 @@
  * @param {string} [options.businessId] - Business ID (optional for business-scoped API keys)
  * @param {string} [options.clientId] - Client ID (optional)
  * @param {string} options.currency - Fiat currency code (USD, EUR, etc.)
- * @param {number} options.amount - Invoice amount
+ * @param {number} [options.amount] - Invoice amount (omit when lineItems is given)
+ * @param {Array<{description: string, quantity: number, unit_price: number, tax_rate?: number, tax_name?: string, item_id?: string}>} [options.lineItems]
+ *   Itemised lines; the server computes the total from them
+ * @param {{type: 'percent'|'fixed', value: number}} [options.discount] - Invoice-level discount, applied before tax
  * @param {string} [options.cryptoCurrency] - Preferred crypto for payment
  * @param {string} [options.dueDate] - Due date (ISO string or YYYY-MM-DD)
  * @param {string} [options.notes] - Notes / description
@@ -48,6 +51,8 @@ export async function createInvoice(client, {
   clientId,
   currency,
   amount,
+  lineItems,
+  discount,
   cryptoCurrency,
   dueDate,
   notes,
@@ -57,8 +62,13 @@ export async function createInvoice(client, {
   const body = {
     business_id: businessId,
     currency,
-    amount,
   };
+  if (lineItems) {
+    body.line_items = lineItems;
+    if (discount) body.discount = discount;
+  } else {
+    body.amount = amount;
+  }
   if (clientId) body.client_id = clientId;
   if (cryptoCurrency) body.crypto_currency = cryptoCurrency;
   if (dueDate) body.due_date = dueDate;
@@ -124,7 +134,9 @@ export async function getInvoice(client, id) {
  * @param {CoinPayClient} client
  * @param {string} id - Invoice ID
  * @param {Object} updates - Partial invoice fields to update
- * @param {number} [updates.amount] - Updated amount
+ * @param {number} [updates.amount] - Updated amount (single-amount invoices only)
+ * @param {Array|null} [updates.lineItems] - Replace the lines (null turns itemising off)
+ * @param {Object|null} [updates.discount] - Replace the discount
  * @param {string} [updates.currency] - Updated currency
  * @param {string} [updates.cryptoCurrency] - Updated crypto currency
  * @param {string} [updates.dueDate] - Updated due date
@@ -137,6 +149,8 @@ export async function getInvoice(client, id) {
 export async function updateInvoice(client, id, updates) {
   const body = {};
   if (updates.amount !== undefined) body.amount = updates.amount;
+  if (updates.lineItems !== undefined) body.line_items = updates.lineItems;
+  if (updates.discount !== undefined) body.discount = updates.discount;
   if (updates.currency !== undefined) body.currency = updates.currency;
   if (updates.cryptoCurrency !== undefined) body.crypto_currency = updates.cryptoCurrency;
   if (updates.dueDate !== undefined) body.due_date = updates.dueDate;
@@ -233,6 +247,11 @@ function normalizeInvoice(data) {
     clientId: invoice.client_id,
     currency: invoice.currency,
     amount: invoice.amount,
+    lineItems: invoice.line_items,
+    subtotal: invoice.subtotal,
+    discount: invoice.discount,
+    discountTotal: invoice.discount_total,
+    taxTotal: invoice.tax_total,
     cryptoCurrency: invoice.crypto_currency,
     cryptoAmount: invoice.crypto_amount,
     status: invoice.status,
@@ -248,3 +267,52 @@ function normalizeInvoice(data) {
     updatedAt: invoice.updated_at,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Catalog: saved tax rates and products/services for itemised invoices.
+// An API key is locked to its own business, so businessId is optional there.
+// ---------------------------------------------------------------------------
+
+function businessQuery(businessId) {
+  return businessId ? '?business_id=' + encodeURIComponent(businessId) : '';
+}
+
+/** List a business's saved tax rates. */
+export async function listTaxRates(client, { businessId } = {}) {
+  const data = await client.request('/tax-rates' + businessQuery(businessId));
+  return data.tax_rates ?? [];
+}
+
+/** Save a tax rate (percent, up to three decimals). */
+export async function createTaxRate(client, { businessId, name, rate, isDefault }) {
+  const body = { name, rate };
+  if (businessId) body.business_id = businessId;
+  if (isDefault !== undefined) body.is_default = isDefault;
+  const data = await client.request('/tax-rates', { method: 'POST', body: JSON.stringify(body) });
+  return data.tax_rate;
+}
+
+export async function deleteTaxRate(client, id) {
+  return client.request('/tax-rates/' + encodeURIComponent(id), { method: 'DELETE' });
+}
+
+/** List a business's saved products and services. */
+export async function listInvoiceItems(client, { businessId } = {}) {
+  const data = await client.request('/invoice-items' + businessQuery(businessId));
+  return data.invoice_items ?? [];
+}
+
+/** Save a product or service to bill again later. */
+export async function createInvoiceItem(client, { businessId, name, unitPrice, description, unit, taxRateId }) {
+  const body = { name, unit_price: unitPrice };
+  if (businessId) body.business_id = businessId;
+  if (description) body.description = description;
+  if (unit) body.unit = unit;
+  if (taxRateId) body.tax_rate_id = taxRateId;
+  const data = await client.request('/invoice-items', { method: 'POST', body: JSON.stringify(body) });
+  return data.invoice_item;
+}
+
+export async function deleteInvoiceItem(client, id) {
+  return client.request('/invoice-items/' + encodeURIComponent(id), { method: 'DELETE' });
+}

package/src/mcp.js

@@ -13,7 +13,7 @@
 import { createInterface } from 'node:readline';
 
 import * as reports from './finances-reports.js';
-import { listFinanceAccounts } from './finances.js';
+import { getFinanceSummary, listFinanceAccounts, listFinanceTransactions } from './finances.js';
 import * as sf from './statements-fetch.js';
 
 export const PROTOCOL_VERSION = '2025-06-18';
@@ -28,6 +28,88 @@ export const TOOLS = [
     inputSchema: { type: 'object', properties: { includeHidden: { type: 'boolean' } }, additionalProperties: false },
     handler: async (args, { client }) => text({ accounts: await listFinanceAccounts(client, { includeHidden: args.includeHidden === true }) }),
   },
+  {
+    name: 'finance_due_soon',
+    description:
+      'What is due across every linked account: overdue, today and the next N days. Projected from each recurring charge\'s own cadence, plus statement due days set on cards and loans. Also lists charges that stopped appearing ("missed") and paid-this-cycle statements.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'integer', minimum: 0, maximum: 60, description: 'Horizon in days (default 7)' },
+        timezone: { type: 'string', description: 'IANA zone for "today"; defaults to the saved finance timezone' },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => {
+      const { recurring, ...due } = await reports.getDueSoon(client, { days: args.days, timezone: args.timezone });
+      return text({ ...due, recurringMonthlyTotal: recurring.monthlyTotal });
+    },
+  },
+  {
+    name: 'finance_recurring',
+    description: 'Every recurring charge detected across all accounts (subscriptions, bills, loan and card payments): cadence, typical amount, last and next date, monthly equivalent.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    handler: async (_args, { client }) => text((await reports.getDueSoon(client, { days: 0 })).recurring),
+  },
+  {
+    name: 'finance_summary',
+    description: 'Balance sheet (assets, debt, net by currency), cashflow for the window, top spending categories, and the debt-and-income position.',
+    inputSchema: { type: 'object', properties: { days: { type: 'integer', minimum: 1, maximum: 3650, description: 'Cashflow window (default 30)' } }, additionalProperties: false },
+    handler: async (args, { client }) => text(await getFinanceSummary(client, { days: args.days || 30 })),
+  },
+  {
+    name: 'finance_transactions',
+    description: 'The bank and card ledger, newest first. Filter by account id, text search, category or date range (YYYY-MM-DD).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        accountId: { type: 'string' },
+        search: { type: 'string' },
+        category: { type: 'string' },
+        startDate: { type: 'string' },
+        endDate: { type: 'string' },
+        limit: { type: 'integer', minimum: 1, maximum: 500 },
+        offset: { type: 'integer', minimum: 0 },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text(await listFinanceTransactions(client, { ...args, limit: args.limit || 50 })),
+  },
+  {
+    name: 'finance_set_due_day',
+    description: 'Set or clear a card or loan\'s statement due day (1-31, null clears) and optionally a fixed monthly amount (null = statement balance). Puts the account on the due-soon list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        accountId: { type: 'string' },
+        day: { type: ['integer', 'null'], minimum: 1, maximum: 31 },
+        amount: { type: ['number', 'string', 'null'] },
+      },
+      required: ['accountId', 'day'],
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text({ account: await reports.setAccountDueDay(client, args.accountId, { day: args.day, amount: args.amount }) }),
+  },
+  {
+    name: 'finance_daily_summary',
+    description: 'The daily summary email (due soon, new activity, position): show it, turn it on (optionally hour 0-23 and recipients), turn it off, or send one now.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['show', 'on', 'off', 'send_now'] },
+        hour: { type: 'integer', minimum: 0, maximum: 23 },
+        to: { type: 'array', items: { type: 'string' }, maxItems: 5 },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => {
+      if (args.action === 'on') return text({ schedule: await reports.setDailySummary(client, { hour: args.hour, recipients: args.to, active: true }) });
+      if (args.action === 'off') return text(await reports.deleteDailySummary(client));
+      if (args.action === 'send_now') return text(await reports.sendDailySummaryNow(client));
+      return text({ schedule: await reports.getDailySummary(client) });
+    },
+  },
   {
     name: 'statements_list',
     description: 'List PDF statements in the CoinPay statement library, optionally for one account or period (2026-08, 2026-Q3).',
@@ -151,7 +233,7 @@ export async function handleMessage(message, ctx) {
         capabilities: { tools: {} },
         serverInfo: { name: 'coinpay', version: ctx.version || '0.0.0' },
         instructions:
-          'CoinPay finances. Statement PDFs come from the banks themselves (SimpleFIN has none): statements_coverage shows what is missing, statements_fetch downloads what is new on this machine. A bank marked login_needed needs a person to run `coinpay finances statements login <bank>`. Tax notices, letters and transcripts (California FTB, IRS) are in tax_documents_list; tax data stays on CoinPay surfaces and is never sent elsewhere.',
+          'CoinPay finances. finance_due_soon answers "what is due" across every account; finance_recurring lists subscriptions and bills; finance_summary is the balance sheet. Statement PDFs come from the banks themselves (SimpleFIN has none): statements_coverage shows what is missing, statements_fetch downloads what is new on this machine. A bank marked login_needed needs a person to run `coinpay finances statements login <bank>`. Tax notices, letters and transcripts (California FTB, IRS) are in tax_documents_list; tax data stays on CoinPay surfaces and is never sent elsewhere.',
       });
     case 'notifications/initialized':
     case 'notifications/cancelled':
@@ -159,7 +241,9 @@ export async function handleMessage(message, ctx) {
     case 'ping':
       return reply({});
     case 'tools/list':
-      return reply({ tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+      // Claude Code's client (revision 2026-07-28) rejects a whole list that
+      // lacks these three cache fields, showing "tools fetch failed".
+      return reply({ tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })), resultType: 'complete', ttlMs: 0, cacheScope: 'private' });
     case 'tools/call': {
       const tool = TOOLS.find((t) => t.name === params.name);
       if (!tool) return fail(-32602, `Unknown tool: ${params.name}`);

package/src/x402.js

@@ -2,7 +2,7 @@
  * x402 Payment Protocol Support
  * 
  * CoinPayPortal as the first multi-chain, multi-asset x402 facilitator.
- * Supports native crypto (BTC, ETH, SOL, POL), USDC stablecoins,
+ * Supports native crypto (BTC, ETH, SOL, POL, XNO), USDC stablecoins,
  * Lightning (BOLT12), and Stripe fiat — all via HTTP 402.
  *
  * Note: Bitcoin Cash is intentionally not listed. The x402 settle path has no
@@ -92,6 +92,18 @@ export const PAYMENT_METHODS = {
     label: 'USDC on Base',
   },
 
+  // ── Nano ───────────────────────────────────────────────────────
+  // Opt-in: only advertised when `payTo` names a Nano address (`payTo.nano`
+  // or a `nano_` string) and an XNO amount can be quoted (`rates.XNO`, or a
+  // raw `amount`). The payer sends a block; the proof carries its `blockHash`.
+  xno: {
+    network: 'nano',
+    asset: 'XNO',
+    scheme: 'exact',
+    decimals: 30,
+    label: 'Nano (XNO)',
+  },
+
   // ── Lightning ──────────────────────────────────────────────────
   lightning: {
     network: 'lightning',
@@ -175,6 +187,14 @@ export function convertUsdToAssetAmount(amountUsd, methodKey, rates = {}) {
   if (!rate) throw new Error(`No exchange rate for ${method.asset}`);
 
   const assetAmount = amountUsd / rate;
+
+  if (method.network === 'nano') {
+    // 30 decimals is past float64's exact range, and String() of a number that
+    // large is exponent notation ("1e+27"), which no verifier parses. Quote to
+    // the nearest 10^-9 XNO and scale the rest in BigInt.
+    return (BigInt(Math.round(assetAmount * 1e9)) * 10n ** 21n).toString();
+  }
+
   const smallest = Math.round(assetAmount * Math.pow(10, method.decimals));
   return String(smallest);
 }
@@ -288,6 +308,8 @@ export function buildPaymentRequired(options) {
       addr = payTo;
     }
     if (!addr) continue; // skip methods where merchant has no address
+    // A single non-Nano address must not be advertised as a Nano payee.
+    if (method.network === 'nano' && !/^(nano|xrb)_/.test(addr)) continue;
 
     // Convert USD to asset amount
     let assetAmount;
@@ -329,6 +351,7 @@ function _networkToMethodKey(network) {
     polygon: 'pol',
     solana: 'sol',
     bitcoin: 'btc',
+    nano: 'xno',
     lightning: 'lightning',
     stripe: 'stripe',
   };