@profullstack/coinpay 0.6.5 → 0.6.7

package/bin/coinpay.js

@@ -208,6 +208,11 @@ ${colors.cyan}Commands:${colors.reset}
     status <swap-id>      Check swap status
     history               Swap history
 
+  ${colors.bright}payout${colors.reset}
+    create                Create a payout to your Stripe account
+    list                  List payouts
+    get <id>              Get payout details
+
   ${colors.bright}card${colors.reset}
     create                Create a card payment via Stripe
     get <id>              Get card payment status
@@ -1593,9 +1598,119 @@ async function handleEscrow(subcommand, args, flags) {
       break;
     }
 
+    case 'series': {
+      const seriesCmd = args[0];
+      const seriesId = args[1];
+
+      switch (seriesCmd) {
+        case 'create': {
+          const rl = createInterface({ input: process.stdin, output: process.stdout });
+          const ask = (q) => new Promise((r) => rl.question(q, r));
+
+          try {
+            const businessId = flags['business-id'] || await ask('Business ID: ');
+            const paymentMethod = flags['payment-method'] || await ask('Payment method (crypto/card): ');
+            const amount = flags.amount || await ask('Amount (cents for card, satoshis-equiv for crypto): ');
+            const currency = flags.currency || await ask('Currency [USD]: ') || 'USD';
+            const interval = flags.interval || await ask('Interval (weekly/biweekly/monthly): ');
+            const maxPeriods = flags['max-periods'] || await ask('Max periods (blank=infinite): ') || undefined;
+            const customerEmail = flags.email || await ask('Customer email (optional): ') || undefined;
+            const description = flags.description || await ask('Description (optional): ') || undefined;
+
+            const params = {
+              business_id: businessId,
+              payment_method: paymentMethod,
+              amount: parseInt(amount),
+              currency,
+              interval,
+              max_periods: maxPeriods ? parseInt(maxPeriods) : undefined,
+              customer_email: customerEmail,
+              description,
+            };
+
+            if (paymentMethod === 'crypto') {
+              params.coin = flags.coin || await ask('Coin (BTC/ETH/SOL/etc): ');
+              params.beneficiary_address = flags.beneficiary || await ask('Beneficiary address: ');
+              params.depositor_address = flags.depositor || await ask('Depositor address: ');
+            } else {
+              params.stripe_account_id = flags['stripe-account'] || await ask('Stripe account ID: ');
+            }
+
+            rl.close();
+
+            const series = await client.createEscrowSeries(params);
+            print.success(`Escrow series created: ${series.id}`);
+            print.info(`  Status: ${series.status}`);
+            print.info(`  Interval: ${series.interval}`);
+            print.info(`  Amount: ${series.amount} ${series.currency}`);
+            if (flags.json) print.json(series);
+          } catch (e) {
+            rl.close();
+            throw e;
+          }
+          break;
+        }
+
+        case 'list': {
+          const businessId = flags['business-id'];
+          if (!businessId) { print.error('--business-id required'); process.exit(1); }
+          const result = await client.listEscrowSeries(businessId, flags.status);
+          print.info(`Series (${result.series.length}):`);
+          for (const s of result.series) {
+            console.log(`  ${s.id} | ${s.status} | ${s.payment_method} | ${s.interval} | ${s.amount} ${s.currency}`);
+          }
+          if (flags.json) print.json(result);
+          break;
+        }
+
+        case 'get': {
+          if (!seriesId) { print.error('Series ID required'); process.exit(1); }
+          const result = await client.getEscrowSeries(seriesId);
+          print.success(`Series ${result.series.id}`);
+          print.info(`  Status: ${result.series.status}`);
+          print.info(`  Method: ${result.series.payment_method}`);
+          print.info(`  Amount: ${result.series.amount} ${result.series.currency}`);
+          print.info(`  Interval: ${result.series.interval}`);
+          print.info(`  Periods: ${result.series.periods_completed}${result.series.max_periods ? '/' + result.series.max_periods : ''}`);
+          print.info(`  Next charge: ${result.series.next_charge_at}`);
+          print.info(`  Crypto escrows: ${result.escrows.crypto.length}`);
+          print.info(`  Stripe escrows: ${result.escrows.stripe.length}`);
+          if (flags.json) print.json(result);
+          break;
+        }
+
+        case 'pause': {
+          if (!seriesId) { print.error('Series ID required'); process.exit(1); }
+          await client.updateEscrowSeries(seriesId, { status: 'paused' });
+          print.success(`Series ${seriesId} paused`);
+          break;
+        }
+
+        case 'resume': {
+          if (!seriesId) { print.error('Series ID required'); process.exit(1); }
+          await client.updateEscrowSeries(seriesId, { status: 'active' });
+          print.success(`Series ${seriesId} resumed`);
+          break;
+        }
+
+        case 'cancel': {
+          if (!seriesId) { print.error('Series ID required'); process.exit(1); }
+          await client.cancelEscrowSeries(seriesId);
+          print.success(`Series ${seriesId} cancelled`);
+          break;
+        }
+
+        default:
+          print.error(`Unknown series command: ${seriesCmd}`);
+          print.info('Available: create, list, get, pause, resume, cancel');
+          process.exit(1);
+      }
+      break;
+    }
+
     default:
       print.error(`Unknown escrow command: ${subcommand}`);
-      print.info('Available: create, get, list, release, refund, dispute, events, auth');
+      print.info('Available: create, get, list, release, refund, dispute, events, auth, series');
       process.exit(1);
   }
 }
@@ -2003,6 +2118,74 @@ async function handleReputation(subcommand, args, flags) {
   }
 }
 
+/**
+ * Payout commands
+ */
+async function handlePayout(subcommand, args, flags) {
+  const client = createClient();
+
+  switch (subcommand) {
+    case 'create': {
+      const amount = parseInt(flags.amount);
+      if (!amount || amount <= 0) {
+        print.error('--amount is required (in cents, e.g., 5000 for $50.00)');
+        print.info('Example: coinpay payout create --amount 5000 --description "Weekly payout"');
+        process.exit(1);
+      }
+
+      const result = await client.createPayout({
+        amount,
+        currency: flags.currency || 'usd',
+        description: flags.description,
+        metadata: flags.metadata ? JSON.parse(flags.metadata) : undefined,
+      });
+
+      print.success('Payout created');
+      print.json(result);
+      break;
+    }
+
+    case 'list': {
+      const result = await client.listPayouts({
+        status: flags.status,
+        dateFrom: flags['date-from'] || flags.dateFrom,
+        dateTo: flags['date-to'] || flags.dateTo,
+        limit: flags.limit ? parseInt(flags.limit) : undefined,
+        offset: flags.offset ? parseInt(flags.offset) : undefined,
+      });
+
+      if (result.payouts && result.payouts.length > 0) {
+        console.log(`\n${colors.bright}Payouts${colors.reset} (${result.pagination?.total || result.payouts.length} total)\n`);
+        for (const p of result.payouts) {
+          const statusColor = p.status === 'paid' ? colors.green : p.status === 'failed' ? colors.red : colors.yellow;
+          console.log(`  ${p.id}  ${statusColor}${p.status}${colors.reset}  $${p.amount_usd || ((p.amount_cents || 0) / 100).toFixed(2)}  ${new Date(p.created_at).toLocaleDateString()}`);
+        }
+        console.log();
+      } else {
+        print.info('No payouts found');
+      }
+      break;
+    }
+
+    case 'get': {
+      const id = args[0];
+      if (!id) {
+        print.error('Usage: coinpay payout get <id>');
+        process.exit(1);
+      }
+
+      const result = await client.getPayout(id);
+      print.json(result);
+      break;
+    }
+
+    default:
+      print.error(`Unknown payout command: ${subcommand}`);
+      print.info('Available: create, list, get');
+      process.exit(1);
+  }
+}
+
 /**
  * Card (Stripe) commands
  */
@@ -2258,6 +2441,10 @@ async function main() {
         await handleWebhook(subcommand, args, flags);
         break;
 
+      case 'payout':
+        await handlePayout(subcommand, args, flags);
+        break;
+
       case 'card':
         await handleCard(subcommand, args, flags);
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "CoinPay SDK & CLI — Accept cryptocurrency payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet and swap support",
   "type": "module",
   "main": "./src/index.js",

package/src/card-payments.js

@@ -285,6 +285,128 @@ export function calculateCardPaymentFees(amountCents, tier = 'free') {
   };
 }
 
+/**
+ * Create a card escrow payment
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} businessId - Business ID
+ * @param {number} amountUSD - Amount in USD (will be converted to cents)
+ * @param {string} description - Payment description
+ * @param {Object} [metadata={}] - Custom metadata
+ * @returns {Promise<Object>} Escrow payment session with checkout URL
+ * 
+ * @example
+ * import { createCardEscrow } from '@profullstack/coinpay/card-payments';
+ * 
+ * const escrow = await createCardEscrow(client, 'business-id', 100, 'Service payment', {
+ *   orderId: '123',
+ *   serviceType: 'web-design'
+ * });
+ * 
+ * // Redirect customer to: escrow.checkout_url
+ */
+export async function createCardEscrow(client, businessId, amountUSD, description, metadata = {}) {
+  // Convert USD to cents
+  const amountCents = Math.round(amountUSD * 100);
+
+  return client.request('POST', '/api/stripe/payments/create', {
+    businessId,
+    amount: amountCents,
+    currency: 'usd',
+    description,
+    metadata,
+    escrowMode: true,
+  });
+}
+
+/**
+ * List card escrows
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {Object} [options={}] - Filtering options
+ * @param {string} [options.businessId] - Filter by business ID
+ * @param {string} [options.status] - Filter by status
+ * @param {number} [options.limit] - Maximum number of results
+ * @param {number} [options.offset] - Results offset
+ * @returns {Promise<Object>} List of card escrows
+ * 
+ * @example
+ * const escrows = await listCardEscrows(client, { 
+ *   businessId: 'business-id', 
+ *   status: 'pending' 
+ * });
+ */
+export async function listCardEscrows(client, options = {}) {
+  const queryParams = new URLSearchParams();
+  if (options.businessId) queryParams.set('businessId', options.businessId);
+  if (options.status) queryParams.set('status', options.status);
+  if (options.limit) queryParams.set('limit', options.limit.toString());
+  if (options.offset) queryParams.set('offset', options.offset.toString());
+
+  const queryString = queryParams.toString();
+  const url = `/api/stripe/escrows${queryString ? `?${queryString}` : ''}`;
+  
+  return client.request('GET', url);
+}
+
+/**
+ * Release a card escrow
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} escrowId - Escrow ID to release
+ * @returns {Promise<Object>} Release result
+ * 
+ * @example
+ * const result = await releaseCardEscrow(client, 'escrow-123');
+ */
+export async function releaseCardEscrow(client, escrowId) {
+  return client.request('POST', '/api/stripe/escrow/release', {
+    escrowId,
+  });
+}
+
+/**
+ * Refund a card escrow
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} escrowId - Escrow ID to refund
+ * @param {Object} [options={}] - Refund options
+ * @param {number} [options.amount] - Partial refund amount in cents
+ * @param {string} [options.reason] - Refund reason
+ * @returns {Promise<Object>} Refund result
+ * 
+ * @example
+ * // Full refund
+ * const result = await refundCardEscrow(client, 'escrow-123');
+ * 
+ * // Partial refund
+ * const result = await refundCardEscrow(client, 'escrow-123', { 
+ *   amount: 2500,  // $25.00 in cents
+ *   reason: 'partial_delivery' 
+ * });
+ */
+export async function refundCardEscrow(client, escrowId, options = {}) {
+  return client.request('POST', '/api/stripe/escrow/refund', {
+    escrowId,
+    ...options,
+  });
+}
+
+/**
+ * Get card escrow status and transaction details
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} escrowId - Escrow/transaction ID
+ * @returns {Promise<Object>} Transaction details with escrow status
+ * 
+ * @example
+ * const status = await getCardEscrowStatus(client, 'escrow-123');
+ * console.log(status.escrow_status); // 'pending', 'released', 'refunded'
+ */
+export async function getCardEscrowStatus(client, escrowId) {
+  return client.request('GET', `/api/stripe/transactions/${escrowId}`);
+}
+
 /**
  * Default export with all convenience functions
  */
@@ -295,4 +417,9 @@ export default {
   getPaymentMethodSupport,
   formatCardAmount,
   calculateCardPaymentFees,
+  createCardEscrow,
+  listCardEscrows,
+  releaseCardEscrow,
+  refundCardEscrow,
+  getCardEscrowStatus,
 };

package/src/client.js

@@ -523,6 +523,43 @@ export class CoinPayClient {
     return authenticateEscrow(this, escrowId, token);
   }
 
+  // ── Stripe Payout Methods ───────────────────────────────
+
+  /**
+   * Create a payout to your connected Stripe account
+   * 
+   * @param {Object} params - Payout parameters
+   * @param {number} params.amount - Amount in cents
+   * @param {string} [params.currency='usd'] - Currency code
+   * @param {string} [params.description] - Payout description
+   * @param {Object} [params.metadata] - Custom metadata
+   * @returns {Promise<Object>} Created payout
+   */
+  async createPayout(params) {
+    const { createPayout } = await import('./payouts.js');
+    return createPayout(this, params);
+  }
+
+  /**
+   * List payouts
+   * @param {Object} [filters] - Filter options
+   * @returns {Promise<Object>} Payouts list with pagination
+   */
+  async listPayouts(filters) {
+    const { listPayouts } = await import('./payouts.js');
+    return listPayouts(this, filters);
+  }
+
+  /**
+   * Get payout by ID
+   * @param {string} payoutId - Payout ID
+   * @returns {Promise<Object>} Payout details
+   */
+  async getPayout(payoutId) {
+    const { getPayout } = await import('./payouts.js');
+    return getPayout(this, payoutId);
+  }
+
   // ── Stripe Card Payment Methods ────────────────────────
 
   /**
@@ -685,6 +722,64 @@ export class CoinPayClient {
       }),
     });
   }
+  // ── Escrow Series (Recurring) Methods ────────────────────
+
+  /**
+   * Create a recurring escrow series
+   * @param {Object} params
+   * @returns {Promise<Object>} Created series
+   */
+  async createEscrowSeries(params) {
+    return this.request('/escrow/series', {
+      method: 'POST',
+      body: JSON.stringify(params),
+    });
+  }
+
+  /**
+   * List escrow series for a business
+   * @param {string} businessId
+   * @param {string} [status]
+   * @returns {Promise<Object>}
+   */
+  async listEscrowSeries(businessId, status) {
+    const params = new URLSearchParams({ business_id: businessId });
+    if (status) params.set('status', status);
+    return this.request(`/escrow/series?${params.toString()}`);
+  }
+
+  /**
+   * Get escrow series detail with child escrows
+   * @param {string} id
+   * @returns {Promise<Object>}
+   */
+  async getEscrowSeries(id) {
+    return this.request(`/escrow/series/${id}`);
+  }
+
+  /**
+   * Update escrow series (pause/resume/cancel, update amount/interval)
+   * @param {string} id
+   * @param {Object} params - { status?, amount?, interval? }
+   * @returns {Promise<Object>}
+   */
+  async updateEscrowSeries(id, params) {
+    return this.request(`/escrow/series/${id}`, {
+      method: 'PATCH',
+      body: JSON.stringify(params),
+    });
+  }
+
+  /**
+   * Cancel an escrow series
+   * @param {string} id
+   * @returns {Promise<Object>}
+   */
+  async cancelEscrowSeries(id) {
+    return this.request(`/escrow/series/${id}`, {
+      method: 'DELETE',
+    });
+  }
 }
 
 export default CoinPayClient;

package/src/index.js

@@ -101,6 +101,42 @@ import {
   getSwapHistory,
 } from './swap.js';
 
+// Payouts
+import {
+  createPayout,
+  listPayouts,
+  getPayout,
+  formatPayoutAmount,
+} from './payouts.js';
+
+// Card payments
+import {
+  createQuickCardPayment,
+  waitForStripeOnboarding,
+  createCardPaymentWithOnboardingCheck,
+  getPaymentMethodSupport,
+  formatCardAmount,
+  calculateCardPaymentFees,
+  createCardEscrow,
+  listCardEscrows,
+  releaseCardEscrow,
+  refundCardEscrow,
+  getCardEscrowStatus,
+} from './card-payments.js';
+
+// Subscriptions
+import {
+  createSubscriptionPlan,
+  listSubscriptionPlans,
+  subscribeCustomer,
+  cancelSubscription,
+  listSubscriptions,
+  getSubscription,
+  formatSubscriptionAmount,
+  PlanInterval,
+  SubscriptionStatus,
+} from './subscriptions.js';
+
 export {
   // Client
   CoinPayClient,
@@ -140,6 +176,36 @@ export {
   getSwapStatus,
   getSwapHistory,
   
+  // Payouts
+  createPayout,
+  listPayouts,
+  getPayout,
+  formatPayoutAmount,
+  
+  // Card payments
+  createQuickCardPayment,
+  waitForStripeOnboarding,
+  createCardPaymentWithOnboardingCheck,
+  getPaymentMethodSupport,
+  formatCardAmount,
+  calculateCardPaymentFees,
+  createCardEscrow,
+  listCardEscrows,
+  releaseCardEscrow,
+  refundCardEscrow,
+  getCardEscrowStatus,
+  
+  // Subscriptions
+  createSubscriptionPlan,
+  listSubscriptionPlans,
+  subscribeCustomer,
+  cancelSubscription,
+  listSubscriptions,
+  getSubscription,
+  formatSubscriptionAmount,
+  PlanInterval,
+  SubscriptionStatus,
+  
   // Constants
   Blockchain,
   Cryptocurrency,  // Deprecated, use Blockchain

package/src/payouts.js

@@ -0,0 +1,79 @@
+/**
+ * CoinPay Payouts - Functions for Stripe Connect payouts
+ * 
+ * Manage payouts to connected Stripe accounts (merchants).
+ */
+
+/**
+ * Create a payout to a connected Stripe account
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {Object} params - Payout parameters
+ * @param {number} params.amount - Amount in cents (e.g., 5000 = $50.00)
+ * @param {string} [params.currency='usd'] - Currency code
+ * @param {string} [params.description] - Payout description
+ * @param {Object} [params.metadata] - Custom metadata
+ * @returns {Promise<Object>} Created payout
+ * 
+ * @example
+ * const payout = await createPayout(client, {
+ *   amount: 5000,
+ *   currency: 'usd',
+ *   description: 'Weekly payout'
+ * });
+ */
+export async function createPayout(client, { amount, currency = 'usd', description, metadata }) {
+  return client.request('/stripe/payouts', {
+    method: 'POST',
+    body: JSON.stringify({ amount, currency, description, metadata }),
+  });
+}
+
+/**
+ * List payouts for the authenticated merchant
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {Object} [filters] - Filter options
+ * @param {string} [filters.status] - Filter by status (pending, paid, failed, canceled)
+ * @param {string} [filters.dateFrom] - Filter from date (ISO string)
+ * @param {string} [filters.dateTo] - Filter to date (ISO string)
+ * @param {number} [filters.limit=50] - Number of results
+ * @param {number} [filters.offset=0] - Pagination offset
+ * @returns {Promise<Object>} List of payouts with pagination
+ */
+export async function listPayouts(client, filters = {}) {
+  const params = new URLSearchParams();
+  if (filters.status) params.set('status', filters.status);
+  if (filters.dateFrom) params.set('date_from', filters.dateFrom);
+  if (filters.dateTo) params.set('date_to', filters.dateTo);
+  if (filters.limit) params.set('limit', String(filters.limit));
+  if (filters.offset) params.set('offset', String(filters.offset));
+
+  const qs = params.toString();
+  return client.request(`/stripe/payouts${qs ? '?' + qs : ''}`);
+}
+
+/**
+ * Get a specific payout by ID
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} payoutId - Payout ID
+ * @returns {Promise<Object>} Payout details
+ */
+export async function getPayout(client, payoutId) {
+  return client.request(`/stripe/payouts/${payoutId}`);
+}
+
+/**
+ * Format payout amount from cents to display string
+ * 
+ * @param {number} amountCents - Amount in cents
+ * @param {string} [currency='usd'] - Currency code
+ * @returns {string} Formatted amount (e.g., "$50.00")
+ */
+export function formatPayoutAmount(amountCents, currency = 'usd') {
+  const amount = (amountCents / 100).toFixed(2);
+  const symbols = { usd: '$', eur: '€', gbp: '£' };
+  const symbol = symbols[currency.toLowerCase()] || currency.toUpperCase() + ' ';
+  return `${symbol}${amount}`;
+}

package/src/subscriptions.js

@@ -0,0 +1,231 @@
+/**
+ * CoinPay Subscriptions - Stripe subscription billing integration
+ * 
+ * Provides functions for managing subscription plans and customer subscriptions
+ * through Stripe's subscription billing system.
+ */
+
+/**
+ * Subscription plan intervals
+ */
+export const PlanInterval = {
+  DAILY: 'day',
+  WEEKLY: 'week',
+  MONTHLY: 'month',
+  YEARLY: 'year',
+};
+
+/**
+ * Subscription statuses
+ */
+export const SubscriptionStatus = {
+  ACTIVE: 'active',
+  PAST_DUE: 'past_due',
+  CANCELED: 'canceled',
+  INCOMPLETE: 'incomplete',
+  INCOMPLETE_EXPIRED: 'incomplete_expired',
+  TRIALING: 'trialing',
+  UNPAID: 'unpaid',
+  PAUSED: 'paused',
+};
+
+/**
+ * Create a subscription plan (Stripe Price + Product)
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {Object} params - Plan parameters
+ * @param {string} params.businessId - Business ID
+ * @param {string} params.name - Plan name
+ * @param {string} [params.description] - Plan description
+ * @param {number} params.amount - Amount in cents
+ * @param {string} [params.currency='usd'] - Currency code
+ * @param {string} [params.interval='month'] - Billing interval (day, week, month, year)
+ * @param {number} [params.intervalCount=1] - Number of intervals between billings
+ * @param {number} [params.trialDays] - Trial period in days
+ * @param {Object} [params.metadata] - Custom metadata
+ * @returns {Promise<Object>} Created plan
+ * 
+ * @example
+ * const plan = await createSubscriptionPlan(client, {
+ *   businessId: 'biz-123',
+ *   name: 'Pro Monthly',
+ *   amount: 2999,
+ *   interval: 'month',
+ * });
+ */
+export async function createSubscriptionPlan(client, params) {
+  const {
+    businessId,
+    name,
+    description,
+    amount,
+    currency = 'usd',
+    interval = 'month',
+    intervalCount = 1,
+    trialDays,
+    metadata = {},
+  } = params;
+
+  if (!businessId || !name || !amount) {
+    throw new Error('businessId, name, and amount are required');
+  }
+
+  return client.request('/stripe/subscriptions/plans', {
+    method: 'POST',
+    body: JSON.stringify({
+      businessId,
+      name,
+      description,
+      amount,
+      currency,
+      interval,
+      intervalCount,
+      trialDays,
+      metadata,
+    }),
+  });
+}
+
+/**
+ * List subscription plans for a business
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} businessId - Business ID
+ * @param {Object} [options] - Query options
+ * @param {number} [options.limit=20] - Max results
+ * @param {boolean} [options.active] - Filter by active status
+ * @returns {Promise<Object>} List of plans
+ */
+export async function listSubscriptionPlans(client, businessId, options = {}) {
+  const params = new URLSearchParams({ businessId });
+  if (options.limit) params.set('limit', String(options.limit));
+  if (options.active !== undefined) params.set('active', String(options.active));
+
+  return client.request(`/stripe/subscriptions/plans?${params}`);
+}
+
+/**
+ * Subscribe a customer to a plan
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {Object} params - Subscription parameters
+ * @param {string} params.planId - Plan/Price ID
+ * @param {string} params.customerEmail - Customer email
+ * @param {string} [params.customerId] - Existing Stripe customer ID
+ * @param {string} [params.paymentMethodId] - Payment method ID
+ * @param {string} [params.successUrl] - Success redirect URL
+ * @param {string} [params.cancelUrl] - Cancel redirect URL
+ * @param {Object} [params.metadata] - Custom metadata
+ * @returns {Promise<Object>} Subscription or checkout session
+ * 
+ * @example
+ * const sub = await subscribeCustomer(client, {
+ *   planId: 'price_123',
+ *   customerEmail: 'customer@example.com',
+ *   successUrl: 'https://mysite.com/success',
+ *   cancelUrl: 'https://mysite.com/cancel',
+ * });
+ * // Redirect to sub.checkout_url
+ */
+export async function subscribeCustomer(client, params) {
+  const {
+    planId,
+    customerEmail,
+    customerId,
+    paymentMethodId,
+    successUrl,
+    cancelUrl,
+    metadata = {},
+  } = params;
+
+  if (!planId || (!customerEmail && !customerId)) {
+    throw new Error('planId and either customerEmail or customerId are required');
+  }
+
+  return client.request('/stripe/subscriptions', {
+    method: 'POST',
+    body: JSON.stringify({
+      planId,
+      customerEmail,
+      customerId,
+      paymentMethodId,
+      successUrl,
+      cancelUrl,
+      metadata,
+    }),
+  });
+}
+
+/**
+ * Cancel a subscription
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} subscriptionId - Subscription ID
+ * @param {Object} [options] - Cancellation options
+ * @param {boolean} [options.immediately=false] - Cancel immediately vs at period end
+ * @returns {Promise<Object>} Cancelled subscription
+ */
+export async function cancelSubscription(client, subscriptionId, options = {}) {
+  if (!subscriptionId) {
+    throw new Error('subscriptionId is required');
+  }
+
+  return client.request(`/stripe/subscriptions/${encodeURIComponent(subscriptionId)}`, {
+    method: 'DELETE',
+    body: JSON.stringify({
+      immediately: options.immediately || false,
+    }),
+  });
+}
+
+/**
+ * List subscriptions
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {Object} [options] - Query options
+ * @param {string} [options.businessId] - Filter by business
+ * @param {string} [options.customerId] - Filter by customer
+ * @param {string} [options.status] - Filter by status
+ * @param {number} [options.limit=20] - Max results
+ * @param {number} [options.offset=0] - Pagination offset
+ * @returns {Promise<Object>} List of subscriptions
+ */
+export async function listSubscriptions(client, options = {}) {
+  const params = new URLSearchParams();
+  if (options.businessId) params.set('businessId', options.businessId);
+  if (options.customerId) params.set('customerId', options.customerId);
+  if (options.status) params.set('status', options.status);
+  if (options.limit) params.set('limit', String(options.limit));
+  if (options.offset) params.set('offset', String(options.offset));
+
+  return client.request(`/stripe/subscriptions?${params}`);
+}
+
+/**
+ * Get subscription status/details
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} subscriptionId - Subscription ID
+ * @returns {Promise<Object>} Subscription details
+ */
+export async function getSubscription(client, subscriptionId) {
+  if (!subscriptionId) {
+    throw new Error('subscriptionId is required');
+  }
+
+  return client.request(`/stripe/subscriptions/${encodeURIComponent(subscriptionId)}`);
+}
+
+/**
+ * Format subscription amount for display
+ * 
+ * @param {number} amount - Amount in cents
+ * @param {string} [currency='usd'] - Currency code
+ * @param {string} [interval='month'] - Billing interval
+ * @returns {string} Formatted amount (e.g., "$29.99/month")
+ */
+export function formatSubscriptionAmount(amount, currency = 'usd', interval = 'month') {
+  const dollars = (amount / 100).toFixed(2);
+  const symbol = currency.toLowerCase() === 'usd' ? '$' : currency.toUpperCase() + ' ';
+  return `${symbol}${dollars}/${interval}`;
+}