@profullstack/coinpay 0.24.1 → 0.26.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.26.0] - 2026-10-28
+
+### Added
+- Declared recurring costs: bills no bank or card feed shows (servers paid by PayPal, crypto or an
+  unlinked card). `coinpay finances costs import <file|url> [--source opendevice] [--header "K: V"]`
+  takes an OpenDevice inventory (converted server-side with `@profullstack/fleet`) or `toCoinPayCosts`
+  rows and replaces that source's set; `coinpay finances costs list [--json]`, `costs clear --source s --yes`.
+  SDK `listDeclaredCosts(client, { source })`, `importDeclaredCosts(client, body, { source })`; MCP
+  `finance_declared_costs`, `finance_import_costs`.
+- `coinpay finances recurring` (and `--json`) now includes declared costs: each charge has `origin`
+  `observed`, `declared` (not in any feed) or `matched` (seen in the feed and declared: payee, amount
+  within 10% and interval agree; counted once, as observed, with the declaration in `declared`).
+  `monthlyTotal` includes declared costs; `monthlyDeclared` is that part.
+
+## [0.25.0] - 2026-10-21
+
+### Added
+- `createCheckoutSession({ amount, customerEmail, accountId, property, metadata, successUrl, cancelUrl, expiresInMinutes, allowedMethods })`
+  and `getCheckoutSession(id)`: one hosted checkout URL where the buyer picks any coin the business can
+  receive, or PayPal. Webhooks for the resulting payment carry `checkout_session_id`, `customer_email`,
+  `account_id`, `property` and `metadata`.
+- `createPayment({ customerEmail, accountId, property })`, stored in the payment's metadata.
+
 ## [0.23.0] - 2026-10-21
 
 ### Added

package/bin/coinpay.js

@@ -270,7 +270,7 @@ 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']);
+const REPEATABLE_FLAGS = new Set(['item', 'header']);
 
 function parseArgs(args) {
   const result = { command: null, subcommand: null, args: [], flags: {} };
@@ -712,7 +712,8 @@ ${colors.cyan}Commands:${colors.reset}
                             --with-documents: a ZIP with the period's tax documents, up to 8 MiB)
     pnl                   Profit and loss, personal and business as separate files
                             (--scope personal|business, --months 3 (default: last 3
-                            complete months) or --from/--to, --name "Holder", --format pdf|html|csv|json)
+                            complete months) or --from/--to, --name "Holder", --format pdf|html|csv|json,
+                            --newest-first puts the latest month first)
     payloads [list|download <id>]  Raw provider responses, exactly as received
     reports send <id>     Email a report (--to a@x,b@y, --format pdf,csv, --message, --no-attach)
     books send            Email the CPA pack (--to, --period, --scope, --format,
@@ -721,6 +722,10 @@ ${colors.cyan}Commands:${colors.reset}
     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
+                            (origin: observed, declared, or matched = both, counted once)
+    costs [list|import|clear]  Declared recurring costs no feed shows (servers paid by PayPal/crypto):
+                            import <file|url> takes an OpenDevice inventory or @profullstack/fleet
+                            toCoinPayCosts rows (--source opendevice, --header "K: V" for a URL)
     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: spend vs target, top cuts, due soon, position (--hour 7 --to …, --target 100)
 
@@ -4999,10 +5004,10 @@ function printPosition(position, fmt, { heading = false, detail = false } = {})
       { title: 'Amount', align: 'right', render: (c) => money(c.amount, cur) },
       { title: 'Every', align: 'left', render: (c) => c.cadence },
       { title: 'Seen', align: 'right', render: (c) => String(c.occurrences) },
-      { title: 'Last', align: 'left', render: (c) => c.lastSeen.slice(0, 10) },
-      { title: 'Next', align: 'left', render: (c) => c.nextExpected.slice(0, 10) },
+      { title: 'Last', align: 'left', render: (c) => (c.origin === 'declared' ? '-' : c.lastSeen.slice(0, 10)) },
+      { title: 'Next', align: 'left', render: (c) => (c.nextExpected || '-').slice(0, 10) },
       { title: 'Per month', align: 'right', render: (c) => money(c.monthlyEquivalent, cur) },
-      { title: 'Kind', align: 'left', render: (c) => (c.isDebtService ? 'debt' : 'bill') },
+      { title: 'Kind', align: 'left', render: (c) => (c.isDebtService ? 'debt' : c.origin === 'declared' ? 'declared' : c.origin === 'matched' ? 'bill (declared)' : 'bill') },
     ]);
   }
   console.log('');
@@ -5252,7 +5257,8 @@ async function handleFinances(subcommand, args, flags) {
     case 'due-soon':
     case 'recurring':
     case 'due-day':
-    case 'daily': {
+    case 'daily':
+    case 'costs': {
       const { client } = financesClient();
       const { runFinancesCommand } = await import('../src/finances-commands.js');
       const code = await runFinancesCommand(subcommand, args, flags, {
@@ -5266,7 +5272,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|pnl|payloads|digest|due|recurring|due-day|daily]');
+      console.log('Usage: coinpay finances [tui|summary|accounts|ledger|connections|sync|connect|disconnect|backfill|jobs|coverage|report|reports|statements|books|pnl|payloads|digest|due|recurring|due-day|daily|costs]');
       process.exit(1);
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.24.1",
-  "description": "CoinPay SDK & CLI \u2014 Accept cryptocurrency and card payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet, swap and a live finances dashboard",
+  "version": "0.26.0",
+  "description": "CoinPay SDK & CLI — 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",
   "types": "./src/index.d.ts",
@@ -135,16 +135,16 @@
     "node": ">=20.0.0"
   },
   "devDependencies": {
-    "eslint": "^8.57.0",
-    "prettier": "^3.4.1",
-    "vitest": "^4.1.11"
+    "eslint": "^8.57.1",
+    "prettier": "^3.9.10",
+    "vitest": "^4.1.12"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.3.0",
-    "@noble/curves": "^1.6.0",
-    "@noble/hashes": "^1.5.0",
-    "@profullstack/hqtui": "^0.6.3",
-    "@scure/bip32": "^1.5.0",
-    "@scure/bip39": "^1.4.0"
+    "@inquirer/prompts": "^8.7.4",
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.8.0",
+    "@profullstack/hqtui": "^0.11.1",
+    "@scure/bip32": "^1.7.0",
+    "@scure/bip39": "^1.6.0"
   }
 }

package/src/client.d.ts

@@ -31,6 +31,57 @@ export interface PaymentParams {
   successUrl?: string;
   /** Where "Back to merchant" goes from an expired or abandoned checkout */
   cancelUrl?: string;
+  /** Email of the person paying; stored in metadata and sent on webhooks */
+  customerEmail?: string;
+  /** Your site's user id or handle for the payer */
+  accountId?: string;
+  /** Your site hostname */
+  property?: string;
+}
+
+/** Parameters for creating a hosted checkout session */
+export interface CheckoutSessionParams {
+  /** Amount in USD */
+  amount: number;
+  /** Only `'USD'` */
+  currency?: 'USD';
+  description?: string;
+  /** Email of the person paying (required) */
+  customerEmail: string;
+  /** Your site's user id or handle for the payer (required) */
+  accountId: string;
+  /** Your site hostname (defaults to the business name) */
+  property?: string;
+  metadata?: Record<string, unknown>;
+  /** `{CHECKOUT_SESSION_ID}` and `{PAYMENT_ID}` are filled in */
+  successUrl?: string;
+  cancelUrl?: string;
+  /** 15 to 120, default 60 */
+  expiresInMinutes?: number;
+  /** Coin codes (e.g. `'USDC_POL'`), `'CRYPTO'` or `'PAYPAL'`; default all */
+  allowedMethods?: string[];
+  /** Only with a merchant session token; a business API key implies it */
+  businessId?: string;
+}
+
+/** Response from `createCheckoutSession` */
+export interface CheckoutSessionResponse {
+  success: boolean;
+  id: string;
+  url: string;
+  status: 'open' | 'paid' | 'expired';
+  amount: number;
+  currency: 'USD';
+  description: string | null;
+  customer_email: string;
+  account_id: string;
+  property: string;
+  metadata: Record<string, unknown>;
+  success_url: string | null;
+  cancel_url: string | null;
+  expires_at: string;
+  methods: string[];
+  [key: string]: unknown;
 }
 
 /** Parameters for listing payments */
@@ -200,6 +251,15 @@ export class CoinPayClient {
    */
   createPayment(params: PaymentParams): Promise<CreatePaymentResponse>;
 
+  /**
+   * Create a hosted checkout session; redirect the buyer to `url`. The buyer
+   * picks any coin the business can receive, or PayPal.
+   */
+  createCheckoutSession(params: CheckoutSessionParams): Promise<CheckoutSessionResponse>;
+
+  /** Get a checkout session (`cs_...`). */
+  getCheckoutSession(sessionId: string): Promise<Record<string, unknown>>;
+
   /**
    * Get payment details by ID.
    *

package/src/client.js

@@ -255,6 +255,9 @@ export class CoinPayClient {
     metadata,
     successUrl,
     cancelUrl,
+    customerEmail,
+    accountId,
+    property,
   }) {
     // Map to API field names (snake_case)
     return this.request('/payments/create', {
@@ -268,10 +271,90 @@ export class CoinPayClient {
         metadata,
         success_url: successUrl,
         cancel_url: cancelUrl,
+        customer_email: customerEmail,
+        account_id: accountId,
+        property,
       }),
     });
   }
 
+  /**
+   * Create a hosted checkout session.
+   *
+   * Redirect the buyer to the returned `url`. There they choose any coin your
+   * business has a wallet for (stablecoins first) or PayPal when connected.
+   * The payment and every webhook for it carry `checkout_session_id`,
+   * `customer_email`, `account_id`, `property` and your `metadata`.
+   *
+   * @param {Object} params
+   * @param {number} params.amount - Amount in USD
+   * @param {string} params.customerEmail - Email of the person paying (required)
+   * @param {string} params.accountId - Your site's user id or handle for the payer (required)
+   * @param {string} [params.property] - Your site hostname (defaults to the business name)
+   * @param {string} [params.description]
+   * @param {Object} [params.metadata]
+   * @param {string} [params.successUrl] - `{CHECKOUT_SESSION_ID}` and `{PAYMENT_ID}` are filled in
+   * @param {string} [params.cancelUrl]
+   * @param {number} [params.expiresInMinutes=60] - 15 to 120
+   * @param {string[]} [params.allowedMethods] - coin codes, 'CRYPTO' or 'PAYPAL' (default: all)
+   * @returns {Promise<{success: boolean, id: string, url: string, status: string, expires_at: string, methods: string[]}>}
+   *
+   * @example
+   * const { id, url } = await client.createCheckoutSession({
+   *   amount: 9.99,
+   *   description: 'Pro plan',
+   *   customerEmail: 'buyer@example.com',
+   *   accountId: 'user_123',
+   *   property: 'example.com',
+   *   successUrl: 'https://example.com/thanks?session={CHECKOUT_SESSION_ID}',
+   *   cancelUrl: 'https://example.com/pricing',
+   * });
+   * // res.redirect(url)
+   */
+  async createCheckoutSession({
+    amount,
+    currency = 'USD',
+    description,
+    customerEmail,
+    accountId,
+    property,
+    metadata,
+    successUrl,
+    cancelUrl,
+    expiresInMinutes,
+    allowedMethods,
+    businessId,
+  }) {
+    return this.request('/checkout/sessions', {
+      method: 'POST',
+      body: JSON.stringify({
+        amount,
+        currency,
+        description,
+        customer_email: customerEmail,
+        account_id: accountId,
+        property,
+        metadata,
+        success_url: successUrl,
+        cancel_url: cancelUrl,
+        expires_in_minutes: expiresInMinutes,
+        allowed_methods: allowedMethods,
+        business_id: businessId,
+      }),
+    });
+  }
+
+  /**
+   * Get a checkout session. With your business API key the response includes
+   * the customer fields, metadata and the underlying payment ids.
+   *
+   * @param {string} sessionId - `cs_...`
+   * @returns {Promise<Object>} `{ success, session }`
+   */
+  async getCheckoutSession(sessionId) {
+    return this.request(`/checkout/sessions/${encodeURIComponent(sessionId)}`);
+  }
+
   /**
    * Get payment by ID
    *

package/src/finances-commands.js

@@ -386,6 +386,37 @@ async function runStatementFetchAction(action, rest, flags, { client, out, emit,
  * Run one subcommand. `ctx` supplies the client and the output channels.
  * @returns {Promise<number>} an exit code
  */
+/**
+ * Read a declared-costs body: a local JSON file or an http(s) URL (an
+ * OpenDevice inventory, or toCoinPayCosts rows). `--header "K: V"` is sent
+ * with a URL, e.g. for a private raw file; it may be repeated.
+ */
+export async function readCostsInput(where, header, { fetchImpl = globalThis.fetch } = {}) {
+  let raw;
+  if (/^https?:\/\//i.test(where)) {
+    const headers = {};
+    for (const h of [].concat(header ?? []).filter((v) => typeof v === 'string')) {
+      const i = h.indexOf(':');
+      if (i <= 0) throw new CliExit(EXIT.INVALID, `--header must look like "Name: value", got ${h.slice(0, 40)}`);
+      headers[h.slice(0, i).trim()] = h.slice(i + 1).trim();
+    }
+    const res = await fetchImpl(where, { headers });
+    if (!res.ok) throw new CliExit(EXIT.FAILURE, `${where}: HTTP ${res.status}`);
+    raw = await res.text();
+  } else {
+    try {
+      raw = readFileSync(resolvePath(where), 'utf8');
+    } catch (e) {
+      throw new CliExit(EXIT.INVALID, `Cannot read ${where}: ${e.message}`);
+    }
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new CliExit(EXIT.INVALID, `${where} is not JSON`);
+  }
+}
+
 export async function runFinancesCommand(subcommand, args, flags, ctx) {
   const { client, out, err: errOut } = ctx;
   const json = flags.json === true;
@@ -816,9 +847,10 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
         const to = typeof flags.to === 'string' ? flags.to : undefined;
         const timezone = typeof flags.timezone === 'string' ? flags.timezone : undefined;
         const name = typeof flags.name === 'string' ? flags.name : undefined;
+        const order = flags['newest-first'] === true ? 'newest' : typeof flags.order === 'string' ? flags.order : undefined;
         const written = [];
         for (const scope of wanted) {
-          const file = await api.exportPnl(client, { scope, months, period, from, to, timezone, name, format });
+          const file = await api.exportPnl(client, { scope, months, period, from, to, timezone, name, format, order });
           const output = typeof flags.output === 'string' && wanted.length === 1 ? flags.output : file.filename || `pnl-${scope}.${format}`;
           written.push({ scope, output: writeDownload(output, Buffer.from(file.bytes), { overwrite: flags.overwrite === true }), bytes: file.bytes.length });
         }
@@ -880,10 +912,12 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
         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));
+          const rows = [...d.recurring.charges].sort((a, b) => (a.nextExpected || '9999').localeCompare(b.nextExpected || '9999'));
           out(`${rows.length} recurring charges · ${money(d.recurring.monthlyTotal)}/mo${d.recurring.monthlyDebtService ? ` (${money(d.recurring.monthlyDebtService)} debt service)` : ''}`);
+          if (d.recurring.monthlyDeclared) out(`  of which ${money(d.recurring.monthlyDeclared)}/mo is declared (not in any feed)`);
           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' : ''}`);
+            const origin = c.origin === 'declared' ? ' · declared' : c.origin === 'matched' ? ' · matched' : '';
+            out(`  next ${(c.nextExpected || '?').slice(0, 10).padEnd(10)}  ${c.cadence.padEnd(9)} ${money(c.amount).padStart(11)}  ${c.payee}  · ${c.accountName}${c.isDebtService ? ' · debt' : ''}${origin}`);
           }
           return EXIT.OK;
         }
@@ -899,6 +933,38 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
         return EXIT.OK;
       }
 
+      case 'costs': {
+        const action = args[0] || 'list';
+        const source = typeof flags.source === 'string' ? flags.source : undefined;
+        const fmt = (cur, n) => new Intl.NumberFormat('en-US', { style: 'currency', currency: cur }).format(n);
+        const describe = (data) => {
+          const lines = data.costs.map((c) => `  ${c.source.padEnd(11)} ${c.key.padEnd(22)} ${fmt(c.currency, c.amount).padStart(11)} ${c.cadence.padEnd(8)} ${c.payee}${c.paidWith ? ` · ${c.paidWith}` : ''}${c.nextExpected ? ` · next ${c.nextExpected.slice(0, 10)}` : ''}`);
+          const totals = Object.entries(data.monthly || {}).map(([cur, n]) => `${fmt(cur, n)}/mo`).join(' + ') || 'nothing';
+          return [`${data.costs.length} declared cost(s) · ${totals}`, ...lines].join('\n');
+        };
+        if (action === 'list') {
+          const data = await api.listDeclaredCosts(client, { source });
+          emit(data, describe(data));
+          return EXIT.OK;
+        }
+        if (action === 'import') {
+          const where = args[1];
+          if (!where) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances costs import <file|url> [--source opendevice] [--header "Authorization: token …"]');
+          const body = await readCostsInput(where, flags.header);
+          const data = await api.importDeclaredCosts(client, body, { source: source || 'opendevice' });
+          emit(data, `Imported ${data.upserted} into ${data.source}${data.removed ? `, removed ${data.removed}` : ''}.\n${describe(data)}\nSee it in: coinpay finances recurring`);
+          return EXIT.OK;
+        }
+        if (action === 'clear') {
+          if (!source) throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances costs clear --source <name> --yes');
+          if (!flags.yes) throw new CliExit(EXIT.INVALID, `This removes every declared cost from ${source}. Re-run with --yes to confirm.`);
+          const data = await api.importDeclaredCosts(client, [], { source });
+          emit(data, `Removed ${data.removed} declared cost(s) from ${source}.`);
+          return EXIT.OK;
+        }
+        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances costs [list [--source s]|import <file|url> [--source opendevice] [--header "K: V"]|clear --source s --yes]');
+      }
+
       case 'due-day': {
         const id = args[0];
         const value = args[1];
@@ -990,4 +1056,4 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
   }
 }
 
-export const EXTENDED_SUBCOMMANDS = ['connect', 'disconnect', 'consent', 'backfill', 'jobs', 'coverage', 'report', 'reports', 'statements', 'books', 'pnl', 'profit-loss', 'payloads', 'digest', 'due', 'due-soon', 'recurring', 'due-day', 'daily'];
+export const EXTENDED_SUBCOMMANDS = ['connect', 'disconnect', 'consent', 'backfill', 'jobs', 'coverage', 'report', 'reports', 'statements', 'books', 'pnl', 'profit-loss', 'payloads', 'digest', 'due', 'due-soon', 'recurring', 'due-day', 'daily', 'costs'];

package/src/finances-reports.d.ts

@@ -420,14 +420,43 @@ export interface DueSoon {
   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 }>;
+    charges: Array<{ key: string; payee: string; amount: number; cadence: string; occurrences: number; lastSeen: string; nextExpected: string; monthlyEquivalent: number; scope: 'business' | 'personal'; isDebtService: boolean; accountId: string; accountName: string; origin?: 'observed' | 'matched' | 'declared'; declared?: DeclaredCostRef }>;
     monthlyTotal: number;
     monthlyDebtService: number;
+    /** The declared part of monthlyTotal that no feed shows. */
+    monthlyDeclared?: number;
+    declaredSkipped?: number;
   };
   currency: string | null;
 }
 
 export function getDueSoon(client: CoinPayClient, opts?: { days?: number; timezone?: string }): Promise<DueSoon>;
+
+export interface DeclaredCostRef {
+  source: string;
+  key: string;
+  payee: string;
+  amount: number;
+  cadence: 'monthly' | 'yearly';
+  monthlyEquivalent: number;
+  category: string | null;
+  paidWith: string | null;
+  meta: Record<string, unknown>;
+}
+
+export interface DeclaredCost extends DeclaredCostRef {
+  currency: string;
+  scope: 'business' | 'personal';
+  nextExpected: string | null;
+  updatedAt?: string | null;
+}
+
+export function listDeclaredCosts(client: CoinPayClient, opts?: { source?: string }): Promise<{ costs: DeclaredCost[]; monthly: Record<string, number> }>;
+export function importDeclaredCosts(
+  client: CoinPayClient,
+  body: unknown,
+  opts?: { source?: string },
+): Promise<{ source: string; removed: number; upserted: number; costs: DeclaredCost[]; monthly: Record<string, number> }>;
 export function getDailySummary(client: CoinPayClient): Promise<WeeklyDigest | null>;
 export function setDailySummary(
   client: CoinPayClient,

package/src/finances-reports.js

@@ -403,8 +403,8 @@ export async function exportBooks(client, { period, from, to, timezone, scope, f
  * Profit and loss statement for one scope. With no period it covers the
  * last `months` complete calendar months (server default 3).
  */
-export async function exportPnl(client, { scope, months, period, from, to, timezone, name, format = 'pdf' } = {}) {
-  return client.requestBinary(`/finances/pnl${query({ scope, months, period, from, to, timezone, name, format })}`);
+export async function exportPnl(client, { scope, months, period, from, to, timezone, name, format = 'pdf', order } = {}) {
+  return client.requestBinary(`/finances/pnl${query({ scope, months, period, from, to, timezone, name, format, order })}`);
 }
 
 // ── Raw provider payloads ──
@@ -466,6 +466,27 @@ export async function getDueSoon(client, { days, timezone } = {}) {
   return data.dueSoon;
 }
 
+/**
+ * Declared recurring costs (servers paid by PayPal or crypto, which no bank
+ * feed shows). `source` defaults to every source.
+ */
+export async function listDeclaredCosts(client, { source } = {}) {
+  const qs = source ? `?source=${encodeURIComponent(source)}` : '';
+  return call(client, `/finances/declared-costs${qs}`);
+}
+
+/**
+ * Replace one source's declared costs. `body` is an OpenDevice inventory (an
+ * object with `devices`), an array of `toCoinPayCosts` rows from
+ * @profullstack/fleet, or `{ costs: [...] }`. An empty array clears it.
+ */
+export async function importDeclaredCosts(client, body, { source = 'opendevice' } = {}) {
+  return call(client, `/finances/declared-costs?source=${encodeURIComponent(source)}`, {
+    method: 'PUT',
+    body: JSON.stringify(body),
+  });
+}
+
 export async function getDailySummary(client) {
   const data = await call(client, '/finances/email-schedules?kind=daily_summary');
   return data.schedule;

package/src/mcp.js

@@ -55,6 +55,30 @@ export const TOOLS = [
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     handler: async (_args, { client }) => text((await reports.getDueSoon(client, { days: 0 })).recurring),
   },
+  {
+    name: 'finance_declared_costs',
+    description: 'Declared recurring costs: bills no bank feed shows (servers paid by PayPal or crypto), stated by the owner, e.g. from an OpenDevice inventory. They are merged into finance_recurring (origin "declared", or "matched" when a feed charge is the same bill).',
+    inputSchema: { type: 'object', properties: { source: { type: 'string', description: 'Only this source, e.g. opendevice' } }, additionalProperties: false },
+    handler: async (args, { client }) => text(await reports.listDeclaredCosts(client, { source: args.source })),
+  },
+  {
+    name: 'finance_import_costs',
+    description: 'Replace one source\'s declared recurring costs. Pass an OpenDevice inventory (an object with "devices"; the server converts it) or an array of @profullstack/fleet toCoinPayCosts rows. An empty array clears the source.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source: { type: 'string', description: 'Source name (default opendevice)' },
+        inventory: { type: 'object', description: 'An OpenDevice inventory' },
+        costs: { type: 'array', items: { type: 'object' }, description: 'toCoinPayCosts rows' },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => {
+      const body = args.inventory ?? args.costs;
+      if (body === undefined) throw new Error('Pass inventory or costs');
+      return text(await reports.importDeclaredCosts(client, body, { source: args.source || 'opendevice' }));
+    },
+  },
   {
     name: 'finance_summary',
     description: 'Balance sheet (assets, debt, net by currency), cashflow for the window, top spending categories, and the debt-and-income position.',
@@ -427,7 +451,7 @@ export async function handleMessage(message, ctx) {
         capabilities: { tools: {} },
         serverInfo: { name: 'coinpay', version: ctx.version || '0.0.0' },
         instructions:
-          '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.',
+          'CoinPay finances. finance_due_soon answers "what is due" across every account; finance_recurring lists subscriptions and bills (declared costs such as servers paid by PayPal included, see finance_declared_costs); 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':