@profullstack/coinpay 0.6.3 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/coinpay",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "CoinPay SDK & CLI — Accept cryptocurrency payments (BTC, ETH, SOL, POL, BCH, USDC) with wallet and swap support",
   "type": "module",
   "main": "./src/index.js",
@@ -17,6 +17,10 @@
       "import": "./src/payments.js",
       "types": "./src/payments.d.ts"
     },
+    "./card-payments": {
+      "import": "./src/card-payments.js",
+      "types": "./src/card-payments.d.ts"
+    },
     "./webhooks": {
       "import": "./src/webhooks.js",
       "types": "./src/webhooks.d.ts"

package/src/card-payments.js

@@ -0,0 +1,298 @@
+/**
+ * CoinPay Card Payments - Convenience functions for Stripe integration
+ * 
+ * This module provides high-level convenience functions for working with
+ * card payments through Stripe Connect, similar to the payments.js module.
+ */
+
+/**
+ * Quick card payment creation with sensible defaults
+ * 
+ * @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} [options] - Additional options
+ * @param {Object} [options.metadata] - Custom metadata
+ * @param {string} [options.successUrl] - Success redirect URL
+ * @param {string} [options.cancelUrl] - Cancel redirect URL
+ * @param {boolean} [options.escrowMode=false] - Enable escrow mode
+ * @returns {Promise<Object>} Payment session with checkout URL
+ * 
+ * @example
+ * import { createQuickCardPayment } from '@profullstack/coinpay/card-payments';
+ * 
+ * const payment = await createQuickCardPayment(client, 'business-id', 50, 'Order #123', {
+ *   metadata: { orderId: '123' },
+ *   escrowMode: true
+ * });
+ * 
+ * // Redirect customer to: payment.checkout_url
+ */
+export async function createQuickCardPayment(client, businessId, amountUSD, description, options = {}) {
+  const {
+    metadata = {},
+    successUrl,
+    cancelUrl,
+    escrowMode = false,
+  } = options;
+
+  // Convert USD to cents
+  const amountCents = Math.round(amountUSD * 100);
+
+  return client.createCardPayment({
+    businessId,
+    amount: amountCents,
+    currency: 'usd',
+    description,
+    metadata,
+    successUrl,
+    cancelUrl,
+    escrowMode,
+  });
+}
+
+/**
+ * Wait for merchant to complete Stripe onboarding
+ * 
+ * Polls the Stripe account status until onboarding is complete.
+ * Useful for integration flows where you need to wait for merchant setup.
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} businessId - Business ID
+ * @param {Object} [options] - Polling options
+ * @param {number} [options.intervalMs=5000] - Polling interval in ms
+ * @param {number} [options.timeoutMs=300000] - Timeout in ms (default: 5 minutes)
+ * @param {Function} [options.onStatusChange] - Callback for status changes
+ * @returns {Promise<Object>} Final account status when onboarding complete
+ * 
+ * @example
+ * const accountStatus = await waitForStripeOnboarding(client, 'business-id', {
+ *   onStatusChange: (status) => {
+ *     console.log(`Onboarding status: ${JSON.stringify(status)}`);
+ *   }
+ * });
+ */
+export async function waitForStripeOnboarding(client, businessId, options = {}) {
+  const {
+    intervalMs = 5000,
+    timeoutMs = 300000, // 5 minutes
+    onStatusChange,
+  } = options;
+
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeoutMs) {
+    const status = await client.getStripeAccountStatus(businessId);
+
+    if (onStatusChange) {
+      onStatusChange(status);
+    }
+
+    if (status.onboarding_complete) {
+      return status;
+    }
+
+    // Wait before next poll
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
+  }
+
+  throw new Error(`Stripe onboarding timeout after ${timeoutMs}ms`);
+}
+
+/**
+ * Create payment with automatic merchant onboarding check
+ * 
+ * Checks if merchant has completed Stripe onboarding first, and provides
+ * helpful error messages if not. Prevents failed payment attempts.
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {Object} params - Payment parameters (same as createCardPayment)
+ * @returns {Promise<Object>} Payment session or onboarding info if incomplete
+ * 
+ * @example
+ * const result = await createCardPaymentWithOnboardingCheck(client, {
+ *   businessId: 'business-id',
+ *   amount: 5000,
+ *   description: 'Order #123'
+ * });
+ * 
+ * if (result.requires_onboarding) {
+ *   // Redirect merchant to result.onboarding_url
+ * } else {
+ *   // Redirect customer to result.checkout_url
+ * }
+ */
+export async function createCardPaymentWithOnboardingCheck(client, params) {
+  try {
+    // Check onboarding status first
+    const status = await client.getStripeAccountStatus(params.businessId);
+
+    if (!status.onboarding_complete) {
+      // Generate onboarding link if needed
+      const onboarding = await client.createStripeOnboardingLink(params.businessId);
+      
+      return {
+        requires_onboarding: true,
+        onboarding_url: onboarding.onboarding_url,
+        status: status,
+        message: 'Merchant must complete Stripe onboarding before accepting card payments',
+      };
+    }
+
+    // Onboarding complete, create payment
+    const payment = await client.createCardPayment(params);
+    return {
+      requires_onboarding: false,
+      ...payment,
+    };
+
+  } catch (error) {
+    if (error.status === 404) {
+      // No Stripe account exists, need onboarding
+      const onboarding = await client.createStripeOnboardingLink(params.businessId);
+      
+      return {
+        requires_onboarding: true,
+        onboarding_url: onboarding.onboarding_url,
+        status: null,
+        message: 'Merchant needs to complete Stripe onboarding',
+      };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Get payment method support status
+ * 
+ * Returns which payment methods are available for a merchant.
+ * Helps with conditional UI rendering.
+ * 
+ * @param {import('./client.js').CoinPayClient} client - CoinPay client instance
+ * @param {string} businessId - Business ID
+ * @returns {Promise<Object>} Available payment methods
+ * 
+ * @example
+ * const support = await getPaymentMethodSupport(client, 'business-id');
+ * console.log(support);
+ * // {
+ * //   crypto: true,
+ * //   cards: true,
+ * //   escrow: true,
+ * //   stripe_onboarding_complete: true
+ * // }
+ */
+export async function getPaymentMethodSupport(client, businessId) {
+  try {
+    // Check if business exists (crypto payments always work)
+    await client.getBusiness(businessId);
+    
+    let cardSupport = false;
+    let stripeOnboardingComplete = false;
+
+    // Check Stripe status
+    try {
+      const stripeStatus = await client.getStripeAccountStatus(businessId);
+      cardSupport = stripeStatus.onboarding_complete;
+      stripeOnboardingComplete = stripeStatus.onboarding_complete;
+    } catch (error) {
+      // No Stripe account = no card support yet
+      cardSupport = false;
+      stripeOnboardingComplete = false;
+    }
+
+    return {
+      crypto: true, // Always available
+      cards: cardSupport,
+      escrow: cardSupport, // Card escrow requires Stripe
+      stripe_onboarding_complete: stripeOnboardingComplete,
+    };
+
+  } catch (error) {
+    if (error.status === 404) {
+      return {
+        crypto: false,
+        cards: false,
+        escrow: false,
+        stripe_onboarding_complete: false,
+        error: 'Business not found',
+      };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Format amount for display
+ * 
+ * Converts cents to dollar amount with proper formatting.
+ * 
+ * @param {number} amountCents - Amount in cents
+ * @param {string} [currency='USD'] - Currency code
+ * @returns {string} Formatted amount string
+ * 
+ * @example
+ * formatCardAmount(5000); // "$50.00"
+ * formatCardAmount(5050); // "$50.50"
+ * formatCardAmount(500, 'EUR'); // "€5.00"
+ */
+export function formatCardAmount(amountCents, currency = 'USD') {
+  const amount = amountCents / 100;
+  
+  const formatters = {
+    USD: (amt) => `$${amt.toFixed(2)}`,
+    EUR: (amt) => `€${amt.toFixed(2)}`,
+    GBP: (amt) => `£${amt.toFixed(2)}`,
+    CAD: (amt) => `C$${amt.toFixed(2)}`,
+  };
+
+  const formatter = formatters[currency.toUpperCase()];
+  if (formatter) {
+    return formatter(amount);
+  }
+
+  // Fallback for unknown currencies
+  return `${amount.toFixed(2)} ${currency.toUpperCase()}`;
+}
+
+/**
+ * Calculate platform fees for card payments
+ * 
+ * @param {number} amountCents - Payment amount in cents
+ * @param {string} tier - Merchant tier ('free' or 'pro')
+ * @returns {Object} Fee breakdown
+ * 
+ * @example
+ * const fees = calculateCardPaymentFees(5000, 'free');
+ * console.log(fees);
+ * // {
+ * //   amount: 5000,
+ * //   platformFee: 50,
+ * //   platformFeePercent: 1,
+ * //   merchantReceives: 4950 // before Stripe fees
+ * // }
+ */
+export function calculateCardPaymentFees(amountCents, tier = 'free') {
+  const platformFeePercent = tier === 'pro' ? 0.5 : 1.0; // 0.5% or 1%
+  const platformFeeCents = Math.round(amountCents * (platformFeePercent / 100));
+  
+  return {
+    amount: amountCents,
+    platformFee: platformFeeCents,
+    platformFeePercent,
+    merchantReceives: amountCents - platformFeeCents, // Before Stripe processing fees
+  };
+}
+
+/**
+ * Default export with all convenience functions
+ */
+export default {
+  createQuickCardPayment,
+  waitForStripeOnboarding,
+  createCardPaymentWithOnboardingCheck,
+  getPaymentMethodSupport,
+  formatCardAmount,
+  calculateCardPaymentFees,
+};

package/src/client.js

@@ -522,6 +522,169 @@ export class CoinPayClient {
     const { authenticateEscrow } = await import('./escrow.js');
     return authenticateEscrow(this, escrowId, token);
   }
+
+  // ── Stripe Card Payment Methods ────────────────────────
+
+  /**
+   * Create a card payment using Stripe
+   * 
+   * Creates a card payment session through Stripe Connect. Returns a checkout URL
+   * that customers can use to pay with their credit/debit card.
+   * 
+   * @param {Object} params - Payment parameters
+   * @param {string} params.businessId - Business ID (merchant must have completed Stripe onboarding)
+   * @param {number} params.amount - Amount in cents (e.g., 5000 = $50.00)
+   * @param {string} [params.currency='usd'] - Currency code (usd, eur, etc.)
+   * @param {string} [params.description] - Payment description
+   * @param {Object} [params.metadata] - Custom metadata
+   * @param {string} [params.successUrl] - URL to redirect on successful payment
+   * @param {string} [params.cancelUrl] - URL to redirect on payment cancellation
+   * @param {boolean} [params.escrowMode=false] - Whether to use escrow mode (holds funds until release)
+   * @returns {Promise<Object>} Payment session with checkout URL
+   * 
+   * @example
+   * // Create a $50 card payment
+   * const payment = await client.createCardPayment({
+   *   businessId: 'your-business-id',
+   *   amount: 5000, // $50.00 in cents
+   *   currency: 'usd',
+   *   description: 'Order #12345',
+   *   metadata: { orderId: '12345' },
+   *   successUrl: 'https://yourdomain.com/success',
+   *   cancelUrl: 'https://yourdomain.com/cancel'
+   * });
+   * 
+   * // Redirect customer to payment.checkout_url
+   */
+  async createCardPayment({
+    businessId,
+    amount,
+    currency = 'usd',
+    description,
+    metadata,
+    successUrl,
+    cancelUrl,
+    escrowMode = false
+  }) {
+    return this.request('/stripe/payments/create', {
+      method: 'POST',
+      body: JSON.stringify({
+        businessId,
+        amount,
+        currency,
+        description,
+        metadata,
+        successUrl,
+        cancelUrl,
+        escrowMode
+      }),
+    });
+  }
+
+  /**
+   * Get Stripe account onboarding status
+   * 
+   * Checks whether a merchant has completed Stripe Connect onboarding
+   * and is able to accept card payments.
+   * 
+   * @param {string} businessId - Business ID
+   * @returns {Promise<Object>} Account status and capabilities
+   * 
+   * @example
+   * const status = await client.getStripeAccountStatus('business-id');
+   * if (status.onboarding_complete) {
+   *   console.log('Merchant can accept card payments');
+   * }
+   */
+  async getStripeAccountStatus(businessId) {
+    return this.request(`/stripe/connect/status/${businessId}`);
+  }
+
+  /**
+   * Create Stripe Connect onboarding link
+   * 
+   * Generates a Stripe Express onboarding link for a merchant.
+   * The merchant must complete this onboarding before they can accept card payments.
+   * 
+   * @param {string} businessId - Business ID
+   * @param {Object} [params] - Optional parameters
+   * @param {string} [params.email] - Merchant email (pre-fills onboarding form)
+   * @param {string} [params.country='US'] - Country code (US, CA, GB, etc.)
+   * @returns {Promise<Object>} Onboarding link and account ID
+   * 
+   * @example
+   * const onboarding = await client.createStripeOnboardingLink('business-id', {
+   *   email: 'merchant@example.com',
+   *   country: 'US'
+   * });
+   * 
+   * // Redirect merchant to onboarding.onboarding_url
+   */
+  async createStripeOnboardingLink(businessId, params = {}) {
+    return this.request('/stripe/connect/onboard', {
+      method: 'POST',
+      body: JSON.stringify({
+        businessId,
+        ...params
+      }),
+    });
+  }
+
+  /**
+   * Release card escrow funds to merchant
+   * 
+   * Releases funds held in card escrow mode to the merchant's Stripe account.
+   * Only works for payments created with escrowMode: true.
+   * 
+   * @param {string} escrowId - Escrow ID (returned from escrow payment creation)
+   * @param {string} [reason] - Reason for release
+   * @returns {Promise<Object>} Release confirmation with transfer details
+   * 
+   * @example
+   * const release = await client.releaseCardEscrow('escrow-id', 'Work completed');
+   * console.log(`Released $${release.amount_transferred / 100} to merchant`);
+   */
+  async releaseCardEscrow(escrowId, reason) {
+    return this.request('/stripe/escrow/release', {
+      method: 'POST',
+      body: JSON.stringify({
+        escrowId,
+        reason
+      }),
+    });
+  }
+
+  /**
+   * Refund a card payment
+   * 
+   * Creates a refund for a card payment. Works for both gateway and escrow mode payments.
+   * For escrow payments, refunds from held funds. For gateway payments, refunds from merchant account.
+   * 
+   * @param {string} paymentId - Payment intent ID or escrow ID
+   * @param {Object} [params] - Optional parameters
+   * @param {number} [params.amount] - Refund amount in cents (partial refund). Omit for full refund.
+   * @param {string} [params.reason] - Reason for refund
+   * @returns {Promise<Object>} Refund confirmation
+   * 
+   * @example
+   * // Full refund
+   * const refund = await client.refundCardPayment('payment-id');
+   * 
+   * // Partial refund
+   * const partialRefund = await client.refundCardPayment('payment-id', {
+   *   amount: 2500, // $25.00 refund
+   *   reason: 'Customer complaint'
+   * });
+   */
+  async refundCardPayment(paymentId, params = {}) {
+    return this.request('/stripe/escrow/refund', {
+      method: 'POST',
+      body: JSON.stringify({
+        escrowId: paymentId, // API expects escrowId param
+        ...params
+      }),
+    });
+  }
 }
 
 export default CoinPayClient;