@profullstack/coinpay 0.17.0 → 0.18.0

package/CHANGELOG.md

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

package/bin/coinpay.js

@@ -31,6 +31,21 @@ import {
   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';
@@ -173,6 +188,11 @@ function createUnauthenticatedClient() {
 }
 
 const BOOLEAN_FLAGS = new Set([
+  // projects, time, client portal
+  'non-billable',
+  'unbilled',
+  'archived',
+  'revoke',
   'active',
   // finances reports / statements
   'wait',
@@ -237,7 +257,7 @@ function parseArgs(args) {
         const next = args[i + 1];
         if (BOOLEAN_FLAGS.has(name)) {
           result.flags[name] = true;
-        } else if (next && !next.startsWith('-')) {
+        } else if (next && (!next.startsWith('-') || /^-\d/.test(next))) {
           setFlag(name, next);
           i++;
         } else {
@@ -471,6 +491,27 @@ ${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]
@@ -1164,6 +1205,141 @@ 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';
@@ -1686,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);
   }
 }
@@ -4764,6 +5013,18 @@ 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);

package/package.json

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

@@ -76,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

@@ -90,6 +90,23 @@ import {
   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,
@@ -243,6 +260,19 @@ export {
   listInvoiceItems,
   createInvoiceItem,
   deleteInvoiceItem,
+  getArAging,
+  getInvoiceSettings,
+  updateInvoiceSettings,
+  createClientPortalLink,
+  revokeClientPortalLink,
+  listProjects,
+  getProject,
+  createProject,
+  logTime,
+  startTimer,
+  stopTimer,
+  listTimeEntries,
+  invoiceProjectTime,
   
   // Wallet
   WalletClient,

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 } : {}));
+}