@profullstack/coinpay 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to `@profullstack/coinpay` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.18.0] - 2026-10-17
+
+### Added
+- Projects and time tracking: `coinpay project list|create|get|invoice`,
+  `coinpay time log|start|stop|list`. `project invoice` bills unbilled
+  billable time as a draft itemised invoice; billed time is locked.
+- `coinpay invoice aging`: unpaid sent invoices by days past due, per
+  currency and per client.
+- `coinpay invoice settings`: reminder schedule (`--reminders "-3,0,7"`),
+  late fee (`--late-fee 1.5%` or `25`, `--late-fee-after 3`) and branding
+  (`--brand-color`, `--logo-url`, `--footer`).
+- `coinpay client portal-link <id>`: one link where a client sees and pays
+  all their invoices; `--revoke` turns it off.
+- MCP: `invoice_list`, `invoice_get`, `invoice_create_draft`,
+  `invoice_ar_aging`, `project_list`, `project_get`, `time_log`,
+  `project_invoice_time`.
+- SDK: `getArAging`, `getInvoiceSettings`, `updateInvoiceSettings`,
+  `createClientPortalLink`, `revokeClientPortalLink`, `listProjects`,
+  `getProject`, `createProject`, `logTime`, `startTimer`, `stopTimer`,
+  `listTimeEntries`, `invoiceProjectTime`.
+
+### Fixed
+- A flag value that starts with a minus and a digit (`--reminders -3,0,7`)
+  is read as the value instead of as another flag.
+
+## [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

package/bin/coinpay.js

@@ -24,7 +24,28 @@ import {
   sendInvoice,
   updateInvoice,
   InvoiceStatus,
+  listTaxRates,
+  createTaxRate,
+  deleteTaxRate,
+  listInvoiceItems,
+  createInvoiceItem,
+  deleteInvoiceItem,
 } from '../src/invoices.js';
+import {
+  getArAging,
+  getInvoiceSettings,
+  updateInvoiceSettings,
+  createClientPortalLink,
+  revokeClientPortalLink,
+  listProjects,
+  getProject,
+  createProject,
+  logTime,
+  startTimer,
+  stopTimer,
+  listTimeEntries,
+  invoiceProjectTime,
+} from '../src/projects.js';
 import { readFileSync, writeFileSync, existsSync, unlinkSync, chmodSync } from 'fs';
 import { execSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
@@ -167,6 +188,11 @@ function createUnauthenticatedClient() {
 }
 
 const BOOLEAN_FLAGS = new Set([
+  // projects, time, client portal
+  'non-billable',
+  'unbilled',
+  'archived',
+  'revoke',
   'active',
   // finances reports / statements
   'wait',
@@ -206,8 +232,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 +251,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;
+        } else if (next && (!next.startsWith('-') || /^-\d/.test(next))) {
+          setFlag(name, next);
           i++;
         } else {
           result.flags[name] = true;
@@ -289,6 +325,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 +395,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 +477,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 +491,38 @@ ${colors.cyan}Commands:${colors.reset}
     delete <id>           Permanently delete a draft invoice
       --yes               Skip confirmation for publish/send/delete
 
+  ${colors.bright}invoice aging${colors.reset}     Unpaid invoices by days past due (--business-id)
+  ${colors.bright}invoice settings${colors.reset}  Show reminders, late fee, branding; change with
+                    --reminders "-3,0,7" | off, --late-fee 1.5% | 25 | none,
+                    --late-fee-after 3, --brand-color "#7c3aed", --logo-url, --footer
+
+  ${colors.bright}client${colors.reset}
+    portal-link <client-id>   Create a portal link listing all their invoices
+                              (replaces the old link; --revoke to turn it off)
+
+  ${colors.bright}project${colors.reset}
+    list                  Projects (--business-id, --archived)
+    create                --name, [--client-id] [--rate 120] [--budget 40]
+    get <id>              Hours, unbilled, billed and paid
+    invoice <id>          Bill unbilled time as a draft invoice
+
+  ${colors.bright}time${colors.reset}
+    log                   --project <id> --minutes 90 | --hours 1.5 [--description] [--non-billable]
+    start                 --project <id> [--description]   start a timer
+    stop                  stop your running timer
+    list                  --project <id> [--unbilled]
+
+  ${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)
 
@@ -1068,6 +1176,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);
@@ -1088,6 +1205,227 @@ function printInvoiceDetails(invoice, { shareUrl } = {}) {
 /**
  * Invoice commands
  */
+async function handleClientCommand(subcommand, args, flags) {
+  const client = createClient();
+  if (subcommand !== 'portal-link' || args.length !== 1) {
+    print.error('Usage: coinpay client portal-link <client-id> [--revoke]');
+    process.exit(1);
+  }
+  if (flags.revoke) {
+    await revokeClientPortalLink(client, args[0]);
+    print.success('Portal link revoked');
+    return;
+  }
+  const url = await createClientPortalLink(client, args[0]);
+  if (flags.json) print.json({ url });
+  else {
+    print.success('Portal link (any earlier link no longer works):');
+    console.log(url);
+  }
+}
+
+function hoursOf(minutes) {
+  return minutes == null ? 'running' : Math.floor(minutes / 60) + 'h' + String(minutes % 60).padStart(2, '0') + 'm';
+}
+
+async function handleProject(subcommand, args, flags) {
+  const client = createClient();
+  requireFlagValues(flags, ['business-id', 'name', 'client-id', 'rate', 'budget', 'currency']);
+  switch (subcommand) {
+    case 'list': {
+      const rows = await listProjects(client, { businessId: flags['business-id'], includeArchived: !!flags.archived });
+      if (flags.json) return print.json(rows);
+      if (!rows.length) return print.info('No projects');
+      for (const p of rows) {
+        print.info(p.id + '  ' + p.name + (p.hourly_rate != null ? '  ' + p.hourly_rate + '/hr' : '') + (p.status === 'archived' ? '  (archived)' : ''));
+      }
+      return;
+    }
+    case 'create': {
+      if (!flags.name) {
+        print.error('--name is required');
+        process.exit(1);
+      }
+      const rate = flags.rate === undefined ? undefined : parseNonNegativeAmount(String(flags.rate));
+      if (rate === null) {
+        print.error('--rate must be an amount with at most two decimals');
+        process.exit(1);
+      }
+      const project = await createProject(client, {
+        businessId: flags['business-id'],
+        name: flags.name,
+        clientId: flags['client-id'],
+        hourlyRate: rate,
+        currency: flags.currency?.toUpperCase(),
+        budgetHours: flags.budget === undefined ? undefined : Number(flags.budget),
+      });
+      if (flags.json) return print.json(project);
+      return print.success('Project created: ' + project.id);
+    }
+    case 'get': {
+      if (args.length !== 1) {
+        print.error('Usage: coinpay project get <id>');
+        process.exit(1);
+      }
+      const { project, stats } = await getProject(client, args[0]);
+      if (flags.json) return print.json({ project, stats });
+      print.info(project.name + (project.hourly_rate != null ? '  ' + project.hourly_rate + '/hr' : ''));
+      print.info('Hours: ' + stats.hours + (project.budget_hours ? ' of ' + project.budget_hours : '') + ' (' + stats.billable_hours + ' billable)');
+      print.info('Unbilled: ' + stats.unbilled_amount + '   Billed: ' + stats.billed_amount + '   Paid: ' + stats.paid_amount);
+      return;
+    }
+    case 'invoice': {
+      if (args.length !== 1) {
+        print.error('Usage: coinpay project invoice <id>');
+        process.exit(1);
+      }
+      const result = await invoiceProjectTime(client, args[0]);
+      if (flags.json) return print.json(result);
+      print.success('Draft ' + result.invoice.invoice_number + ' for ' + result.invoice.amount + ' from ' + result.entries_billed + ' entries');
+      return print.info('Review and send: coinpay invoice send ' + result.invoice.id);
+    }
+    default:
+      print.error('Usage: coinpay project <list|create|get|invoice>');
+      process.exit(1);
+  }
+}
+
+async function handleTime(subcommand, args, flags) {
+  const client = createClient();
+  requireFlagValues(flags, ['project', 'minutes', 'hours', 'description', 'business-id']);
+  switch (subcommand) {
+    case 'log': {
+      const minutes = flags.minutes !== undefined ? Number(flags.minutes) : Math.round(Number(flags.hours) * 60);
+      if (!flags.project || !Number.isInteger(minutes) || minutes < 1) {
+        print.error('Usage: coinpay time log --project <id> --minutes 90 (or --hours 1.5) [--description "..."]');
+        process.exit(1);
+      }
+      const entry = await logTime(client, {
+        projectId: flags.project,
+        minutes,
+        description: flags.description,
+        billable: flags['non-billable'] ? false : undefined,
+      });
+      if (flags.json) return print.json(entry);
+      return print.success('Logged ' + hoursOf(entry.minutes));
+    }
+    case 'start': {
+      if (!flags.project) {
+        print.error('Usage: coinpay time start --project <id> [--description "..."]');
+        process.exit(1);
+      }
+      const entry = await startTimer(client, { projectId: flags.project, description: flags.description });
+      if (flags.json) return print.json(entry);
+      return print.success('Timer started (' + entry.id + ')');
+    }
+    case 'stop': {
+      const entry = await stopTimer(client, { entryId: args[0], businessId: flags['business-id'] });
+      if (flags.json) return print.json(entry);
+      return print.success('Timer stopped: ' + hoursOf(entry.minutes));
+    }
+    case 'list': {
+      const rows = await listTimeEntries(client, { projectId: flags.project, businessId: flags['business-id'], unbilled: !!flags.unbilled });
+      if (flags.json) return print.json(rows);
+      if (!rows.length) return print.info('No time logged');
+      for (const e of rows) {
+        print.info(
+          e.started_at.slice(0, 10) + '  ' + hoursOf(e.minutes).padStart(8) + '  ' + (e.invoice_id ? 'billed  ' : e.billable ? 'unbilled' : 'internal') + '  ' + (e.description || '')
+        );
+      }
+      return;
+    }
+    default:
+      print.error('Usage: coinpay time <log|start|stop|list>');
+      process.exit(1);
+  }
+}
+
+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();
 
@@ -1103,12 +1441,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);
       }
 
@@ -1130,6 +1479,8 @@ async function handleInvoice(subcommand, args, flags) {
         clientId: flags['client-id'],
         currency: currency.toUpperCase(),
         amount,
+        lineItems,
+        discount,
         cryptoCurrency: cryptoCurrency?.toUpperCase(),
         dueDate,
         notes: flags.notes,
@@ -1511,9 +1862,82 @@ async function handleInvoice(subcommand, args, flags) {
       break;
     }
 
+    case 'aging': {
+      requireFlagValues(flags, ['business-id']);
+      const report = await getArAging(client, { businessId: flags['business-id'] });
+      if (flags.json) {
+        print.json(report);
+        break;
+      }
+      if (!report.totals?.length) {
+        print.info('Nothing outstanding');
+        break;
+      }
+      const cols = ['current', '1_30', '31_60', '61_90', '90_plus', 'total'];
+      print.info('                          current     1-30    31-60    61-90      90+    total');
+      for (const row of [...report.totals.map((t) => ({ ...t, name: 'TOTAL ' + t.currency })), ...report.clients]) {
+        print.info(
+          String(row.name).slice(0, 24).padEnd(24) +
+            cols.map((c) => String(row[c] ? row[c].toFixed(2) : '-').padStart(9)).join('')
+        );
+      }
+      break;
+    }
+
+    case 'settings': {
+      requireFlagValues(flags, ['business-id', 'reminders', 'late-fee', 'late-fee-after', 'brand-color', 'logo-url', 'footer']);
+      const changes = {};
+      if (flags.reminders !== undefined) {
+        if (flags.reminders === 'off') changes.reminders_enabled = false;
+        else {
+          const days = String(flags.reminders).split(',').map((d) => Number(d.trim()));
+          if (days.some((d) => !Number.isInteger(d))) {
+            print.error('--reminders must be days relative to the due date, like "-3,0,7", or off');
+            process.exit(1);
+          }
+          changes.reminders_enabled = true;
+          changes.reminder_days = days;
+        }
+      }
+      if (flags['late-fee'] !== undefined) {
+        const fee = String(flags['late-fee']).trim();
+        const m = /^(\d+(?:\.\d{1,2})?)(%?)$/.exec(fee);
+        if (fee === 'none') changes.late_fee_type = 'none';
+        else if (m) Object.assign(changes, { late_fee_type: m[2] ? 'percent' : 'fixed', late_fee_value: Number(m[1]) });
+        else {
+          print.error('--late-fee must be a percent like 1.5%, an amount like 25, or none');
+          process.exit(1);
+        }
+      }
+      if (flags['late-fee-after'] !== undefined) changes.late_fee_after_days = Number(flags['late-fee-after']);
+      if (flags['brand-color'] !== undefined) changes.brand_color = flags['brand-color'] === 'none' ? null : flags['brand-color'];
+      if (flags['logo-url'] !== undefined) changes.logo_url = flags['logo-url'] === 'none' ? null : flags['logo-url'];
+      if (flags.footer !== undefined) changes.invoice_footer = flags.footer === 'none' ? null : flags.footer;
+
+      const settings = Object.keys(changes).length
+        ? await updateInvoiceSettings(client, { businessId: flags['business-id'], ...changes })
+        : await getInvoiceSettings(client, { businessId: flags['business-id'] });
+      if (flags.json) {
+        print.json(settings);
+        break;
+      }
+      print.info('Reminders: ' + (settings.reminders_enabled ? settings.reminder_days.join(', ') + ' days from due' : 'off'));
+      print.info(
+        'Late fee: ' +
+          (settings.late_fee_type === 'none'
+            ? 'none'
+            : (settings.late_fee_type === 'percent' ? settings.late_fee_value + '%' : settings.late_fee_value) +
+              ', ' + settings.late_fee_after_days + ' days after due')
+      );
+      print.info('Brand colour: ' + (settings.brand_color || 'default'));
+      print.info('Logo: ' + (settings.logo_url || 'none'));
+      if (settings.invoice_footer) print.info('Footer: ' + settings.invoice_footer);
+      break;
+    }
+
     default:
       print.error('Unknown invoice command: ' + subcommand);
-      print.info('Available: create, list, get, update, publish, send, delete');
+      print.info('Available: create, list, get, update, publish, send, delete, aging, settings');
       process.exit(1);
   }
 }
@@ -4589,6 +5013,23 @@ async function handleLightning(subcommand, args, flags) {
         await handleInvoice(subcommand, args, flags);
         break;
 
+      case 'client':
+        await handleClientCommand(subcommand, args, flags);
+        break;
+
+      case 'project':
+        await handleProject(subcommand, args, flags);
+        break;
+
+      case 'time':
+        await handleTime(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.16.0",
+  "version": "0.18.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/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,
@@ -65,6 +76,24 @@ export type {
   ListInvoicesResult,
 } from './invoices.js';
 
+// Projects, time, aging, invoice settings, portal links
+export {
+  getArAging,
+  getInvoiceSettings,
+  updateInvoiceSettings,
+  createClientPortalLink,
+  revokeClientPortalLink,
+  listProjects,
+  getProject,
+  createProject,
+  logTime,
+  startTimer,
+  stopTimer,
+  listTimeEntries,
+  invoiceProjectTime,
+} from './projects.js';
+export type { ArAging, AgingRow, InvoiceSettings, Project, ProjectStats, TimeEntry } from './projects.js';
+
 // Webhook exports
 export {
   verifyWebhookSignature,

package/src/index.js

@@ -82,8 +82,31 @@ import {
   sendInvoice,
   getInvoicePaymentData,
   InvoiceStatus,
+  listTaxRates,
+  createTaxRate,
+  deleteTaxRate,
+  listInvoiceItems,
+  createInvoiceItem,
+  deleteInvoiceItem,
 } from './invoices.js';
 
+// Projects, time, aging, invoice settings, portal links
+import {
+  getArAging,
+  getInvoiceSettings,
+  updateInvoiceSettings,
+  createClientPortalLink,
+  revokeClientPortalLink,
+  listProjects,
+  getProject,
+  createProject,
+  logTime,
+  startTimer,
+  stopTimer,
+  listTimeEntries,
+  invoiceProjectTime,
+} from './projects.js';
+
 // Wallet exports
 import {
   WalletClient,
@@ -231,6 +254,25 @@ export {
   sendInvoice,
   getInvoicePaymentData,
   InvoiceStatus,
+  listTaxRates,
+  createTaxRate,
+  deleteTaxRate,
+  listInvoiceItems,
+  createInvoiceItem,
+  deleteInvoiceItem,
+  getArAging,
+  getInvoiceSettings,
+  updateInvoiceSettings,
+  createClientPortalLink,
+  revokeClientPortalLink,
+  listProjects,
+  getProject,
+  createProject,
+  logTime,
+  startTimer,
+  stopTimer,
+  listTimeEntries,
+  invoiceProjectTime,
   
   // 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

@@ -15,6 +15,8 @@ import { createInterface } from 'node:readline';
 import * as reports from './finances-reports.js';
 import { getFinanceSummary, listFinanceAccounts, listFinanceTransactions } from './finances.js';
 import * as sf from './statements-fetch.js';
+import { listInvoices, getInvoice, createInvoice } from './invoices.js';
+import * as projects from './projects.js';
 
 export const PROTOCOL_VERSION = '2025-06-18';
 
@@ -218,6 +220,107 @@ export const TOOLS = [
       return { ...text({ banks: results }), isError: false };
     },
   },
+  {
+    name: 'invoice_list',
+    description: 'List invoices (number, status, amount, currency, due date, client). Filter by status: draft, sent, overdue, paid, cancelled.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        businessId: { type: 'string' },
+        status: { type: 'string', enum: ['draft', 'sent', 'overdue', 'paid', 'cancelled'] },
+        clientId: { type: 'string' },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text(await listInvoices(client, args)),
+  },
+  {
+    name: 'invoice_get',
+    description: 'One invoice with its line items, totals, payment details and status.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false },
+    handler: async (args, { client }) => text(await getInvoice(client, args.id)),
+  },
+  {
+    name: 'invoice_create_draft',
+    description:
+      'Create a DRAFT itemised invoice (nothing is sent). lineItems: [{description, quantity, unit_price, tax_rate?, tax_name?}]; discount: {type: percent|fixed, value}. The server computes the total.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        businessId: { type: 'string' },
+        clientId: { type: 'string' },
+        currency: { type: 'string', description: 'ISO code, default USD' },
+        dueDate: { type: 'string', description: 'ISO date' },
+        notes: { type: 'string' },
+        lineItems: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 100,
+          items: {
+            type: 'object',
+            properties: {
+              description: { type: 'string' },
+              quantity: { type: 'number' },
+              unit_price: { type: 'number' },
+              tax_rate: { type: 'number' },
+              tax_name: { type: 'string' },
+            },
+            required: ['description', 'quantity', 'unit_price'],
+            additionalProperties: false,
+          },
+        },
+        discount: {
+          type: 'object',
+          properties: { type: { type: 'string', enum: ['percent', 'fixed'] }, value: { type: 'number' } },
+          required: ['type', 'value'],
+          additionalProperties: false,
+        },
+      },
+      required: ['lineItems'],
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text(await createInvoice(client, { ...args, currency: args.currency || 'USD' })),
+  },
+  {
+    name: 'invoice_ar_aging',
+    description: 'Accounts receivable aging: unpaid sent invoices by days past due (current, 1-30, 31-60, 61-90, 90+), per currency and per client.',
+    inputSchema: { type: 'object', properties: { businessId: { type: 'string' } }, additionalProperties: false },
+    handler: async (args, { client }) => text(await projects.getArAging(client, args)),
+  },
+  {
+    name: 'project_list',
+    description: 'List active projects (name, client, hourly rate, budget).',
+    inputSchema: { type: 'object', properties: { businessId: { type: 'string' }, includeArchived: { type: 'boolean' } }, additionalProperties: false },
+    handler: async (args, { client }) => text({ projects: await projects.listProjects(client, args) }),
+  },
+  {
+    name: 'project_get',
+    description: 'One project with hours logged, unbilled value, billed and paid totals.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false },
+    handler: async (args, { client }) => text(await projects.getProject(client, args.id)),
+  },
+  {
+    name: 'time_log',
+    description: 'Log finished time on a project, in minutes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string' },
+        minutes: { type: 'integer', minimum: 1, maximum: 100000 },
+        description: { type: 'string' },
+        billable: { type: 'boolean' },
+      },
+      required: ['projectId', 'minutes'],
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text({ time_entry: await projects.logTime(client, args) }),
+  },
+  {
+    name: 'project_invoice_time',
+    description: "Bill a project's unbilled billable time as a DRAFT itemised invoice (not sent). Returns the invoice number and amount.",
+    inputSchema: { type: 'object', properties: { projectId: { type: 'string' } }, required: ['projectId'], additionalProperties: false },
+    handler: async (args, { client }) => text(await projects.invoiceProjectTime(client, args.projectId)),
+  },
 ];
 
 /** Answer one JSON-RPC message; null for a notification. */

package/src/projects.d.ts

@@ -0,0 +1,91 @@
+import type { CoinPayClient } from './client.js';
+
+export interface AgingRow {
+  currency: string;
+  current: number;
+  '1_30': number;
+  '31_60': number;
+  '61_90': number;
+  '90_plus': number;
+  total: number;
+}
+
+export interface ArAging {
+  as_of: string;
+  totals: AgingRow[];
+  clients: Array<AgingRow & { client_id: string | null; name: string; invoices: number }>;
+}
+
+export interface InvoiceSettings {
+  business_id: string;
+  reminders_enabled: boolean;
+  reminder_days: number[];
+  late_fee_type: 'none' | 'percent' | 'fixed';
+  late_fee_value: number | null;
+  late_fee_after_days: number;
+  brand_color: string | null;
+  logo_url: string | null;
+  invoice_footer: string | null;
+}
+
+export interface Project {
+  id: string;
+  business_id: string;
+  client_id: string | null;
+  name: string;
+  hourly_rate: number | null;
+  currency: string;
+  budget_hours: number | null;
+  status: 'active' | 'archived';
+}
+
+export interface ProjectStats {
+  hours: number;
+  billable_hours: number;
+  unbilled_amount: number;
+  billed_amount: number;
+  paid_amount: number;
+}
+
+export interface TimeEntry {
+  id: string;
+  project_id: string;
+  description: string;
+  started_at: string;
+  ended_at: string | null;
+  /** null while the timer is running */
+  minutes: number | null;
+  billable: boolean;
+  hourly_rate: number | null;
+  invoice_id: string | null;
+}
+
+export function getArAging(client: CoinPayClient, options?: { businessId?: string }): Promise<ArAging>;
+export function getInvoiceSettings(client: CoinPayClient, options?: { businessId?: string }): Promise<InvoiceSettings>;
+export function updateInvoiceSettings(
+  client: CoinPayClient,
+  options: { businessId?: string } & Partial<Omit<InvoiceSettings, 'business_id'>>
+): Promise<InvoiceSettings>;
+export function createClientPortalLink(client: CoinPayClient, clientId: string): Promise<string>;
+export function revokeClientPortalLink(client: CoinPayClient, clientId: string): Promise<Record<string, unknown>>;
+export function listProjects(client: CoinPayClient, options?: { businessId?: string; includeArchived?: boolean }): Promise<Project[]>;
+export function getProject(client: CoinPayClient, id: string): Promise<{ project: Project; stats: ProjectStats }>;
+export function createProject(
+  client: CoinPayClient,
+  options: { businessId?: string; name: string; clientId?: string; hourlyRate?: number; currency?: string; budgetHours?: number; notes?: string }
+): Promise<Project>;
+export function logTime(
+  client: CoinPayClient,
+  options: { projectId: string; minutes: number; description?: string; billable?: boolean; hourlyRate?: number; startedAt?: string }
+): Promise<TimeEntry>;
+export function startTimer(client: CoinPayClient, options: { projectId: string; description?: string }): Promise<TimeEntry>;
+export function stopTimer(client: CoinPayClient, options?: { entryId?: string; businessId?: string }): Promise<TimeEntry>;
+export function listTimeEntries(
+  client: CoinPayClient,
+  options?: { projectId?: string; businessId?: string; unbilled?: boolean }
+): Promise<TimeEntry[]>;
+export function invoiceProjectTime(
+  client: CoinPayClient,
+  projectId: string,
+  options?: { entryIds?: string[] }
+): Promise<{ invoice: { id: string; invoice_number: string; amount: number }; entries_billed: number }>;

package/src/projects.js

@@ -0,0 +1,106 @@
+/**
+ * Projects, time tracking, AR aging, invoice settings and client portal links.
+ *
+ * An API key is locked to its own business, so `businessId` is optional when
+ * the client was created with one.
+ */
+
+const q = (params) => {
+  const entries = Object.entries(params).filter(([, v]) => v !== undefined && v !== null && v !== '');
+  return entries.length ? '?' + new URLSearchParams(entries.map(([k, v]) => [k, String(v)])).toString() : '';
+};
+const json = (method, body) => ({ method, body: JSON.stringify(body) });
+
+/** Open invoices by days past due, per currency and per client. */
+export async function getArAging(client, { businessId } = {}) {
+  return client.request('/invoices/aging' + q({ business_id: businessId }));
+}
+
+/** Reminder schedule, late fee and branding. */
+export async function getInvoiceSettings(client, { businessId } = {}) {
+  const data = await client.request('/invoice-settings' + q({ business_id: businessId }));
+  return data.settings;
+}
+
+/**
+ * Update invoice settings. Fields use the API's names: reminders_enabled,
+ * reminder_days (e.g. [-3, 0, 7]), late_fee_type ('none'|'percent'|'fixed'),
+ * late_fee_value, late_fee_after_days, brand_color, logo_url, invoice_footer.
+ */
+export async function updateInvoiceSettings(client, { businessId, ...fields }) {
+  const data = await client.request('/invoice-settings', json('PUT', { business_id: businessId, ...fields }));
+  return data.settings;
+}
+
+/** Create (or replace) a client's portal link; the old one stops working. */
+export async function createClientPortalLink(client, clientId) {
+  const data = await client.request(`/clients/${encodeURIComponent(clientId)}/portal-link`, { method: 'POST' });
+  return data.url;
+}
+
+export async function revokeClientPortalLink(client, clientId) {
+  return client.request(`/clients/${encodeURIComponent(clientId)}/portal-link`, { method: 'DELETE' });
+}
+
+export async function listProjects(client, { businessId, includeArchived } = {}) {
+  const data = await client.request('/projects' + q({ business_id: businessId, include_archived: includeArchived ? 'true' : undefined }));
+  return data.projects ?? [];
+}
+
+/** A project with its hours, unbilled, billed and paid totals. */
+export async function getProject(client, id) {
+  return client.request('/projects/' + encodeURIComponent(id));
+}
+
+export async function createProject(client, { businessId, name, clientId, hourlyRate, currency, budgetHours, notes }) {
+  const body = { name };
+  if (businessId) body.business_id = businessId;
+  if (clientId) body.client_id = clientId;
+  if (hourlyRate !== undefined) body.hourly_rate = hourlyRate;
+  if (currency) body.currency = currency;
+  if (budgetHours !== undefined) body.budget_hours = budgetHours;
+  if (notes) body.notes = notes;
+  const data = await client.request('/projects', json('POST', body));
+  return data.project;
+}
+
+/** Log finished time on a project. */
+export async function logTime(client, { projectId, minutes, description, billable, hourlyRate, startedAt }) {
+  const body = { project_id: projectId, minutes };
+  if (description) body.description = description;
+  if (billable !== undefined) body.billable = billable;
+  if (hourlyRate !== undefined) body.hourly_rate = hourlyRate;
+  if (startedAt) body.started_at = startedAt;
+  const data = await client.request('/time-entries', json('POST', body));
+  return data.time_entry;
+}
+
+/** Start a running timer (one per person). */
+export async function startTimer(client, { projectId, description }) {
+  const data = await client.request('/time-entries', json('POST', { project_id: projectId, start: true, ...(description ? { description } : {}) }));
+  return data.time_entry;
+}
+
+/** Stop a running timer; with no id, stops yours wherever it runs. */
+export async function stopTimer(client, { entryId, businessId } = {}) {
+  let id = entryId;
+  if (!id) {
+    const data = await client.request('/time-entries' + q({ business_id: businessId, running: 'true' }));
+    id = data.time_entries?.[0]?.id;
+    if (!id) throw new Error('No timer is running');
+  }
+  const data = await client.request('/time-entries/' + encodeURIComponent(id), json('PATCH', { stop: true }));
+  return data.time_entry;
+}
+
+export async function listTimeEntries(client, { projectId, businessId, unbilled } = {}) {
+  const data = await client.request(
+    '/time-entries' + q({ project_id: projectId, business_id: businessId, unbilled: unbilled ? 'true' : undefined })
+  );
+  return data.time_entries ?? [];
+}
+
+/** Bill a project's unbilled billable time as a draft itemised invoice. */
+export async function invoiceProjectTime(client, projectId, { entryIds } = {}) {
+  return client.request(`/projects/${encodeURIComponent(projectId)}/invoice`, json('POST', entryIds ? { entry_ids: entryIds } : {}));
+}

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',
   };