@profullstack/coinpay 0.15.0 → 0.16.0

package/CHANGELOG.md

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

@@ -529,6 +529,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
@@ -4355,7 +4359,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 +4378,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);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.15.0",
+  "version": "0.16.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/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}`);