@thorprovider/adapters 4.2.0 → 4.3.0

package/src/utils/payment-utils.js

@@ -1,152 +0,0 @@
-"use strict";
-/**
- * @thorprovider/adapters - Payment Utilities
- *
- * Backend-agnostic utilities for extracting backend provider IDs from
- * normalized PaymentMethod objects using metadata.
- *
- * This solves the problem of losing backend-specific provider IDs during
- * transformation to frontend-friendly formats.
- *
- * @module payment-utils
- * @since 2.0.0
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getBackendProviderId = getBackendProviderId;
-exports.validatePaymentId = validatePaymentId;
-/**
- * Extract backend provider ID from PaymentMethod
- *
- * Uses the `_backendMapping` metadata to retrieve the original
- * backend-specific provider ID that should be sent to API calls.
- *
- * **Why this exists:**
- * During transformation, we normalize backend IDs to friendly types:
- * - Backend: 'pp_stripe_stripe' → Frontend: type 'card'
- * - Backend: 'pp_system_default' → Frontend: type 'cash_on_delivery'
- *
- * But when making API calls, we need the ORIGINAL backend ID, not the type.
- * This function extracts it from metadata.
- *
- * @param method - PaymentMethod with _backendMapping metadata
- * @returns Backend provider ID (e.g., 'pp_stripe_stripe', 'pp_system_default')
- * @throws {Error} If _backendMapping metadata is missing or invalid
- *
- * @example
- * ```typescript
- * // PaymentMethod from backend with metadata
- * const method = {
- *   id: 'pp_system_default',
- *   type: 'cash_on_delivery',
- *   name: 'Cash on Delivery',
- *   metadata: {
- *     _backendMapping: {
- *       backend: 'medusa',
- *       originalId: 'pp_system_default',
- *       normalizedType: 'cash_on_delivery'
- *     }
- *   }
- * };
- *
- * const providerId = getBackendProviderId(method);
- * // Returns: 'pp_system_default'
- *
- * // Now safe to use with backend API:
- * await commerce.initiatePaymentSession(cartId, providerId);
- * ```
- *
- * @example
- * ```typescript
- * // Handling missing metadata
- * try {
- *   const providerId = getBackendProviderId(methodWithoutMetadata);
- * } catch (error) {
- *   console.error('Payment method missing backend mapping:', error.message);
- *   // Error: PaymentMethod 'stripe' is missing _backendMapping metadata.
- *   // This is required to extract the backend provider ID.
- * }
- * ```
- */
-function getBackendProviderId(method) {
-    var _a;
-    var mapping = (_a = method.metadata) === null || _a === void 0 ? void 0 : _a._backendMapping;
-    if (!mapping) {
-        throw new Error("PaymentMethod '".concat(method.id, "' is missing _backendMapping metadata. ") +
-            "This is required to extract the backend provider ID. " +
-            "Ensure the payment method was transformed with metadata preservation. " +
-            "Check transformPaymentMethod() implementation in your provider adapter.");
-    }
-    if (!mapping.originalId) {
-        throw new Error("PaymentMethod '".concat(method.id, "' has invalid _backendMapping metadata: ") +
-            "'originalId' field is missing or empty. " +
-            "Expected structure: { _backendMapping: { backend: 'medusa', originalId: 'pp_...', normalizedType: '...' } }");
-    }
-    return mapping.originalId;
-}
-/**
- * Validate payment provider ID format
- *
- * Checks if the provider ID is a valid backend-specific identifier,
- * not a normalized type like 'card', 'wallet', etc.
- *
- * **Why this exists:**
- * Common bug: Accidentally sending normalized types to backend APIs:
- * ❌ `initiatePaymentSession(cartId, 'card')` → Backend error
- * ✅ `initiatePaymentSession(cartId, 'pp_stripe_stripe')` → Success
- *
- * This validation catches the bug at runtime with a helpful error message.
- *
- * @param id - Provider ID to validate
- * @throws {Error} If ID appears to be a normalized type instead of backend ID
- *
- * @example
- * ```typescript
- * // Valid backend IDs - pass validation:
- * validatePaymentId('pp_stripe_stripe');    // ✅ OK (Medusa)
- * validatePaymentId('pp_system_default');   // ✅ OK (Medusa)
- * validatePaymentId('shopify_payments');    // ✅ OK (Shopify)
- * validatePaymentId('stripe');              // ✅ OK (WooCommerce)
- * validatePaymentId('paypal_express');      // ✅ OK (generic)
- *
- * // Invalid (normalized types) - throw error:
- * validatePaymentId('card');                // ❌ Throws error
- * validatePaymentId('wallet');              // ❌ Throws error
- * validatePaymentId('cash_on_delivery');    // ❌ Throws error
- * ```
- *
- * @example
- * ```typescript
- * // Use before API calls:
- * async function initiatePayment(cartId: string, providerId: string) {
- *   // Validate before sending to backend
- *   validatePaymentId(providerId);
- *
- *   return await sdk.payment.initiatePaymentSession(cart, {
- *     provider_id: providerId
- *   });
- * }
- *
- * // Catches bugs early:
- * await initiatePayment(cartId, 'card');
- * // ❌ Error: Invalid payment provider ID: 'card'.
- * // This appears to be a normalized payment type, not a backend provider ID.
- * // Use getBackendProviderId() to extract the correct backend ID from PaymentMethod.
- * ```
- */
-function validatePaymentId(id) {
-    var normalizedTypes = [
-        'card',
-        'wallet',
-        'bank_transfer',
-        'buy_now_pay_later',
-        'cash_on_delivery',
-        'crypto',
-        'other'
-    ];
-    if (normalizedTypes.includes(id)) {
-        throw new Error("Invalid payment provider ID: '".concat(id, "'. ") +
-            "This appears to be a normalized payment type, not a backend provider ID. " +
-            "Use getBackendProviderId() to extract the correct backend ID from PaymentMethod. " +
-            "Expected format examples: 'pp_stripe_stripe', 'pp_system_default', 'shopify_payments', 'stripe'");
-    }
-}