@profullstack/coinpay 0.3.9 → 0.3.10

package/bin/coinpay.js

@@ -161,6 +161,15 @@ ${colors.cyan}Commands:${colors.reset}
     backup-seed           Encrypt seed phrase to GPG file
     decrypt-backup <file> Decrypt a GPG backup file
 
+  ${colors.bright}escrow${colors.reset}
+    create                Create a new escrow
+    get <id>              Get escrow status
+    list                  List escrows
+    release <id>          Release funds to beneficiary
+    refund <id>           Refund funds to depositor
+    dispute <id>          Open a dispute
+    events <id>           Get escrow audit log
+
   ${colors.bright}webhook${colors.reset}
     logs <business-id>    Get webhook logs
     test <business-id>    Send test webhook
@@ -732,6 +741,139 @@ async function main() {
     showHelp();
     return;
   }
+
+async function handleEscrow(subcommand, args, flags) {
+  const client = getClient();
+
+  switch (subcommand) {
+    case 'create': {
+      const chain = flags.chain || flags.blockchain;
+      const amount = parseFloat(flags.amount);
+      const depositor = flags.depositor || flags['depositor-address'];
+      const beneficiary = flags.beneficiary || flags['beneficiary-address'];
+
+      if (!chain || !amount || !depositor || !beneficiary) {
+        print.error('Required: --chain, --amount, --depositor, --beneficiary');
+        process.exit(1);
+      }
+
+      print.info(`Creating escrow: ${amount} ${chain}`);
+      print.info(`  Depositor: ${depositor}`);
+      print.info(`  Beneficiary: ${beneficiary}`);
+
+      const escrow = await client.createEscrow({
+        chain,
+        amount,
+        depositorAddress: depositor,
+        beneficiaryAddress: beneficiary,
+        metadata: flags.metadata ? JSON.parse(flags.metadata) : undefined,
+        expiresInHours: flags['expires-in'] ? parseFloat(flags['expires-in']) : undefined,
+      });
+
+      print.success(`Escrow created: ${escrow.id}`);
+      print.info(`  Deposit to: ${escrow.escrowAddress}`);
+      print.info(`  Status: ${escrow.status}`);
+      print.info(`  Expires: ${escrow.expiresAt}`);
+      print.warn(`  Release Token: ${escrow.releaseToken}`);
+      print.warn(`  Beneficiary Token: ${escrow.beneficiaryToken}`);
+      print.warn('  ⚠️  Save these tokens! They cannot be recovered.');
+
+      if (flags.json) console.log(JSON.stringify(escrow, null, 2));
+      break;
+    }
+
+    case 'get': {
+      const id = args[0];
+      if (!id) { print.error('Escrow ID required'); process.exit(1); }
+
+      const escrow = await client.getEscrow(id);
+      print.success(`Escrow ${escrow.id}`);
+      print.info(`  Status: ${escrow.status}`);
+      print.info(`  Chain: ${escrow.chain}`);
+      print.info(`  Amount: ${escrow.amount}`);
+      print.info(`  Escrow Address: ${escrow.escrowAddress}`);
+      print.info(`  Depositor: ${escrow.depositorAddress}`);
+      print.info(`  Beneficiary: ${escrow.beneficiaryAddress}`);
+      if (escrow.depositedAmount) print.info(`  Deposited: ${escrow.depositedAmount}`);
+      if (escrow.depositTxHash) print.info(`  Deposit TX: ${escrow.depositTxHash}`);
+      if (escrow.settlementTxHash) print.info(`  Settlement TX: ${escrow.settlementTxHash}`);
+
+      if (flags.json) console.log(JSON.stringify(escrow, null, 2));
+      break;
+    }
+
+    case 'list': {
+      const result = await client.listEscrows({
+        status: flags.status,
+        depositor: flags.depositor,
+        beneficiary: flags.beneficiary,
+        limit: flags.limit ? parseInt(flags.limit) : 20,
+      });
+
+      print.info(`Escrows (${result.total} total):`);
+      for (const e of result.escrows) {
+        console.log(`  ${e.id} | ${e.status} | ${e.amount} ${e.chain} | ${e.createdAt}`);
+      }
+
+      if (flags.json) console.log(JSON.stringify(result, null, 2));
+      break;
+    }
+
+    case 'release': {
+      const id = args[0];
+      const token = flags.token || flags['release-token'];
+      if (!id || !token) { print.error('Required: <id> --token <release_token>'); process.exit(1); }
+
+      const escrow = await client.releaseEscrow(id, token);
+      print.success(`Escrow ${id} released → ${escrow.beneficiaryAddress}`);
+      break;
+    }
+
+    case 'refund': {
+      const id = args[0];
+      const token = flags.token || flags['release-token'];
+      if (!id || !token) { print.error('Required: <id> --token <release_token>'); process.exit(1); }
+
+      const escrow = await client.refundEscrow(id, token);
+      print.success(`Escrow ${id} refunded → ${escrow.depositorAddress}`);
+      break;
+    }
+
+    case 'dispute': {
+      const id = args[0];
+      const token = flags.token || flags['release-token'] || flags['beneficiary-token'];
+      const reason = flags.reason;
+      if (!id || !token || !reason) {
+        print.error('Required: <id> --token <token> --reason "description"');
+        process.exit(1);
+      }
+
+      const escrow = await client.disputeEscrow(id, token, reason);
+      print.success(`Escrow ${id} disputed`);
+      print.info(`  Reason: ${escrow.disputeReason}`);
+      break;
+    }
+
+    case 'events': {
+      const id = args[0];
+      if (!id) { print.error('Escrow ID required'); process.exit(1); }
+
+      const events = await client.getEscrowEvents(id);
+      print.info(`Events for escrow ${id}:`);
+      for (const e of events) {
+        console.log(`  ${e.createdAt} | ${e.eventType} | ${e.actor || 'system'}`);
+      }
+
+      if (flags.json) console.log(JSON.stringify(events, null, 2));
+      break;
+    }
+
+    default:
+      print.error(`Unknown escrow command: ${subcommand}`);
+      print.info('Available: create, get, list, release, refund, dispute, events');
+      process.exit(1);
+  }
+}
   
   try {
     switch (command) {
@@ -751,6 +893,10 @@ async function main() {
         await handleRates(subcommand, args, flags);
         break;
         
+      case 'escrow':
+        await handleEscrow(subcommand, args, flags);
+        break;
+
       case 'webhook':
         await handleWebhook(subcommand, args, flags);
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "CoinPay SDK & CLI — Accept cryptocurrency payments (BTC, ETH, SOL, POL, BCH, USDC) in your Node.js application",
   "type": "module",
   "main": "./src/index.js",

package/src/client.js

@@ -396,6 +396,93 @@ export class CoinPayClient {
       }),
     });
   }
+
+  // ── Escrow Methods ──────────────────────────────────────
+
+  /**
+   * Create a new escrow
+   * @param {Object} params - See escrow.js createEscrow for full params
+   * @returns {Promise<Object>} Created escrow with releaseToken
+   */
+  async createEscrow(params) {
+    const { createEscrow } = await import('./escrow.js');
+    return createEscrow(this, params);
+  }
+
+  /**
+   * Get escrow status
+   * @param {string} escrowId
+   * @returns {Promise<Object>}
+   */
+  async getEscrow(escrowId) {
+    const { getEscrow } = await import('./escrow.js');
+    return getEscrow(this, escrowId);
+  }
+
+  /**
+   * List escrows with filters
+   * @param {Object} [filters]
+   * @returns {Promise<Object>}
+   */
+  async listEscrows(filters) {
+    const { listEscrows } = await import('./escrow.js');
+    return listEscrows(this, filters);
+  }
+
+  /**
+   * Release escrow funds to beneficiary
+   * @param {string} escrowId
+   * @param {string} releaseToken
+   * @returns {Promise<Object>}
+   */
+  async releaseEscrow(escrowId, releaseToken) {
+    const { releaseEscrow } = await import('./escrow.js');
+    return releaseEscrow(this, escrowId, releaseToken);
+  }
+
+  /**
+   * Refund escrow to depositor
+   * @param {string} escrowId
+   * @param {string} releaseToken
+   * @returns {Promise<Object>}
+   */
+  async refundEscrow(escrowId, releaseToken) {
+    const { refundEscrow } = await import('./escrow.js');
+    return refundEscrow(this, escrowId, releaseToken);
+  }
+
+  /**
+   * Dispute an escrow
+   * @param {string} escrowId
+   * @param {string} token - release_token or beneficiary_token
+   * @param {string} reason - At least 10 characters
+   * @returns {Promise<Object>}
+   */
+  async disputeEscrow(escrowId, token, reason) {
+    const { disputeEscrow } = await import('./escrow.js');
+    return disputeEscrow(this, escrowId, token, reason);
+  }
+
+  /**
+   * Get escrow audit log
+   * @param {string} escrowId
+   * @returns {Promise<Array>}
+   */
+  async getEscrowEvents(escrowId) {
+    const { getEscrowEvents } = await import('./escrow.js');
+    return getEscrowEvents(this, escrowId);
+  }
+
+  /**
+   * Poll escrow until target status
+   * @param {string} escrowId
+   * @param {Object} [options] - { targetStatus, intervalMs, timeoutMs }
+   * @returns {Promise<Object>}
+   */
+  async waitForEscrow(escrowId, options) {
+    const { waitForEscrow } = await import('./escrow.js');
+    return waitForEscrow(this, escrowId, options);
+  }
 }
 
 export default CoinPayClient;

package/src/escrow.js

@@ -0,0 +1,245 @@
+/**
+ * Escrow SDK Module
+ *
+ * Anonymous, non-custodial escrow for crypto payments.
+ * Both humans and AI agents can create/fund/release/dispute escrows.
+ *
+ * @example
+ * import { CoinPayClient } from '@profullstack/coinpay';
+ *
+ * const client = new CoinPayClient({ apiKey: 'your-key' });
+ *
+ * // Create escrow
+ * const escrow = await client.createEscrow({
+ *   chain: 'SOL',
+ *   amount: 0.5,
+ *   depositorAddress: 'depositor-wallet',
+ *   beneficiaryAddress: 'worker-wallet',
+ *   metadata: { job: 'Code review', deadline: '2026-02-10' }
+ * });
+ * // Save escrow.releaseToken — needed to release/refund
+ *
+ * // Check status
+ * const status = await client.getEscrow(escrow.id);
+ *
+ * // Release funds to worker
+ * await client.releaseEscrow(escrow.id, escrow.releaseToken);
+ */
+
+/**
+ * Create a new escrow
+ * @param {CoinPayClient} client - API client instance
+ * @param {Object} params - Escrow parameters
+ * @param {string} params.chain - Blockchain (BTC, ETH, SOL, POL, etc.)
+ * @param {number} params.amount - Crypto amount to escrow
+ * @param {string} params.depositorAddress - Wallet address for refunds
+ * @param {string} params.beneficiaryAddress - Wallet address for releases
+ * @param {string} [params.arbiterAddress] - Optional dispute resolver address
+ * @param {Object} [params.metadata] - Job details, milestones, etc.
+ * @param {number} [params.expiresInHours] - Deposit window (default: 24h)
+ * @returns {Promise<Object>} Created escrow with releaseToken and beneficiaryToken
+ */
+export async function createEscrow(client, {
+  chain,
+  amount,
+  depositorAddress,
+  beneficiaryAddress,
+  arbiterAddress,
+  metadata,
+  expiresInHours,
+}) {
+  const body = {
+    chain,
+    amount,
+    depositor_address: depositorAddress,
+    beneficiary_address: beneficiaryAddress,
+  };
+  if (arbiterAddress) body.arbiter_address = arbiterAddress;
+  if (metadata) body.metadata = metadata;
+  if (expiresInHours) body.expires_in_hours = expiresInHours;
+
+  const data = await client.request('/escrow', {
+    method: 'POST',
+    body: JSON.stringify(body),
+  });
+
+  return {
+    id: data.id,
+    escrowAddress: data.escrow_address,
+    chain: data.chain,
+    amount: data.amount,
+    amountUsd: data.amount_usd,
+    status: data.status,
+    depositorAddress: data.depositor_address,
+    beneficiaryAddress: data.beneficiary_address,
+    releaseToken: data.release_token,
+    beneficiaryToken: data.beneficiary_token,
+    metadata: data.metadata,
+    expiresAt: data.expires_at,
+    createdAt: data.created_at,
+  };
+}
+
+/**
+ * Get escrow status
+ * @param {CoinPayClient} client
+ * @param {string} escrowId
+ * @returns {Promise<Object>} Escrow status (public view, no tokens)
+ */
+export async function getEscrow(client, escrowId) {
+  const data = await client.request(`/escrow/${escrowId}`);
+  return normalizeEscrow(data);
+}
+
+/**
+ * List escrows with filters
+ * @param {CoinPayClient} client
+ * @param {Object} [filters]
+ * @param {string} [filters.status] - Filter by status
+ * @param {string} [filters.depositor] - Filter by depositor address
+ * @param {string} [filters.beneficiary] - Filter by beneficiary address
+ * @param {number} [filters.limit] - Results per page (default: 20)
+ * @param {number} [filters.offset] - Offset for pagination
+ * @returns {Promise<Object>} { escrows, total, limit, offset }
+ */
+export async function listEscrows(client, filters = {}) {
+  const params = new URLSearchParams();
+  if (filters.status) params.set('status', filters.status);
+  if (filters.depositor) params.set('depositor', filters.depositor);
+  if (filters.beneficiary) params.set('beneficiary', filters.beneficiary);
+  if (filters.limit) params.set('limit', String(filters.limit));
+  if (filters.offset) params.set('offset', String(filters.offset));
+
+  const data = await client.request(`/escrow?${params.toString()}`);
+  return {
+    escrows: (data.escrows || []).map(normalizeEscrow),
+    total: data.total,
+    limit: data.limit,
+    offset: data.offset,
+  };
+}
+
+/**
+ * Release escrow funds to beneficiary
+ * @param {CoinPayClient} client
+ * @param {string} escrowId
+ * @param {string} releaseToken - Secret token from escrow creation
+ * @returns {Promise<Object>} Updated escrow
+ */
+export async function releaseEscrow(client, escrowId, releaseToken) {
+  const data = await client.request(`/escrow/${escrowId}/release`, {
+    method: 'POST',
+    body: JSON.stringify({ release_token: releaseToken }),
+  });
+  return normalizeEscrow(data);
+}
+
+/**
+ * Refund escrow to depositor
+ * @param {CoinPayClient} client
+ * @param {string} escrowId
+ * @param {string} releaseToken
+ * @returns {Promise<Object>} Updated escrow
+ */
+export async function refundEscrow(client, escrowId, releaseToken) {
+  const data = await client.request(`/escrow/${escrowId}/refund`, {
+    method: 'POST',
+    body: JSON.stringify({ release_token: releaseToken }),
+  });
+  return normalizeEscrow(data);
+}
+
+/**
+ * Dispute an escrow
+ * @param {CoinPayClient} client
+ * @param {string} escrowId
+ * @param {string} token - release_token or beneficiary_token
+ * @param {string} reason - Dispute reason (min 10 chars)
+ * @returns {Promise<Object>} Updated escrow
+ */
+export async function disputeEscrow(client, escrowId, token, reason) {
+  const data = await client.request(`/escrow/${escrowId}/dispute`, {
+    method: 'POST',
+    body: JSON.stringify({ token, reason }),
+  });
+  return normalizeEscrow(data);
+}
+
+/**
+ * Get escrow event log
+ * @param {CoinPayClient} client
+ * @param {string} escrowId
+ * @returns {Promise<Array>} Array of events
+ */
+export async function getEscrowEvents(client, escrowId) {
+  const data = await client.request(`/escrow/${escrowId}/events`);
+  return (data.events || []).map(e => ({
+    id: e.id,
+    escrowId: e.escrow_id,
+    eventType: e.event_type,
+    actor: e.actor,
+    details: e.details,
+    createdAt: e.created_at,
+  }));
+}
+
+/**
+ * Poll escrow until it reaches a target status
+ * @param {CoinPayClient} client
+ * @param {string} escrowId
+ * @param {Object} [options]
+ * @param {string} [options.targetStatus] - Status to wait for (default: 'funded')
+ * @param {number} [options.intervalMs] - Poll interval (default: 10000)
+ * @param {number} [options.timeoutMs] - Max wait time (default: 3600000 = 1h)
+ * @returns {Promise<Object>} Escrow when target status reached
+ */
+export async function waitForEscrow(client, escrowId, options = {}) {
+  const {
+    targetStatus = 'funded',
+    intervalMs = 10000,
+    timeoutMs = 3600000,
+  } = options;
+
+  const start = Date.now();
+
+  while (Date.now() - start < timeoutMs) {
+    const escrow = await getEscrow(client, escrowId);
+
+    if (escrow.status === targetStatus) return escrow;
+    if (['settled', 'refunded', 'expired'].includes(escrow.status)) return escrow;
+
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
+  }
+
+  throw new Error(`Escrow ${escrowId} did not reach status '${targetStatus}' within ${timeoutMs}ms`);
+}
+
+// ── Helpers ──
+
+function normalizeEscrow(data) {
+  return {
+    id: data.id,
+    escrowAddress: data.escrow_address,
+    chain: data.chain,
+    amount: data.amount,
+    amountUsd: data.amount_usd,
+    feeAmount: data.fee_amount,
+    depositedAmount: data.deposited_amount,
+    status: data.status,
+    depositorAddress: data.depositor_address,
+    beneficiaryAddress: data.beneficiary_address,
+    arbiterAddress: data.arbiter_address,
+    depositTxHash: data.deposit_tx_hash,
+    settlementTxHash: data.settlement_tx_hash,
+    metadata: data.metadata,
+    disputeReason: data.dispute_reason,
+    disputeResolution: data.dispute_resolution,
+    createdAt: data.created_at,
+    fundedAt: data.funded_at,
+    releasedAt: data.released_at,
+    settledAt: data.settled_at,
+    disputedAt: data.disputed_at,
+    refundedAt: data.refunded_at,
+    expiresAt: data.expires_at,
+  };
+}

package/src/index.js

@@ -36,6 +36,17 @@ import {
   WebhookEvent,
 } from './webhooks.js';
 
+import {
+  createEscrow,
+  getEscrow,
+  listEscrows,
+  releaseEscrow,
+  refundEscrow,
+  disputeEscrow,
+  getEscrowEvents,
+  waitForEscrow,
+} from './escrow.js';
+
 export {
   // Client
   CoinPayClient,
@@ -45,6 +56,16 @@ export {
   getPayment,
   listPayments,
   
+  // Escrow functions
+  createEscrow,
+  getEscrow,
+  listEscrows,
+  releaseEscrow,
+  refundEscrow,
+  disputeEscrow,
+  getEscrowEvents,
+  waitForEscrow,
+  
   // Constants
   Blockchain,
   Cryptocurrency,  // Deprecated, use Blockchain