@thorprovider/adapters 3.0.2

package/src/utils/geolocation.ts

@@ -0,0 +1,52 @@
+/**
+ * Geolocation utilities
+ *
+ * Framework-agnostic helpers for proximity-based fulfillment.
+ */
+
+import { getCityCoordinates } from './city-coordinates';
+
+export interface Coordinates {
+  lat: number;
+  lng: number;
+}
+
+/**
+ * Calculate distance between two coordinates using the Haversine formula.
+ * @returns Distance in kilometers
+ */
+export function calculateDistance(from: Coordinates, to: Coordinates): number {
+  const R = 6371;
+  const dLat = toRad(to.lat - from.lat);
+  const dLng = toRad(to.lng - from.lng);
+
+  const a =
+    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+    Math.cos(toRad(from.lat)) *
+      Math.cos(toRad(to.lat)) *
+      Math.sin(dLng / 2) *
+      Math.sin(dLng / 2);
+
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+  return R * c;
+}
+
+function toRad(degrees: number): number {
+  return degrees * (Math.PI / 180);
+}
+
+/**
+ * Geocode an address to coordinates.
+ *
+ * This is intentionally a best-effort approximation (city + country lookup).
+ * For production-grade accuracy, integrate a real geocoding provider.
+ */
+export async function geocodeAddress(address: {
+  city?: string;
+  countryCode?: string;
+  postalCode?: string;
+}): Promise<Coordinates | null> {
+  if (!address.city || !address.countryCode) return null;
+
+  return getCityCoordinates(address.city, address.countryCode);
+}

package/src/utils/payment-utils.js

@@ -0,0 +1,152 @@
+"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'");
+    }
+}

package/src/utils/payment-utils.ts

@@ -0,0 +1,203 @@
+/**
+ * @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
+ */
+
+import type { PaymentMethod } from '@thorprovider/types';
+
+/**
+ * Backend mapping metadata stored in PaymentMethod.metadata
+ * 
+ * This metadata is added during payment method transformation
+ * to preserve the original backend-specific identifier.
+ * 
+ * @example
+ * ```typescript
+ * const metadata = {
+ *   _backendMapping: {
+ *     backend: 'medusa',
+ *     originalId: 'pp_stripe_stripe',
+ *     normalizedType: 'card'
+ *   }
+ * };
+ * ```
+ */
+export interface BackendMapping {
+  /**
+   * Backend type (e.g., 'medusa', 'shopify', 'woocommerce')
+   */
+  backend: string;
+  
+  /**
+   * Original backend-specific provider ID
+   * 
+   * Examples:
+   * - Medusa: 'pp_stripe_stripe', 'pp_paypal_paypal', 'pp_system_default'
+   * - Shopify: 'shopify_payments', 'paypal_express'
+   * - WooCommerce: 'stripe', 'paypal', 'cod'
+   */
+  originalId: string;
+  
+  /**
+   * Normalized payment method type
+   * 
+   * The frontend-friendly type we inferred from the backend ID
+   * (e.g., 'card', 'wallet', 'bank_transfer', 'cash_on_delivery')
+   */
+  normalizedType: string;
+}
+
+/**
+ * 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.
+ * }
+ * ```
+ */
+export function getBackendProviderId(method: PaymentMethod): string {
+  const mapping = method.metadata?._backendMapping as BackendMapping | undefined;
+  
+  if (!mapping) {
+    throw new Error(
+      `PaymentMethod '${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 '${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.
+ * ```
+ */
+export function validatePaymentId(id: string): void {
+  const 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: '${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'`
+    );
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/.tsbuildinfo",
+    "moduleResolution": "bundler",
+    "baseUrl": "."
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: {
+    'index': 'src/index.ts'
+  },
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  external: ['react', '@medusajs/types', '@tanstack/react-query'],
+  onSuccess: process.env.SKIP_TYPE_CHECK === 'true' ? undefined : 'tsc --noEmit --skipLibCheck'
+})