@profullstack/coinpay 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.19.0] - 2026-10-17
+
+### Added
+- Contractors: `coinpay contractor list|add|get|link|offboard|contract|send|end|pending|approve|reject|bonus|expense|1099`.
+  Invite a contractor (they get a private portal to add a payout wallet, file a W-9 or W-8,
+  sign contracts and submit hours, milestones and expenses), contract fixed, hourly or
+  milestone work, approve submissions, and see who needs a 1099-NEC.
+- Pay runs: `coinpay payrun list|create|get|pay|record|delete`. A run collects fixed fees
+  that are due plus approved work, one line per contractor. `pay <id> --yes` sends from the
+  business payout wallet (signed-in owner only); `record` logs a payment made from your own wallet.
+- SDK: `listContractors`, `addContractor`, `createContract`, `sendContract`, `reviewWorkItem`,
+  `createPayRun`, `payPayRun`, `recordPayRunPayments`, `get1099Summary` and friends.
+- MCP: `contractor_list`, `contractor_get`, `contractor_work_list`, `contractor_work_review`,
+  `pay_run_list`, `pay_run_get`, `pay_run_draft`, `contractor_1099_summary`. None of them sends money.
+
 ## [0.18.0] - 2026-10-17
 
 ### Added

package/bin/coinpay.js

@@ -46,6 +46,26 @@ import {
   listTimeEntries,
   invoiceProjectTime,
 } from '../src/projects.js';
+import {
+  listContractors,
+  getContractor,
+  addContractor,
+  createContractorPortalLink,
+  offboardContractor,
+  createContract,
+  sendContract,
+  endContract,
+  listWorkItems,
+  reviewWorkItem,
+  addContractorPayment,
+  listPayRuns,
+  getPayRun,
+  createPayRun,
+  deletePayRun,
+  payPayRun,
+  recordPayRunPayments,
+  get1099Summary,
+} from '../src/contractors.js';
 import { readFileSync, writeFileSync, existsSync, unlinkSync, chmodSync } from 'fs';
 import { execSync, spawn } from 'child_process';
 import { createInterface } from 'readline';
@@ -500,6 +520,28 @@ ${colors.cyan}Commands:${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}contractor${colors.reset}
+    list                  Contractors (--business-id, --all includes offboarded)
+    add                   --name, --email [--country US] [--title] [--no-invite]
+    get <id>              Wallet, tax form, contracts and work lines
+    link <id>             New portal link (--email to send it)
+    contract <id>         Draft: --title --kind fixed|hourly --rate 2000 [--frequency monthly]
+    send <contract-id>    Sign as the business and send: --signature "Your Name"
+    end <contract-id>     [--reason] [--end YYYY-MM-DD]
+    pending               Work waiting for approval
+    approve <id>...       Approve work lines; reject <id> --note "why"
+    bonus | expense       --contract <id> --amount 250 --description "..."
+    1099                  Totals and who needs a 1099-NEC (--year 2026)
+    offboard <id>         End contracts and revoke the portal link
+
+  ${colors.bright}payrun${colors.reset}
+    list                  Pay runs
+    create                Draft from fixed fees due + approved work [--date YYYY-MM-DD]
+    get <id>              Per-contractor amounts, lines and warnings
+    pay <id> --yes        Send from the business payout wallet (owner login only)
+    record <id>           You paid yourself: --item <item-id> --tx <hash>
+    delete <id>           Discard a draft
+
   ${colors.bright}project${colors.reset}
     list                  Projects (--business-id, --archived)
     create                --name, [--client-id] [--rate 120] [--budget 40]
@@ -640,7 +682,7 @@ ${colors.cyan}Commands:${colors.reset}
     due [--days 7]        What is due and overdue across every account (--days up to 60)
     recurring             Every recurring charge detected, with next date and monthly cost
     due-day <id> <1-31|clear>  A card/loan's statement due day (--amount 810.46, or balance)
-    daily [show|on|off|send-now]  Daily summary email: due soon, new activity, position (--hour 7 --to …)
+    daily [show|on|off|send-now]  Daily summary email: spend vs target, top cuts, due soon, position (--hour 7 --to …, --target 100)
 
   ${colors.bright}escrow${colors.reset}
     create                Create a new escrow
@@ -1228,6 +1270,200 @@ function hoursOf(minutes) {
   return minutes == null ? 'running' : Math.floor(minutes / 60) + 'h' + String(minutes % 60).padStart(2, '0') + 'm';
 }
 
+const usdText = (n) => '$' + Number(n).toFixed(2);
+
+function usageExit(usage) {
+  print.error('Usage: ' + usage);
+  process.exit(1);
+}
+
+async function handleContractor(subcommand, args, flags) {
+  const client = createClient();
+  requireFlagValues(flags, ['business-id', 'name', 'email', 'country', 'title', 'kind', 'rate', 'frequency', 'start', 'end', 'note', 'signature', 'reason', 'amount', 'contract', 'description', 'status', 'year']);
+  switch (subcommand) {
+    case 'list': {
+      const rows = await listContractors(client, { businessId: flags['business-id'], includeOffboarded: !!flags.all });
+      if (flags.json) return print.json(rows);
+      if (!rows.length) return print.info('No contractors');
+      for (const c of rows) {
+        const bits = [c.status, c.payout_currency || 'no wallet', c.tax_form ? c.tax_form + ' ' + c.tax_status : 'no tax form'];
+        if (c.pending_approvals) bits.push(c.pending_approvals + ' to approve');
+        print.info(c.id + '  ' + c.name + ' <' + c.email + '>  ' + bits.join(' · '));
+      }
+      return;
+    }
+    case 'add': {
+      if (!flags.name || !flags.email) usageExit('coinpay contractor add --name "Ada" --email ada@example.com [--country US] [--no-invite]');
+      const result = await addContractor(client, {
+        businessId: flags['business-id'],
+        name: flags.name,
+        email: flags.email,
+        country: flags.country?.toUpperCase(),
+        jobTitle: flags.title,
+        sendInvite: !flags['no-invite'],
+      });
+      if (flags.json) return print.json(result);
+      print.success('Contractor added: ' + result.contractor.id + (flags['no-invite'] ? '' : ' (invite emailed)'));
+      return print.info('Portal link: ' + result.portal_url);
+    }
+    case 'get': {
+      if (args.length !== 1) usageExit('coinpay contractor get <id>');
+      const data = await getContractor(client, args[0]);
+      if (flags.json) return print.json(data);
+      const c = data.contractor;
+      print.info(c.name + ' <' + c.email + '>  ' + c.status);
+      print.info('Wallet: ' + (c.payout_wallet ? c.payout_currency + ' ' + c.payout_wallet : 'not set'));
+      print.info('Tax form: ' + (c.tax_form ? c.tax_form + ' ' + c.tax_status + (c.tax_id_last4 ? ' •••' + c.tax_id_last4 : '') : 'missing'));
+      for (const k of data.contracts) {
+        const terms = k.kind === 'fixed' ? usdText(k.rate) + ' ' + k.frequency : k.kind === 'hourly' ? usdText(k.rate) + '/h' : 'milestones';
+        print.info('  contract ' + k.id + '  ' + k.title + '  ' + terms + '  ' + k.status);
+      }
+      for (const w of data.work_items.slice(0, 20)) print.info('  ' + w.work_date + '  ' + w.kind + '  ' + usdText(w.amount) + '  ' + w.status + '  ' + w.id);
+      return;
+    }
+    case 'link': {
+      if (args.length !== 1) usageExit('coinpay contractor link <id> [--email]');
+      const url = await createContractorPortalLink(client, args[0], { sendEmail: !!flags.email });
+      return flags.json ? print.json({ url }) : print.info(url);
+    }
+    case 'offboard': {
+      if (args.length !== 1) usageExit('coinpay contractor offboard <id>');
+      await offboardContractor(client, args[0]);
+      return print.success('Offboarded');
+    }
+    case 'contract': {
+      if (args.length !== 1 || !flags.title || !flags.kind) {
+        usageExit('coinpay contractor contract <id> --title "Retainer" --kind fixed|hourly --rate 2000 [--frequency monthly] [--start YYYY-MM-DD]');
+      }
+      if (flags.kind === 'milestone') usageExit('milestone contracts are created in the dashboard (they need a milestone list)');
+      const rate = parseNonNegativeAmount(String(flags.rate ?? ''));
+      if (!rate) usageExit('--rate must be an amount with at most two decimals');
+      const contract = await createContract(client, args[0], {
+        title: flags.title,
+        kind: flags.kind,
+        rate,
+        frequency: flags.frequency,
+        startDate: flags.start,
+        endDate: flags.end,
+      });
+      if (flags.json) return print.json(contract);
+      print.success('Draft contract: ' + contract.id);
+      return print.info('Send it with: coinpay contractor send ' + contract.id + ' --signature "Your Name"');
+    }
+    case 'send': {
+      if (args.length !== 1 || !flags.signature) usageExit('coinpay contractor send <contract-id> --signature "Your Name"');
+      const contract = await sendContract(client, args[0], { signature: flags.signature });
+      return flags.json ? print.json(contract) : print.success('Signed and sent: ' + contract.title);
+    }
+    case 'end': {
+      if (args.length !== 1) usageExit('coinpay contractor end <contract-id> [--reason "..."] [--end YYYY-MM-DD]');
+      const contract = await endContract(client, args[0], { reason: flags.reason, endDate: flags.end });
+      return flags.json ? print.json(contract) : print.success('Contract ended ' + contract.end_date);
+    }
+    case 'pending': {
+      const rows = await listWorkItems(client, { businessId: flags['business-id'], status: flags.status || 'submitted' });
+      if (flags.json) return print.json(rows);
+      if (!rows.length) return print.info('Nothing waiting');
+      for (const w of rows) {
+        print.info(w.id + '  ' + (w.contractors?.name || '') + '  ' + w.kind + (w.minutes ? ' ' + (w.minutes / 60).toFixed(2) + 'h' : '') + '  ' + usdText(w.amount) + '  ' + w.description);
+      }
+      return;
+    }
+    case 'approve':
+    case 'reject': {
+      if (!args.length) usageExit('coinpay contractor ' + subcommand + ' <work-item-id>...' + (subcommand === 'reject' ? ' --note "why"' : ''));
+      for (const workId of args) {
+        const w = await reviewWorkItem(client, workId, { action: subcommand, note: flags.note });
+        print.success((subcommand === 'approve' ? 'Approved ' : 'Rejected ') + w.id + '  ' + usdText(w.amount));
+      }
+      return;
+    }
+    case 'bonus':
+    case 'expense': {
+      if (!flags.contract || !flags.amount || !flags.description) {
+        usageExit('coinpay contractor ' + subcommand + ' --contract <id> --amount 250 --description "..."');
+      }
+      const amount = parseNonNegativeAmount(String(flags.amount));
+      if (!amount) usageExit('--amount must be an amount with at most two decimals');
+      const w = await addContractorPayment(client, { businessId: flags['business-id'], contractId: flags.contract, kind: subcommand, amount, description: flags.description });
+      return flags.json ? print.json(w) : print.success(subcommand + ' added: ' + usdText(w.amount) + ' (goes into the next pay run)');
+    }
+    case '1099': {
+      const year = flags.year ? Number(flags.year) : new Date().getUTCFullYear() - 1;
+      const data = await get1099Summary(client, { businessId: flags['business-id'], year });
+      if (flags.json) return print.json(data);
+      if (!data.contractors.length) return print.info('No contractor payments in ' + year);
+      for (const r of data.contractors) {
+        print.info(String(r.name).padEnd(30) + usdText(r.total_paid).padStart(14) + '  ' + (r.needs_1099_nec ? '1099-NEC' : r.missing_w9 ? 'MISSING W-9' : '-'));
+      }
+      return print.info('Full CSV with tax ids: the Contractors page, Tax forms & 1099 tab (owner only).');
+    }
+    default:
+      usageExit('coinpay contractor <list|add|get|link|offboard|contract|send|end|pending|approve|reject|bonus|expense|1099>');
+  }
+}
+
+async function handlePayRun(subcommand, args, flags) {
+  const client = createClient();
+  requireFlagValues(flags, ['business-id', 'date', 'item', 'tx']);
+  switch (subcommand) {
+    case 'list': {
+      const rows = await listPayRuns(client, { businessId: flags['business-id'] });
+      if (flags.json) return print.json(rows);
+      if (!rows.length) return print.info('No pay runs');
+      for (const r of rows) print.info(r.id + '  #' + r.number + '  ' + r.pay_date + '  ' + usdText(r.total) + '  ' + r.status + '  ' + r.paid + '/' + r.contractors + ' paid');
+      return;
+    }
+    case 'create': {
+      const run = await createPayRun(client, { businessId: flags['business-id'], payDate: flags.date });
+      if (flags.json) return print.json(run);
+      print.success('Drafted pay run #' + run.number + ' for ' + usdText(run.total) + ': ' + run.id);
+      return print.info('Review it with: coinpay payrun get ' + run.id);
+    }
+    case 'get': {
+      if (args.length !== 1) usageExit('coinpay payrun get <id>');
+      const data = await getPayRun(client, args[0]);
+      if (flags.json) return print.json(data);
+      const r = data.pay_run;
+      print.info('Pay run #' + r.number + '  ' + r.pay_date + '  ' + usdText(r.total) + '  ' + r.status);
+      for (const i of data.items) {
+        print.info('  ' + i.id + '  ' + String(i.contractors?.name || '').padEnd(24) + usdText(i.amount).padStart(12) + '  ' + i.status + (i.tx_hash ? '  ' + i.tx_hash : '') + (i.can_send_from_wallet ? '' : '  (pay manually)'));
+        for (const w of i.warnings || []) print.info('      ! ' + w);
+      }
+      return;
+    }
+    case 'pay': {
+      if (args.length !== 1) usageExit('coinpay payrun pay <id> --yes   (sends from the business payout wallet; needs `coinpay login` as the owner)');
+      if (!flags.yes) {
+        print.error('This sends crypto and cannot be undone. Review with `coinpay payrun get ' + args[0] + '`, then add --yes.');
+        process.exit(1);
+      }
+      const result = await payPayRun(client, args[0]);
+      if (flags.json) return print.json(result);
+      for (const o of result.outcomes) {
+        const line = o.contractor + ': ' + o.status + (o.tx_hash ? ' ' + o.tx_hash : '') + (o.error ? ' · ' + o.error : '');
+        if (o.error) print.error(line);
+        else print.success(line);
+      }
+      return print.info('Pay run is ' + result.pay_run.status);
+    }
+    case 'record': {
+      if (args.length !== 1 || !flags.item || !flags.tx) usageExit('coinpay payrun record <id> --item <item-id> --tx <hash>   (you paid from your own wallet)');
+      const result = await recordPayRunPayments(client, args[0], [{ itemId: flags.item, txHash: flags.tx }]);
+      if (flags.json) return print.json(result);
+      const o = result.outcomes[0];
+      return o.error ? print.error(o.error) : print.success('Recorded. Pay run is ' + result.pay_run.status);
+    }
+    case 'delete': {
+      if (args.length !== 1) usageExit('coinpay payrun delete <id>');
+      await deletePayRun(client, args[0]);
+      return print.success('Draft deleted; its lines go back to the approved pool');
+    }
+    default:
+      usageExit('coinpay payrun <list|create|get|pay|record|delete>');
+  }
+}
+
 async function handleProject(subcommand, args, flags) {
   const client = createClient();
   requireFlagValues(flags, ['business-id', 'name', 'client-id', 'rate', 'budget', 'currency']);
@@ -5021,6 +5257,16 @@ async function handleLightning(subcommand, args, flags) {
         await handleProject(subcommand, args, flags);
         break;
 
+      case 'contractor':
+      case 'contractors':
+        await handleContractor(subcommand, args, flags);
+        break;
+
+      case 'payrun':
+      case 'payruns':
+        await handlePayRun(subcommand, args, flags);
+        break;
+
       case 'time':
         await handleTime(subcommand, args, flags);
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.18.0",
+  "version": "0.20.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/contractors.d.ts

@@ -0,0 +1,124 @@
+import type { CoinPayClient } from './client.js';
+
+export interface Contractor {
+  id: string;
+  business_id: string;
+  name: string;
+  email: string;
+  country: string | null;
+  job_title: string | null;
+  status: 'invited' | 'active' | 'offboarded';
+  payout_currency: string | null;
+  payout_wallet: string | null;
+  payout_wallet_changed_at: string | null;
+  tax_form: 'W9' | 'W8BEN' | 'W8BENE' | null;
+  tax_status: 'missing' | 'submitted' | 'verified';
+  tax_legal_name: string | null;
+  tax_id_last4: string | null;
+  pending_approvals?: number;
+}
+
+export interface ContractorMilestone {
+  id: string;
+  contract_id: string;
+  title: string;
+  amount: string;
+  due_date: string | null;
+  position: number;
+  status: 'pending' | 'submitted' | 'approved' | 'paid';
+}
+
+export interface ContractorContract {
+  id: string;
+  contractor_id: string;
+  title: string;
+  scope: string | null;
+  kind: 'fixed' | 'hourly' | 'milestone';
+  rate: string | null;
+  frequency: 'weekly' | 'biweekly' | 'semimonthly' | 'monthly' | null;
+  start_date: string;
+  end_date: string | null;
+  next_pay_date: string | null;
+  status: 'draft' | 'sent' | 'active' | 'ended';
+  contractor_milestones?: ContractorMilestone[];
+}
+
+export interface ContractorWorkItem {
+  id: string;
+  contractor_id: string;
+  contract_id: string;
+  kind: 'hours' | 'milestone' | 'expense' | 'bonus' | 'fixed';
+  description: string;
+  work_date: string;
+  minutes: number | null;
+  amount: string;
+  status: 'submitted' | 'approved' | 'rejected' | 'paid';
+  review_note: string | null;
+}
+
+export interface PayRun {
+  id: string;
+  business_id: string;
+  number: number;
+  pay_date: string;
+  status: 'draft' | 'processing' | 'paid' | 'partially_paid';
+  total: string;
+  auto_drafted: boolean;
+  paid_at: string | null;
+  contractors?: number;
+  paid?: number;
+}
+
+export interface PayRunItem {
+  id: string;
+  contractor_id: string;
+  amount: string;
+  status: 'pending' | 'processing' | 'paid' | 'failed' | 'indeterminate';
+  method: 'wallet' | 'manual' | null;
+  tx_hash: string | null;
+  error: string | null;
+  invoice_number: string;
+  warnings?: string[];
+  can_send_from_wallet?: boolean;
+}
+
+export interface PayOutcome {
+  item_id: string;
+  contractor: string;
+  status: string;
+  tx_hash?: string | null;
+  error?: string;
+}
+
+export function listContractors(client: CoinPayClient, options?: { businessId?: string; includeOffboarded?: boolean }): Promise<Contractor[]>;
+export function getContractor(client: CoinPayClient, contractorId: string): Promise<{ contractor: Contractor; contracts: ContractorContract[]; work_items: ContractorWorkItem[]; payments: PayRunItem[] }>;
+export function addContractor(client: CoinPayClient, input: { businessId?: string; name: string; email: string; country?: string; jobTitle?: string; sendInvite?: boolean }): Promise<{ contractor: Contractor; portal_url: string }>;
+export function createContractorPortalLink(client: CoinPayClient, contractorId: string, options?: { sendEmail?: boolean }): Promise<string>;
+export function offboardContractor(client: CoinPayClient, contractorId: string): Promise<{ success: boolean }>;
+export function createContract(
+  client: CoinPayClient,
+  contractorId: string,
+  input: {
+    title: string;
+    kind: 'fixed' | 'hourly' | 'milestone';
+    scope?: string;
+    rate?: number;
+    frequency?: 'weekly' | 'biweekly' | 'semimonthly' | 'monthly';
+    startDate?: string;
+    endDate?: string;
+    firstPayDate?: string;
+    milestones?: { title: string; amount: number; due_date?: string }[];
+  }
+): Promise<ContractorContract>;
+export function sendContract(client: CoinPayClient, contractId: string, input: { signature: string }): Promise<ContractorContract>;
+export function endContract(client: CoinPayClient, contractId: string, input?: { reason?: string; endDate?: string }): Promise<ContractorContract>;
+export function listWorkItems(client: CoinPayClient, options?: { businessId?: string; status?: string; contractorId?: string }): Promise<ContractorWorkItem[]>;
+export function reviewWorkItem(client: CoinPayClient, workItemId: string, input: { action: 'approve' | 'reject'; note?: string }): Promise<ContractorWorkItem>;
+export function addContractorPayment(client: CoinPayClient, input: { businessId?: string; contractId: string; kind: 'bonus' | 'expense'; amount: number; description: string }): Promise<ContractorWorkItem>;
+export function listPayRuns(client: CoinPayClient, options?: { businessId?: string }): Promise<PayRun[]>;
+export function getPayRun(client: CoinPayClient, payRunId: string): Promise<{ pay_run: PayRun; items: PayRunItem[]; sendable_coins: string[] }>;
+export function createPayRun(client: CoinPayClient, options?: { businessId?: string; payDate?: string }): Promise<PayRun>;
+export function deletePayRun(client: CoinPayClient, payRunId: string): Promise<{ success: boolean }>;
+export function payPayRun(client: CoinPayClient, payRunId: string, options?: { itemIds?: string[] }): Promise<{ success: boolean; pay_run: PayRun; outcomes: PayOutcome[] }>;
+export function recordPayRunPayments(client: CoinPayClient, payRunId: string, payments: { itemId: string; txHash: string }[]): Promise<{ success: boolean; pay_run: PayRun; outcomes: PayOutcome[] }>;
+export function get1099Summary(client: CoinPayClient, options?: { businessId?: string; year?: number }): Promise<{ year: number; threshold: number; contractors: { contractor_id: string; name: string; tax_form: string | null; total_paid: number; needs_1099_nec: boolean; missing_w9: boolean }[] }>;

package/src/contractors.js

@@ -0,0 +1,135 @@
+/**
+ * Contractors and pay runs: invite contractors, contract with them, approve the
+ * work they submit and pay the whole team in crypto.
+ *
+ * An API key is locked to its own business, so `businessId` is optional when
+ * the client was created with one. Paying a run needs a signed-in owner
+ * (`coinpay login`), never an API key.
+ */
+
+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) });
+const id = (v) => encodeURIComponent(v);
+
+export async function listContractors(client, { businessId, includeOffboarded } = {}) {
+  const data = await client.request('/contractors' + q({ business_id: businessId, include_offboarded: includeOffboarded ? 'true' : undefined }));
+  return data.contractors ?? [];
+}
+
+/** A contractor with contracts (and milestones), work lines and payments. */
+export async function getContractor(client, contractorId) {
+  return client.request('/contractors/' + id(contractorId));
+}
+
+/** Invite a contractor. They are emailed a portal link unless sendInvite is false. */
+export async function addContractor(client, { businessId, name, email, country, jobTitle, sendInvite }) {
+  const body = { name, email };
+  if (businessId) body.business_id = businessId;
+  if (country) body.country = country;
+  if (jobTitle) body.job_title = jobTitle;
+  if (sendInvite === false) body.send_invite = false;
+  return client.request('/contractors', json('POST', body));
+}
+
+/** Issue a new portal link (the old one stops working). Returns the URL. */
+export async function createContractorPortalLink(client, contractorId, { sendEmail } = {}) {
+  const data = await client.request(`/contractors/${id(contractorId)}/portal-link`, json('POST', { send_email: !!sendEmail }));
+  return data.url;
+}
+
+/** Offboard: ends live contracts and revokes the portal link. Records are kept. */
+export async function offboardContractor(client, contractorId) {
+  return client.request('/contractors/' + id(contractorId), { method: 'DELETE' });
+}
+
+/**
+ * Draft a contract. kind: 'fixed' (rate per frequency), 'hourly' (rate per
+ * hour) or 'milestone' (milestones: [{ title, amount, due_date? }]).
+ */
+export async function createContract(client, contractorId, { title, scope, kind, rate, frequency, startDate, endDate, firstPayDate, milestones }) {
+  const body = { title, kind };
+  if (scope) body.scope = scope;
+  if (rate !== undefined) body.rate = rate;
+  if (frequency) body.frequency = frequency;
+  if (startDate) body.start_date = startDate;
+  if (endDate) body.end_date = endDate;
+  if (firstPayDate) body.first_pay_date = firstPayDate;
+  if (milestones) body.milestones = milestones;
+  const data = await client.request(`/contractors/${id(contractorId)}/contracts`, json('POST', body));
+  return data.contract;
+}
+
+/** Sign a draft contract as the business and send it to the contractor. */
+export async function sendContract(client, contractId, { signature }) {
+  const data = await client.request('/contractor-contracts/' + id(contractId), json('PATCH', { action: 'send', signature }));
+  return data.contract;
+}
+
+export async function endContract(client, contractId, { reason, endDate } = {}) {
+  const data = await client.request('/contractor-contracts/' + id(contractId), json('PATCH', { action: 'end', reason, end_date: endDate }));
+  return data.contract;
+}
+
+/** Work lines: hours, milestones, expenses, bonuses and fixed fees. status: submitted|approved|rejected|paid */
+export async function listWorkItems(client, { businessId, status, contractorId } = {}) {
+  const data = await client.request('/contractor-work-items' + q({ business_id: businessId, status, contractor_id: contractorId }));
+  return data.work_items ?? [];
+}
+
+/** Approve or reject a submission. A rejection needs a note. */
+export async function reviewWorkItem(client, workItemId, { action, note }) {
+  const data = await client.request('/contractor-work-items/' + id(workItemId), json('PATCH', { action, note }));
+  return data.work_item;
+}
+
+/** Add a bonus or an expense reimbursement (approved immediately). */
+export async function addContractorPayment(client, { businessId, contractId, kind, amount, description }) {
+  const body = { contract_id: contractId, kind, amount, description };
+  if (businessId) body.business_id = businessId;
+  const data = await client.request('/contractor-work-items', json('POST', body));
+  return data.work_item;
+}
+
+export async function listPayRuns(client, { businessId } = {}) {
+  const data = await client.request('/pay-runs' + q({ business_id: businessId }));
+  return data.pay_runs ?? [];
+}
+
+/** A run with one item per contractor, its lines, and any warnings. */
+export async function getPayRun(client, payRunId) {
+  return client.request('/pay-runs/' + id(payRunId));
+}
+
+/** Draft a pay run (fixed fees due by payDate plus approved work). Moves no money. */
+export async function createPayRun(client, { businessId, payDate } = {}) {
+  const body = {};
+  if (businessId) body.business_id = businessId;
+  if (payDate) body.pay_date = payDate;
+  const data = await client.request('/pay-runs', json('POST', body));
+  return data.pay_run;
+}
+
+export async function deletePayRun(client, payRunId) {
+  return client.request('/pay-runs/' + id(payRunId), { method: 'DELETE' });
+}
+
+/** Send a run (or some items) from the business payout wallet. Owner session only. */
+export async function payPayRun(client, payRunId, { itemIds } = {}) {
+  return client.request(`/pay-runs/${id(payRunId)}/pay`, json('POST', itemIds ? { method: 'wallet', item_ids: itemIds } : { method: 'wallet' }));
+}
+
+/** Record payments made from your own wallet: [{ itemId, txHash }]. Owner session only. */
+export async function recordPayRunPayments(client, payRunId, payments) {
+  return client.request(
+    `/pay-runs/${id(payRunId)}/pay`,
+    json('POST', { method: 'manual', payments: payments.map((p) => ({ item_id: p.itemId, tx_hash: p.txHash })) })
+  );
+}
+
+/** Per-contractor totals for a calendar year and who needs a 1099-NEC. */
+export async function get1099Summary(client, { businessId, year } = {}) {
+  return client.request('/contractors/1099' + q({ business_id: businessId, year }));
+}

package/src/finances-commands.js

@@ -891,10 +891,21 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
         const action = flags.off ? 'off' : args[0] || 'show';
         const describe = (s) => s
           ? `Daily summary ${s.active ? 'on' : 'off'} · ${String(s.hour).padStart(2, '0')}:00 ${s.timezone} · to ${s.recipients.join(', ')}${s.nextRunAt ? ` · next ${s.nextRunAt}` : ''}${s.lastSentAt ? ` · last ${s.lastSentAt}` : ''}`
-          : 'No daily summary configured. Turn it on with: coinpay finances daily on --hour 7 --to you@example.com';
+          : 'No daily summary configured. Turn it on with: coinpay finances daily on --hour 7';
+        const targetText = (t) => (t === null || t === undefined ? 'no daily spend target' : `target $${t}/day`);
+        if (flags.target !== undefined) {
+          const raw = String(flags.target);
+          const target = ['off', 'clear', 'none'].includes(raw) ? null : Number(raw.replace(/^\$/, ''));
+          if (target !== null && (!Number.isFinite(target) || target < 0)) throw new CliExit(EXIT.INVALID, 'The target is a daily amount, e.g. --target 100, or --target clear');
+          const data = await api.setDailySpendTarget(client, target);
+          if (action === 'show') {
+            emit({ schedule: data.schedule, target: data.target }, `${describe(data.schedule)}\n${target === null ? 'Cleared the daily spend target.' : `Daily spend target set to $${data.target}/day.`}`);
+            return EXIT.OK;
+          }
+        }
         if (action === 'show') {
-          const s = await api.getDailySummary(client);
-          emit({ schedule: s }, describe(s));
+          const { schedule: s, target } = await api.getDailySummaryWithTarget(client);
+          emit({ schedule: s, target }, `${describe(s)} · ${targetText(target)}`);
           return EXIT.OK;
         }
         if (action === 'on' || action === 'set') {
@@ -917,7 +928,7 @@ export async function runFinancesCommand(subcommand, args, flags, ctx) {
           emit(data, `Sent to ${data.sent.join(', ') || 'nobody'} (${data.due} due, ${data.overdue} overdue)${data.failed.length ? `; failed: ${data.failed.map((f) => `${f.to} (${f.error})`).join(', ')}` : ''}`);
           return data.sent.length > 0 ? EXIT.OK : EXIT.FAILURE;
         }
-        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances daily [show|on --hour 7 --to a@x|off|send-now]');
+        throw new CliExit(EXIT.INVALID, 'Usage: coinpay finances daily [show|on --hour 7 --to a@x|off|send-now] [--target 100|--target clear]');
       }
 
       case 'payloads': {

package/src/finances-reports.js

@@ -461,6 +461,12 @@ export async function getDailySummary(client) {
   return data.schedule;
 }
 
+/** The daily summary schedule plus the owner's $/day spend target (null when none). */
+export async function getDailySummaryWithTarget(client) {
+  const data = await call(client, '/finances/email-schedules?kind=daily_summary');
+  return { schedule: data.schedule, target: data.dailySpendTarget ?? null };
+}
+
 export async function setDailySummary(client, { weekdays, hour, timezone, recipients, active } = {}) {
   const data = await call(client, '/finances/email-schedules', {
     method: 'POST',
@@ -469,6 +475,15 @@ export async function setDailySummary(client, { weekdays, hour, timezone, recipi
   return data.schedule;
 }
 
+/** Set the daily summary's $/day spend target, or clear it with null. Does not turn the summary on. */
+export async function setDailySpendTarget(client, target) {
+  const data = await call(client, '/finances/email-schedules', {
+    method: 'POST',
+    body: JSON.stringify({ kind: 'daily_summary', target }),
+  });
+  return { schedule: data.schedule, target: data.dailySpendTarget ?? null };
+}
+
 export async function deleteDailySummary(client) {
   return call(client, '/finances/email-schedules?kind=daily_summary', { method: 'DELETE' });
 }

package/src/index.d.ts

@@ -93,6 +93,27 @@ export {
   invoiceProjectTime,
 } from './projects.js';
 export type { ArAging, AgingRow, InvoiceSettings, Project, ProjectStats, TimeEntry } from './projects.js';
+export {
+  listContractors,
+  getContractor,
+  addContractor,
+  createContractorPortalLink,
+  offboardContractor,
+  createContract,
+  sendContract,
+  endContract,
+  listWorkItems,
+  reviewWorkItem,
+  addContractorPayment,
+  listPayRuns,
+  getPayRun,
+  createPayRun,
+  deletePayRun,
+  payPayRun,
+  recordPayRunPayments,
+  get1099Summary,
+} from './contractors.js';
+export type { Contractor, ContractorContract, ContractorMilestone, ContractorWorkItem, PayRun, PayRunItem, PayOutcome } from './contractors.js';
 
 // Webhook exports
 export {

package/src/index.js

@@ -107,6 +107,27 @@ import {
   invoiceProjectTime,
 } from './projects.js';
 
+import {
+  listContractors,
+  getContractor,
+  addContractor,
+  createContractorPortalLink,
+  offboardContractor,
+  createContract,
+  sendContract,
+  endContract,
+  listWorkItems,
+  reviewWorkItem,
+  addContractorPayment,
+  listPayRuns,
+  getPayRun,
+  createPayRun,
+  deletePayRun,
+  payPayRun,
+  recordPayRunPayments,
+  get1099Summary,
+} from './contractors.js';
+
 // Wallet exports
 import {
   WalletClient,
@@ -273,6 +294,24 @@ export {
   stopTimer,
   listTimeEntries,
   invoiceProjectTime,
+  listContractors,
+  getContractor,
+  addContractor,
+  createContractorPortalLink,
+  offboardContractor,
+  createContract,
+  sendContract,
+  endContract,
+  listWorkItems,
+  reviewWorkItem,
+  addContractorPayment,
+  listPayRuns,
+  getPayRun,
+  createPayRun,
+  deletePayRun,
+  payPayRun,
+  recordPayRunPayments,
+  get1099Summary,
   
   // Wallet
   WalletClient,

package/src/mcp.js

@@ -17,6 +17,7 @@ import { getFinanceSummary, listFinanceAccounts, listFinanceTransactions } from
 import * as sf from './statements-fetch.js';
 import { listInvoices, getInvoice, createInvoice } from './invoices.js';
 import * as projects from './projects.js';
+import * as contractors from './contractors.js';
 
 export const PROTOCOL_VERSION = '2025-06-18';
 
@@ -94,13 +95,14 @@ export const TOOLS = [
   },
   {
     name: 'finance_daily_summary',
-    description: 'The daily summary email (due soon, new activity, position): show it, turn it on (optionally hour 0-23 and recipients), turn it off, or send one now.',
+    description: 'The daily summary email (spend vs a $/day target, top cuts, due soon, new activity, position): show it, turn it on (optionally hour 0-23 and recipients), turn it off, send one now, or set_target (target in $/day, null clears).',
     inputSchema: {
       type: 'object',
       properties: {
-        action: { type: 'string', enum: ['show', 'on', 'off', 'send_now'] },
+        action: { type: 'string', enum: ['show', 'on', 'off', 'send_now', 'set_target'] },
         hour: { type: 'integer', minimum: 0, maximum: 23 },
         to: { type: 'array', items: { type: 'string' }, maxItems: 5 },
+        target: { type: ['number', 'null'], minimum: 0 },
       },
       required: ['action'],
       additionalProperties: false,
@@ -109,7 +111,8 @@ export const TOOLS = [
       if (args.action === 'on') return text({ schedule: await reports.setDailySummary(client, { hour: args.hour, recipients: args.to, active: true }) });
       if (args.action === 'off') return text(await reports.deleteDailySummary(client));
       if (args.action === 'send_now') return text(await reports.sendDailySummaryNow(client));
-      return text({ schedule: await reports.getDailySummary(client) });
+      if (args.action === 'set_target') return text(await reports.setDailySpendTarget(client, args.target ?? null));
+      return text(await reports.getDailySummaryWithTarget(client));
     },
   },
   {
@@ -321,6 +324,68 @@ export const TOOLS = [
     inputSchema: { type: 'object', properties: { projectId: { type: 'string' } }, required: ['projectId'], additionalProperties: false },
     handler: async (args, { client }) => text(await projects.invoiceProjectTime(client, args.projectId)),
   },
+  // Contractors. None of these sends money: paying a run is a signed-in owner's act in the dashboard or CLI.
+  {
+    name: 'contractor_list',
+    description: 'List contractors with wallet and tax-form status and how many submissions wait for approval.',
+    inputSchema: { type: 'object', properties: { businessId: { type: 'string' }, includeOffboarded: { type: 'boolean' } }, additionalProperties: false },
+    handler: async (args, { client }) => text({ contractors: await contractors.listContractors(client, args) }),
+  },
+  {
+    name: 'contractor_get',
+    description: 'One contractor: contracts and milestones, work lines and payments.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false },
+    handler: async (args, { client }) => text(await contractors.getContractor(client, args.id)),
+  },
+  {
+    name: 'contractor_work_list',
+    description: 'Contractor work lines (hours, milestones, expenses, bonuses, fixed fees). Use status "submitted" for what waits for approval.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        businessId: { type: 'string' },
+        status: { type: 'string', enum: ['submitted', 'approved', 'rejected', 'paid'] },
+        contractorId: { type: 'string' },
+      },
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text({ work_items: await contractors.listWorkItems(client, args) }),
+  },
+  {
+    name: 'contractor_work_review',
+    description: 'Approve or reject a submitted work line. A rejection needs a note the contractor will see. Approving does not pay; it queues the line for the next pay run.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' }, action: { type: 'string', enum: ['approve', 'reject'] }, note: { type: 'string' } },
+      required: ['id', 'action'],
+      additionalProperties: false,
+    },
+    handler: async (args, { client }) => text({ work_item: await contractors.reviewWorkItem(client, args.id, args) }),
+  },
+  {
+    name: 'pay_run_list',
+    description: 'Pay runs with totals and how many contractors are paid.',
+    inputSchema: { type: 'object', properties: { businessId: { type: 'string' } }, additionalProperties: false },
+    handler: async (args, { client }) => text({ pay_runs: await contractors.listPayRuns(client, args) }),
+  },
+  {
+    name: 'pay_run_get',
+    description: 'One pay run: per-contractor amounts, lines, status and warnings (missing or recently changed wallets).',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'], additionalProperties: false },
+    handler: async (args, { client }) => text(await contractors.getPayRun(client, args.id)),
+  },
+  {
+    name: 'pay_run_draft',
+    description: 'Draft a pay run from fixed fees due by payDate (YYYY-MM-DD, default today) plus all approved work. Sends nothing; the owner reviews and pays it.',
+    inputSchema: { type: 'object', properties: { businessId: { type: 'string' }, payDate: { type: 'string' } }, additionalProperties: false },
+    handler: async (args, { client }) => text({ pay_run: await contractors.createPayRun(client, args) }),
+  },
+  {
+    name: 'contractor_1099_summary',
+    description: 'Totals paid per contractor in a calendar year and who needs a 1099-NEC (US, $600+, not a corporation). Shows only the last four of tax ids.',
+    inputSchema: { type: 'object', properties: { businessId: { type: 'string' }, year: { type: 'integer' } }, additionalProperties: false },
+    handler: async (args, { client }) => text(await contractors.get1099Summary(client, args)),
+  },
 ];
 
 /** Answer one JSON-RPC message; null for a notification. */