swiftshopr-payments 1.0.0

package/src/payments.js

@@ -0,0 +1,319 @@
+/**
+ * Payments API Module
+ * Handles payment sessions, transfers, and status checks
+ */
+
+const { SwiftShoprError } = require('./utils/http');
+
+/**
+ * UUID validation regex
+ */
+const UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Ethereum address validation regex
+ */
+const ETH_ADDRESS_REGEX = /^0x[a-fA-F0-9]{40}$/;
+
+/**
+ * Validate payment session parameters
+ */
+function validateSessionParams(params) {
+  const errors = [];
+
+  if (
+    !params.amount ||
+    typeof params.amount !== 'number' ||
+    params.amount <= 0
+  ) {
+    errors.push('amount must be a positive number');
+  }
+
+  if (params.amount > 10000) {
+    errors.push('amount cannot exceed $10,000 per transaction');
+  }
+
+  if (
+    params.destinationAddress &&
+    !ETH_ADDRESS_REGEX.test(params.destinationAddress)
+  ) {
+    errors.push('destinationAddress must be a valid Ethereum address');
+  }
+
+  if (!params.storeId && !params.destinationAddress) {
+    errors.push('Either storeId or destinationAddress is required');
+  }
+
+  if (errors.length > 0) {
+    throw new SwiftShoprError('VALIDATION_ERROR', errors.join('; '), {
+      errors,
+    });
+  }
+}
+
+/**
+ * Validate transfer parameters
+ */
+function validateTransferParams(params) {
+  const errors = [];
+
+  if (
+    !params.amount ||
+    typeof params.amount !== 'number' ||
+    params.amount <= 0
+  ) {
+    errors.push('amount must be a positive number');
+  }
+
+  if (params.amount > 10000) {
+    errors.push('amount cannot exceed $10,000 per transaction');
+  }
+
+  if (
+    !params.userWalletAddress ||
+    !ETH_ADDRESS_REGEX.test(params.userWalletAddress)
+  ) {
+    errors.push('userWalletAddress must be a valid Ethereum address');
+  }
+
+  if (
+    params.destinationAddress &&
+    !ETH_ADDRESS_REGEX.test(params.destinationAddress)
+  ) {
+    errors.push('destinationAddress must be a valid Ethereum address');
+  }
+
+  if (!params.storeId && !params.destinationAddress) {
+    errors.push('Either storeId or destinationAddress is required');
+  }
+
+  if (errors.length > 0) {
+    throw new SwiftShoprError('VALIDATION_ERROR', errors.join('; '), {
+      errors,
+    });
+  }
+}
+
+/**
+ * Create Payments API instance
+ */
+function createPaymentsAPI(http) {
+  return {
+    /**
+     * Create an onramp session (Add Funds button)
+     * User will be directed to Coinbase to purchase USDC
+     *
+     * @param {Object} params
+     * @param {number} params.amount - Amount in USD
+     * @param {string} [params.orderId] - Your order reference
+     * @param {string} [params.storeId] - Store ID (resolves wallet automatically)
+     * @param {string} [params.destinationAddress] - Retailer wallet address
+     * @param {string} [params.paymentMethod] - ACH_BANK_ACCOUNT, CARD, etc.
+     * @returns {Promise<Object>} Session with onramp_url
+     */
+    async createSession(params) {
+      validateSessionParams(params);
+
+      const body = {
+        paymentAmount: params.amount.toString(),
+        paymentCurrency: 'USD',
+        paymentMethod: params.paymentMethod || 'ACH_BANK_ACCOUNT',
+        ...(params.orderId && { orderId: params.orderId }),
+        ...(params.storeId && { storeId: params.storeId }),
+        ...(params.destinationAddress && {
+          destinationAddress: params.destinationAddress,
+        }),
+        ...(params.metadata && { metadata: params.metadata }),
+      };
+
+      const response = await http.post('/api/v1/sdk/onramp/session', body, {
+        idempotencyKey: params.idempotencyKey,
+      });
+
+      return {
+        intentId: response.intent_id,
+        sessionId: response.session_id,
+        orderId: response.order_id,
+        quoteId: response.quote_id,
+        onrampUrl: response.onramp_url,
+        expiresAt: response.expires_at,
+        branding: response.branding || null,
+      };
+    },
+
+    /**
+     * Create a direct transfer (Purchase button)
+     * For users who already have USDC balance
+     *
+     * @param {Object} params
+     * @param {number} params.amount - Amount in USD
+     * @param {string} params.userWalletAddress - User's wallet address
+     * @param {string} [params.orderId] - Your order reference
+     * @param {string} [params.storeId] - Store ID (resolves wallet automatically)
+     * @param {string} [params.destinationAddress] - Retailer wallet address
+     * @returns {Promise<Object>} Transfer instructions
+     */
+    async createTransfer(params) {
+      validateTransferParams(params);
+
+      const body = {
+        amount: params.amount.toString(),
+        userWalletAddress: params.userWalletAddress,
+        ...(params.orderId && { orderId: params.orderId }),
+        ...(params.storeId && { storeId: params.storeId }),
+        ...(params.destinationAddress && {
+          destinationAddress: params.destinationAddress,
+        }),
+        ...(params.metadata && { metadata: params.metadata }),
+      };
+
+      const response = await http.post('/api/v1/sdk/onramp/transfer', body, {
+        idempotencyKey: params.idempotencyKey,
+      });
+
+      return {
+        intentId: response.intent_id,
+        orderId: response.order_id,
+        status: response.status,
+        transfer: {
+          to: response.transfer.to,
+          amount: response.transfer.amount,
+          asset: response.transfer.asset,
+          network: response.transfer.network,
+          chainId: response.transfer.chain_id,
+        },
+        expiresAt: response.expires_at,
+        branding: response.branding || null,
+      };
+    },
+
+    /**
+     * Get payment status by intent ID
+     *
+     * @param {string} intentId - Payment intent ID (UUID)
+     * @returns {Promise<Object>} Payment status
+     */
+    async getStatus(intentId) {
+      if (!intentId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'intentId is required');
+      }
+
+      const response = await http.get(
+        `/api/v1/sdk/onramp/payments/${intentId}/status`,
+      );
+
+      return {
+        intentId: response.intent_id,
+        orderId: response.order_id,
+        status: response.status,
+        amount: parseFloat(response.amount_usd),
+        storeId: response.store_id,
+        destinationAddress: response.destination_address,
+        txHash: response.tx_hash || null,
+        explorerUrl: response.explorer_url || null,
+        confirmedAt: response.confirmed_at || null,
+        createdAt: response.created_at,
+        expiresAt: response.expires_at,
+        isExpired: response.is_expired,
+        refund: response.refund || null,
+      };
+    },
+
+    /**
+     * Get payment status by order ID
+     *
+     * @param {string} orderId - Your order reference
+     * @returns {Promise<Object>} Payment status
+     */
+    async getStatusByOrderId(orderId) {
+      if (!orderId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'orderId is required');
+      }
+
+      const response = await http.get(
+        `/api/v1/sdk/onramp/payments/${encodeURIComponent(orderId)}/status?by=order`,
+      );
+
+      return {
+        intentId: response.intent_id,
+        orderId: response.order_id,
+        status: response.status,
+        amount: parseFloat(response.amount_usd),
+        storeId: response.store_id,
+        destinationAddress: response.destination_address,
+        txHash: response.tx_hash || null,
+        explorerUrl: response.explorer_url || null,
+        confirmedAt: response.confirmed_at || null,
+        createdAt: response.created_at,
+        expiresAt: response.expires_at,
+        isExpired: response.is_expired,
+        refund: response.refund || null,
+      };
+    },
+
+    /**
+     * Poll for payment completion
+     * Useful for waiting for webhook confirmation
+     *
+     * @param {string} intentId - Payment intent ID
+     * @param {Object} [options]
+     * @param {number} [options.timeout=300000] - Max wait time (default 5 min)
+     * @param {number} [options.interval=2000] - Poll interval (default 2s)
+     * @param {Function} [options.onStatusChange] - Callback on status change
+     * @returns {Promise<Object>} Final payment status
+     */
+    async waitForCompletion(intentId, options = {}) {
+      const timeout = options.timeout || 300000;
+      const interval = options.interval || 2000;
+      const { onStatusChange } = options;
+
+      const startTime = Date.now();
+      let lastStatus = null;
+
+      while (Date.now() - startTime < timeout) {
+        const status = await this.getStatus(intentId);
+
+        if (lastStatus !== status.status) {
+          lastStatus = status.status;
+          if (onStatusChange) {
+            onStatusChange(status);
+          }
+        }
+
+        if (status.status === 'completed' || status.status === 'COMPLETED') {
+          return status;
+        }
+
+        if (status.status === 'failed' || status.status === 'FAILED') {
+          throw new SwiftShoprError('PAYMENT_FAILED', 'Payment failed', status);
+        }
+
+        if (status.status === 'canceled' || status.status === 'CANCELED') {
+          throw new SwiftShoprError(
+            'PAYMENT_CANCELED',
+            'Payment was canceled',
+            status,
+          );
+        }
+
+        if (status.isExpired) {
+          throw new SwiftShoprError(
+            'PAYMENT_EXPIRED',
+            'Payment expired',
+            status,
+          );
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, interval));
+      }
+
+      throw new SwiftShoprError(
+        'TIMEOUT',
+        `Payment did not complete within ${timeout}ms`,
+      );
+    },
+  };
+}
+
+module.exports = { createPaymentsAPI };

package/src/refunds.js

@@ -0,0 +1,209 @@
+/**
+ * Refunds API Module
+ * Handles refund requests and status tracking
+ */
+
+const { SwiftShoprError } = require('./utils/http');
+
+/**
+ * UUID validation regex
+ */
+const UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Validate refund parameters
+ */
+function validateRefundParams(params) {
+  const errors = [];
+
+  if (!params.intentId) {
+    errors.push('intentId is required');
+  } else if (!UUID_REGEX.test(params.intentId)) {
+    errors.push('intentId must be a valid UUID');
+  }
+
+  if (params.amount !== undefined) {
+    if (typeof params.amount !== 'number' || params.amount <= 0) {
+      errors.push('amount must be a positive number');
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new SwiftShoprError('VALIDATION_ERROR', errors.join('; '), {
+      errors,
+    });
+  }
+}
+
+/**
+ * Create Refunds API instance
+ */
+function createRefundsAPI(http) {
+  return {
+    /**
+     * Request a refund for a completed payment
+     *
+     * @param {Object} params
+     * @param {string} params.intentId - Original payment intent ID
+     * @param {number} [params.amount] - Refund amount (optional, defaults to full refund)
+     * @param {string} [params.reason] - Reason for refund
+     * @returns {Promise<Object>} Refund details with transfer instructions
+     */
+    async create(params) {
+      validateRefundParams(params);
+
+      const body = {
+        intent_id: params.intentId,
+        ...(params.amount && { amount: params.amount }),
+        ...(params.reason && { reason: params.reason }),
+      };
+
+      const response = await http.post('/api/v1/sdk/onramp/refund', body, {
+        idempotencyKey: params.idempotencyKey,
+      });
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          response.error || 'REFUND_ERROR',
+          response.message || 'Refund request failed',
+          response,
+        );
+      }
+
+      return {
+        id: response.refund.id,
+        intentId: response.refund.intent_id,
+        orderId: response.refund.order_id,
+        status: response.refund.status,
+        amount: response.refund.amount,
+        originalAmount: response.refund.original_amount,
+        isPartial: response.refund.is_partial,
+        reason: response.refund.reason,
+        createdAt: response.refund.created_at,
+        instructions: {
+          message: response.instructions.message,
+          transfer: {
+            to: response.instructions.transfer.to,
+            amount: response.instructions.transfer.amount,
+            asset: response.instructions.transfer.asset,
+            network: response.instructions.transfer.network,
+            chainId: response.instructions.transfer.chain_id,
+          },
+          fromWallet: response.instructions.from_wallet,
+        },
+      };
+    },
+
+    /**
+     * Get refund status by refund ID
+     *
+     * @param {string} refundId - Refund ID (UUID)
+     * @returns {Promise<Object>} Refund status
+     */
+    async get(refundId) {
+      if (!refundId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'refundId is required');
+      }
+
+      const response = await http.get(`/api/v1/sdk/onramp/refund/${refundId}`);
+
+      if (!response.success) {
+        throw new SwiftShoprError(
+          response.error || 'REFUND_ERROR',
+          response.message || 'Failed to get refund status',
+          response,
+        );
+      }
+
+      return {
+        id: response.refund.id,
+        intentId: response.refund.intent_id,
+        orderId: response.refund.order_id,
+        amount: response.refund.amount,
+        reason: response.refund.reason,
+        status: response.refund.status,
+        txHash: response.refund.tx_hash,
+        explorerUrl: response.refund.explorer_url,
+        fromAddress: response.refund.from_address,
+        toAddress: response.refund.to_address,
+        createdAt: response.refund.created_at,
+        completedAt: response.refund.completed_at,
+      };
+    },
+
+    /**
+     * List all refunds for a payment intent
+     *
+     * @param {string} intentId - Payment intent ID (UUID)
+     * @returns {Promise<Array>} List of refunds
+     */
+    async listForPayment(intentId) {
+      if (!intentId) {
+        throw new SwiftShoprError('VALIDATION_ERROR', 'intentId is required');
+      }
+
+      const response = await http.get(
+        `/api/v1/sdk/onramp/payments/${intentId}/refunds`,
+      );
+
+      return response.map((refund) => ({
+        id: refund.id,
+        amount: refund.amount,
+        reason: refund.reason,
+        status: refund.status,
+        txHash: refund.tx_hash,
+        explorerUrl: refund.explorer_url,
+        createdAt: refund.created_at,
+        completedAt: refund.completed_at,
+      }));
+    },
+
+    /**
+     * Poll for refund completion
+     *
+     * @param {string} refundId - Refund ID
+     * @param {Object} [options]
+     * @param {number} [options.timeout=600000] - Max wait time (default 10 min)
+     * @param {number} [options.interval=5000] - Poll interval (default 5s)
+     * @param {Function} [options.onStatusChange] - Callback on status change
+     * @returns {Promise<Object>} Final refund status
+     */
+    async waitForCompletion(refundId, options = {}) {
+      const timeout = options.timeout || 600000;
+      const interval = options.interval || 5000;
+      const { onStatusChange } = options;
+
+      const startTime = Date.now();
+      let lastStatus = null;
+
+      while (Date.now() - startTime < timeout) {
+        const refund = await this.get(refundId);
+
+        if (lastStatus !== refund.status) {
+          lastStatus = refund.status;
+          if (onStatusChange) {
+            onStatusChange(refund);
+          }
+        }
+
+        if (refund.status === 'completed') {
+          return refund;
+        }
+
+        if (refund.status === 'failed') {
+          throw new SwiftShoprError('REFUND_FAILED', 'Refund failed', refund);
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, interval));
+      }
+
+      throw new SwiftShoprError(
+        'TIMEOUT',
+        `Refund did not complete within ${timeout}ms`,
+      );
+    },
+  };
+}
+
+module.exports = { createRefundsAPI };