@thorprovider/adapters 4.2.1 → 5.0.0

package/src/types/capabilities.types.js

@@ -1,141 +0,0 @@
-"use strict";
-/**
- * @thorprovider/adapters v2.0
- * Backend Capabilities System
- *
- * Defines what operations each backend platform supports.
- * This is a compile-time capability detection system, NOT runtime feature flags.
- *
- * NOTE: BackendCapabilities interface is defined in @thorprovider/types (L1: Foundation).
- * This file re-exports it and provides platform-specific implementations.
- *
- * @see packages/core/docs/BACKEND_CAPABILITIES_ANALYSIS.md
- * @see packages/core/docs/COMMERCE_PROVIDER_ARCHITECTURE.md
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SHOPIFY_CAPABILITIES = exports.MEDUSA_CAPABILITIES = void 0;
-exports.isBackendCapabilities = isBackendCapabilities;
-exports.getCapabilityDescription = getCapabilityDescription;
-/**
- * Medusa backend capabilities
- *
- * @see https://docs.medusajs.com/api/store
- */
-exports.MEDUSA_CAPABILITIES = {
-    // Profile Management
-    updateProfile: true,
-    updateEmail: false, // Security restriction
-    changePasswordDirect: false, // Email flow only
-    changePasswordViaEmail: true,
-    deleteAccount: true, // Implemented via ThorMedusaClient
-    // Avatar
-    uploadAvatar: false,
-    avatarViaMetadata: true,
-    // Custom Attributes
-    customAttributes: true,
-    // Orders
-    fetchOrders: true,
-    cancelOrder: true,
-    // Addresses
-    manageAddresses: true,
-    defaultAddress: true,
-    // Cart/Checkout
-    applyDiscounts: true,
-    shippingCalculation: true,
-    guestCheckout: true,
-    savedPaymentMethods: false, // Depends on payment provider
-    listPaymentProviders: true,
-    regionSpecificPayments: true,
-    // Wishlist
-    wishlist: false, // Requires custom implementation
-    // Search
-    advancedSearch: true,
-    facetedFilters: true,
-    // Reviews
-    productReviews: false, // Requires custom implementation
-    // Loyalty
-    loyaltyProgram: false, // Requires custom implementation
-};
-/**
- * Shopify backend capabilities
- *
- * @see https://shopify.dev/docs/api/storefront
- */
-exports.SHOPIFY_CAPABILITIES = {
-    // Profile Management
-    updateProfile: true,
-    updateEmail: true,
-    changePasswordDirect: true,
-    changePasswordViaEmail: true,
-    deleteAccount: false, // Requires admin API
-    // Avatar
-    uploadAvatar: false,
-    avatarViaMetadata: true,
-    // Custom Attributes
-    customAttributes: true,
-    // Orders
-    fetchOrders: true,
-    cancelOrder: true,
-    // Addresses
-    manageAddresses: true,
-    defaultAddress: true,
-    // Cart/Checkout
-    applyDiscounts: true,
-    shippingCalculation: true,
-    guestCheckout: true,
-    savedPaymentMethods: true,
-    listPaymentProviders: true,
-    regionSpecificPayments: false, // Global payment methods
-    // Wishlist
-    wishlist: false, // Requires app
-    // Search
-    advancedSearch: true,
-    facetedFilters: true,
-    // Reviews
-    productReviews: false, // Requires app
-    // Loyalty
-    loyaltyProgram: false, // Requires app
-};
-/**
- * Type guard to check if an object is a valid BackendCapabilities
- */
-function isBackendCapabilities(obj) {
-    if (typeof obj !== 'object' || obj === null)
-        return false;
-    var capabilities = obj;
-    // Check required profile management capabilities
-    return (typeof capabilities.updateProfile === 'boolean' &&
-        typeof capabilities.updateEmail === 'boolean' &&
-        typeof capabilities.changePasswordDirect === 'boolean');
-}
-/**
- * Get capability description for UI display
- */
-function getCapabilityDescription(capability) {
-    var descriptions = {
-        updateProfile: 'Update profile information (name, phone)',
-        updateEmail: 'Change email address',
-        changePasswordDirect: 'Change password directly',
-        changePasswordViaEmail: 'Request password reset via email',
-        deleteAccount: 'Delete account (self-service)',
-        uploadAvatar: 'Upload profile picture',
-        avatarViaMetadata: 'Store avatar URL in metadata',
-        customAttributes: 'Custom customer attributes',
-        fetchOrders: 'View order history',
-        cancelOrder: 'Cancel orders',
-        manageAddresses: 'Add/update/delete addresses',
-        defaultAddress: 'Set default address',
-        applyDiscounts: 'Apply discount codes',
-        shippingCalculation: 'Calculate shipping rates',
-        guestCheckout: 'Checkout without account',
-        savedPaymentMethods: 'Save payment methods',
-        listPaymentProviders: 'List available payment providers',
-        regionSpecificPayments: 'Region-specific payment methods',
-        wishlist: 'Wishlist/favorites',
-        advancedSearch: 'Advanced product search',
-        facetedFilters: 'Filter by product attributes',
-        productReviews: 'Product reviews and ratings',
-        loyaltyProgram: 'Loyalty/rewards program',
-    };
-    return descriptions[capability] || capability;
-}

package/src/types/provider.js

@@ -1,9 +0,0 @@
-"use strict";
-/**
- * @thorprovider/adapters v2.0
- * Provider interface - unified commerce operations across all platforms
- *
- * NOTE: This file re-exports CommerceProvider from @thorprovider/types for backward compatibility.
- * The actual interface definition lives in @thorprovider/types (L1: Foundation).
- */
-Object.defineProperty(exports, "__esModule", { value: true });

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'");
-    }
-}