@profullstack/coinpay 0.3.9 → 0.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.3.9",
-  "description": "CoinPay SDK & CLI — Accept cryptocurrency payments (BTC, ETH, SOL, POL, BCH, USDC) in your Node.js application",
+  "version": "0.4.0",
+  "description": "CoinPay SDK & CLI — Accept cryptocurrency payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet and swap support",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -20,6 +20,14 @@
     "./webhooks": {
       "import": "./src/webhooks.js",
       "types": "./src/webhooks.d.ts"
+    },
+    "./wallet": {
+      "import": "./src/wallet.js",
+      "types": "./src/wallet.d.ts"
+    },
+    "./swap": {
+      "import": "./src/swap.js",
+      "types": "./src/swap.d.ts"
     }
   },
   "files": [
@@ -49,12 +57,16 @@
     "stablecoin",
     "non-custodial",
     "wallet",
+    "swap",
+    "exchange",
     "sdk",
     "cli",
     "web3",
     "blockchain",
     "payment-gateway",
-    "merchant"
+    "merchant",
+    "bip39",
+    "mnemonic"
   ],
   "author": "Profullstack, Inc.",
   "license": "MIT",
@@ -76,5 +88,10 @@
     "prettier": "^3.4.1"
   },
   "peerDependencies": {},
-  "dependencies": {}
+  "dependencies": {
+    "@scure/bip39": "^1.4.0",
+    "@scure/bip32": "^1.5.0",
+    "@noble/curves": "^1.6.0",
+    "@noble/hashes": "^1.5.0"
+  }
 }

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.d.ts

@@ -5,9 +5,17 @@
  * @module @profullstack/coinpay
  */
 
+// Client exports
 export { CoinPayClient } from './client.js';
-export type { CoinPayClientOptions, PaymentParams, ListPaymentsParams, WaitForPaymentOptions, CreateBusinessParams } from './client.js';
+export type { 
+  CoinPayClientOptions, 
+  PaymentParams, 
+  ListPaymentsParams, 
+  WaitForPaymentOptions, 
+  CreateBusinessParams 
+} from './client.js';
 
+// Payment exports
 export {
   createPayment,
   getPayment,
@@ -17,8 +25,13 @@ export {
   PaymentStatus,
   FiatCurrency,
 } from './payments.js';
-export type { CreatePaymentParams, GetPaymentParams, ListPaymentsFnParams } from './payments.js';
+export type { 
+  CreatePaymentParams, 
+  GetPaymentParams, 
+  ListPaymentsFnParams 
+} from './payments.js';
 
+// Webhook exports
 export {
   verifyWebhookSignature,
   generateWebhookSignature,
@@ -33,5 +46,55 @@ export type {
   ParsedWebhookEvent,
 } from './webhooks.js';
 
+// Wallet exports
+export {
+  WalletClient,
+  WalletChain,
+  DEFAULT_CHAINS,
+  generateMnemonic,
+  validateMnemonic,
+  getDerivationPath,
+  restoreFromBackup,
+} from './wallet.js';
+export type {
+  WalletChainType,
+  WalletCreateOptions,
+  WalletImportOptions,
+  WalletAddress,
+  AddressListResult,
+  WalletBalance,
+  SendOptions,
+  HistoryOptions,
+  Transaction,
+  FeeEstimate,
+} from './wallet.js';
+
+// Swap exports
+export {
+  SwapClient,
+  SwapCoins,
+  SwapStatus,
+  getSwapCoins,
+  getSwapQuote,
+  createSwap,
+  getSwapStatus,
+  getSwapHistory,
+} from './swap.js';
+export type {
+  SwapStatusType,
+  SwapClientOptions,
+  CoinInfo,
+  CoinsResult,
+  SwapQuote,
+  QuoteResult,
+  CreateSwapParams,
+  Swap,
+  SwapResult,
+  WaitForSwapOptions,
+  SwapHistoryOptions,
+  SwapHistoryPagination,
+  SwapHistoryResult,
+} from './swap.js';
+
 import { CoinPayClient } from './client.js';
 export default CoinPayClient;

package/src/index.js

@@ -16,6 +16,24 @@
  *   blockchain: Blockchain.BTC,
  *   description: 'Order #12345'
  * });
+ *
+ * @example
+ * // Wallet usage
+ * import { WalletClient } from '@profullstack/coinpay';
+ *
+ * // Create a new wallet
+ * const wallet = await WalletClient.create({ words: 12, chains: ['BTC', 'ETH'] });
+ * console.log('Backup your seed:', wallet.getMnemonic());
+ *
+ * // Or import existing
+ * const wallet = await WalletClient.fromSeed('your twelve word mnemonic phrase ...');
+ *
+ * @example
+ * // Swap usage
+ * import { SwapClient } from '@profullstack/coinpay';
+ *
+ * const swap = new SwapClient({ walletId: 'your-wallet-id' });
+ * const quote = await swap.getSwapQuote('BTC', 'ETH', 0.1);
  */
 
 import { CoinPayClient } from './client.js';
@@ -36,6 +54,40 @@ import {
   WebhookEvent,
 } from './webhooks.js';
 
+import {
+  createEscrow,
+  getEscrow,
+  listEscrows,
+  releaseEscrow,
+  refundEscrow,
+  disputeEscrow,
+  getEscrowEvents,
+  waitForEscrow,
+} from './escrow.js';
+
+// Wallet exports
+import {
+  WalletClient,
+  WalletChain,
+  DEFAULT_CHAINS,
+  generateMnemonic,
+  validateMnemonic,
+  getDerivationPath,
+  restoreFromBackup,
+} from './wallet.js';
+
+// Swap exports
+import {
+  SwapClient,
+  SwapCoins,
+  SwapStatus,
+  getSwapCoins,
+  getSwapQuote,
+  createSwap,
+  getSwapStatus,
+  getSwapHistory,
+} from './swap.js';
+
 export {
   // Client
   CoinPayClient,
@@ -45,6 +97,35 @@ export {
   getPayment,
   listPayments,
   
+  // Escrow functions
+  createEscrow,
+  getEscrow,
+  listEscrows,
+  releaseEscrow,
+  refundEscrow,
+  disputeEscrow,
+  getEscrowEvents,
+  waitForEscrow,
+  
+  // Wallet
+  WalletClient,
+  WalletChain,
+  DEFAULT_CHAINS,
+  generateMnemonic,
+  validateMnemonic,
+  getDerivationPath,
+  restoreFromBackup,
+  
+  // Swap
+  SwapClient,
+  SwapCoins,
+  SwapStatus,
+  getSwapCoins,
+  getSwapQuote,
+  createSwap,
+  getSwapStatus,
+  getSwapHistory,
+  
   // Constants
   Blockchain,
   Cryptocurrency,  // Deprecated, use Blockchain
@@ -59,4 +140,4 @@ export {
   WebhookEvent,
 };
 
-export default CoinPayClient;
+export default CoinPayClient;