@thorprovider/adapters 3.0.2

package/src/types/capabilities.types.ts

@@ -0,0 +1,366 @@
+/**
+ * @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
+ */
+
+import type { BackendCapabilities } from '@thorprovider/types';
+
+export type { BackendCapabilities };
+
+/**
+ * Medusa backend capabilities
+ * 
+ * @see https://docs.medusajs.com/api/store
+ */
+export const MEDUSA_CAPABILITIES: Readonly<BackendCapabilities> = {
+  // 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
+ */
+export const SHOPIFY_CAPABILITIES: Readonly<BackendCapabilities> = {
+  // 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
+};
+
+/**
+ * BigCommerce backend capabilities
+ * 
+ * @see https://developer.bigcommerce.com/docs/rest-storefront
+ */
+export const BIGCOMMERCE_CAPABILITIES: Readonly<BackendCapabilities> = {
+  // Profile Management
+  updateProfile: true,
+  updateEmail: true,
+  changePasswordDirect: true,
+  changePasswordViaEmail: true,
+  deleteAccount: false,
+
+  // Avatar
+  uploadAvatar: false,
+  avatarViaMetadata: false,
+
+  // Custom Attributes
+  customAttributes: true,
+
+  // Orders
+  fetchOrders: true,
+  cancelOrder: false,  // Admin API only
+
+  // Addresses
+  manageAddresses: true,
+  defaultAddress: false,
+
+  // Cart/Checkout
+  applyDiscounts: true,
+  shippingCalculation: true,
+  guestCheckout: true,
+  savedPaymentMethods: true,
+  listPaymentProviders: true,
+  regionSpecificPayments: false,
+
+  // Wishlist
+  wishlist: true,  // Native support
+
+  // Search
+  advancedSearch: true,
+  facetedFilters: true,
+
+  // Reviews
+  productReviews: true,  // Native support
+
+  // Loyalty
+  loyaltyProgram: false,
+};
+
+/**
+ * WooCommerce backend capabilities
+ * 
+ * @see https://developer.woocommerce.com/docs/apis/store-api
+ */
+export const WOOCOMMERCE_CAPABILITIES: Readonly<BackendCapabilities> = {
+  // Profile Management
+  updateProfile: true,
+  updateEmail: true,
+  changePasswordDirect: false,  // WordPress handles auth
+  changePasswordViaEmail: true,
+  deleteAccount: false,
+
+  // Avatar
+  uploadAvatar: false,
+  avatarViaMetadata: false,  // Gravatar-based
+
+  // Custom Attributes
+  customAttributes: true,  // Via meta_data
+
+  // Orders
+  fetchOrders: true,
+  cancelOrder: true,
+
+  // Addresses
+  manageAddresses: true,
+  defaultAddress: false,  // Billing/shipping only
+
+  // Cart/Checkout
+  applyDiscounts: true,  // Coupon codes
+  shippingCalculation: true,
+  guestCheckout: true,
+  savedPaymentMethods: false,
+  listPaymentProviders: true,
+  regionSpecificPayments: false,
+
+  // Wishlist
+  wishlist: false,  // Requires plugin
+
+  // Search
+  advancedSearch: false,  // Basic WP search
+  facetedFilters: false,  // Requires plugin
+
+  // Reviews
+  productReviews: true,  // Native WP reviews
+
+  // Loyalty
+  loyaltyProgram: false,
+};
+
+/**
+ * Spree Commerce backend capabilities
+ * 
+ * @see https://docs.spreecommerce.org/api-reference
+ */
+export const SPREE_CAPABILITIES: Readonly<BackendCapabilities> = {
+  // Profile Management
+  updateProfile: true,
+  updateEmail: true,
+  changePasswordDirect: true,
+  changePasswordViaEmail: true,
+  deleteAccount: false,
+
+  // Avatar
+  uploadAvatar: false,
+  avatarViaMetadata: false,
+
+  // Custom Attributes
+  customAttributes: false,
+
+  // Orders
+  fetchOrders: true,
+  cancelOrder: true,
+
+  // Addresses
+  manageAddresses: true,
+  defaultAddress: true,
+
+  // Cart/Checkout
+  applyDiscounts: true,
+  shippingCalculation: true,
+  guestCheckout: true,
+  savedPaymentMethods: false,
+  listPaymentProviders: true,
+  regionSpecificPayments: false,
+
+  // Wishlist
+  wishlist: true,  // Native support
+
+  // Search
+  advancedSearch: false,
+  facetedFilters: true,  // Taxon-based filtering
+
+  // Reviews
+  productReviews: false,  // Requires extension
+
+  // Loyalty
+  loyaltyProgram: false,
+};
+
+/**
+ * Adobe Commerce / Magento backend capabilities
+ * 
+ * @see https://developer.adobe.com/commerce/webapi/graphql/
+ */
+export const MAGENTO_CAPABILITIES: Readonly<BackendCapabilities> = {
+  // Profile Management
+  updateProfile: true,
+  updateEmail: true,
+  changePasswordDirect: true,
+  changePasswordViaEmail: true,
+  deleteAccount: false,  // Admin only
+
+  // Avatar
+  uploadAvatar: false,
+  avatarViaMetadata: false,
+
+  // Custom Attributes
+  customAttributes: true,  // EAV model
+
+  // Orders
+  fetchOrders: true,
+  cancelOrder: true,
+
+  // Addresses
+  manageAddresses: true,
+  defaultAddress: true,
+
+  // Cart/Checkout
+  applyDiscounts: true,
+  shippingCalculation: true,
+  guestCheckout: true,
+  savedPaymentMethods: true,
+  listPaymentProviders: true,
+  regionSpecificPayments: true,  // Store-view scoped
+
+  // Wishlist
+  wishlist: true,  // Native support
+
+  // Search
+  advancedSearch: true,  // Elasticsearch/OpenSearch
+  facetedFilters: true,  // Layered navigation
+
+  // Reviews
+  productReviews: true,  // Native support
+
+  // Loyalty
+  loyaltyProgram: false,  // Requires extension
+};
+
+/**
+ * Type guard to check if an object is a valid BackendCapabilities
+ */
+export function isBackendCapabilities(obj: unknown): obj is BackendCapabilities {
+  if (typeof obj !== 'object' || obj === null) return false;
+  
+  const capabilities = obj as Partial<BackendCapabilities>;
+  
+  // Check required profile management capabilities
+  return (
+    typeof capabilities.updateProfile === 'boolean' &&
+    typeof capabilities.updateEmail === 'boolean' &&
+    typeof capabilities.changePasswordDirect === 'boolean'
+  );
+}
+
+/**
+ * Get capability description for UI display
+ */
+export function getCapabilityDescription(capability: keyof BackendCapabilities): string {
+  const descriptions: Record<keyof BackendCapabilities, string> = {
+    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/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @thorprovider/adapters v2.0
+ * Type exports - unified commerce types
+ * 
+ * Re-exports from @thorprovider/types package
+ */
+
+// Re-export all shared types from @thorprovider/types
+export type * from '@thorprovider/types';
+
+// Provider-specific types (remain in adapters)
+export type {
+  CommerceProvider,
+  ProviderConfig,
+} from './provider';
+
+// UI-ready response types (transformed for direct UI consumption)
+export type {
+  UICartItem,
+  UICartTotals,
+  UIShippingMethod,
+  UIDiscountCode,
+  UIPaymentMethod,
+} from './ui-responses';

package/src/types/provider.js

@@ -0,0 +1,9 @@
+"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/types/provider.ts

@@ -0,0 +1,9 @@
+/**
+ * @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).
+ */
+
+export type { CommerceProvider, BackendCapabilities, ProviderConfig } from '@thorprovider/types';

package/src/types/ui-responses.ts

@@ -0,0 +1,261 @@
+/**
+ * @thorprovider/adapters
+ * UI-ready response types
+ * 
+ * These types extend domain types from @thorprovider/types (L1) but with transformations
+ * applied for direct UI consumption. This is where Money→number conversions happen.
+ * 
+ * L3 (@thorprovider/components) should import these types, not the raw domain types.
+ */
+
+import type {
+  CartItem as DomainCartItem,
+  ShippingMethod as DomainShippingMethod,
+  Address,
+  Customer,
+  DiscountCode,
+  Money,
+} from '@thorprovider/types';
+
+/**
+ * UI-ready cart item with prices as numbers
+ * 
+ * Simplified cart item for UI consumption with prices in major currency units (e.g., dollars, euros).
+ * Transformed from domain CartItem by adapter services.
+ * Values come from Money.amount (decimal string in major units) parsed to number.
+ * 
+ * This is a flattened structure optimized for UI display, unlike the nested
+ * domain CartItem which follows the Shopify/Medusa structure.
+ * 
+ * @example
+ * ```typescript
+ * const uiItem: UICartItem = {
+ *   id: 'item_123',
+ *   productId: 'prod_abc',
+ *   variantId: 'var_xyz',
+ *   name: 'T-Shirt',
+ *   variant: 'Red / Large',
+ *   image: 'https://...',
+ *   price: 19.99,  // $19.99 in major units
+ *   quantity: 2,
+ *   total: 39.98,  // $39.98 in major units
+ *   isAvailable: true
+ * }
+ * ```
+ */
+export interface UICartItem {
+  /** Unique item identifier */
+  id: string;
+  
+  /** Product ID */
+  productId: string;
+  
+  /** Variant ID */
+  variantId: string;
+  
+  /** Product name */
+  name: string;
+  
+  /** Product description (optional) */
+  description?: string;
+  
+  /** Variant description (e.g., 'Red / Large') */
+  variant: string;
+  
+  /** Product image URL */
+  image: string;
+  
+  /** Unit price in major currency units (e.g., dollars, euros) */
+  price: number;
+  
+  /** Quantity in cart */
+  quantity: number;
+  
+  /** Total price (price × quantity) in major currency units */
+  total: number;
+  
+  /** Whether item is available for purchase */
+  isAvailable?: boolean;
+  
+  /** Maximum quantity available in stock */
+  maxQuantity?: number;
+}
+
+/**
+ * UI-ready cart totals with amounts as numbers
+ * 
+ * All monetary values are in major currency units (e.g., dollars, euros).
+ * Values come from Money.amount (decimal string in major units) parsed to number.
+ * Transformed from domain CartCost by adapter services.
+ * 
+ * @example
+ * ```typescript
+ * const totals: UICartTotals = {
+ *   subtotal: 59.97,    // $59.97
+ *   discount: 10.00,    // $10.00
+ *   shipping: 5.00,     // $5.00
+ *   tax: 5.39,          // $5.39
+ *   total: 60.36,       // $60.36
+ *   currency: 'USD',
+ *   itemCount: 3
+ * }
+ * ```
+ */
+export interface UICartTotals {
+  /** Subtotal before discounts/shipping/tax (in major currency units) */
+  subtotal: number;
+  
+  /** Discount amount if any (in major currency units) */
+  discount?: number;
+  
+  /** Discount code applied */
+  discountCode?: string;
+  
+  /** Shipping cost (in major currency units) */
+  shipping?: number;
+  
+  /** Tax amount (in major currency units) */
+  tax?: number;
+  
+  /** Final total amount (in major currency units) */
+  total: number;
+  
+  /** Currency code (ISO 4217, e.g., 'USD', 'EUR') */
+  currency: string;
+  
+  /** Total number of items in cart */
+  itemCount: number;
+}
+
+/**
+ * UI-ready shipping method with price as number
+ * 
+ * Price is in the currency's smallest unit.
+ * Transformed from domain ShippingMethod by adapter services.
+ * 
+ * Includes alias fields for compatibility with existing checkout components.
+ * 
+ * @example
+ * ```typescript
+ * const method: UIShippingMethod = {
+ *   id: 'ship_standard',
+ *   methodId: 'ship_standard',  // alias for id
+ *   name: 'Standard Shipping',
+ *   price: 500,  // $5.00 as 500 cents
+ *   amount: 500, // alias for price
+ *   estimatedDays: '3-5 business days'
+ * }
+ * ```
+ */
+export interface UIShippingMethod {
+  /** Unique identifier */
+  id: string;
+  
+  /** Alias for id (for compatibility with checkout components) */
+  methodId: string;
+  
+  /** Display name */
+  name: string;
+  
+  /** Shipping price in smallest currency unit */
+  price: number;
+  
+  /** Alias for price (for compatibility with checkout components) */
+  amount: number;
+  
+  /** Optional description */
+  description?: string;
+  
+  /** Estimated delivery time (human-readable string) */
+  estimatedDays?: string;
+}
+
+/**
+ * UI-ready discount code with value as number
+ * 
+ * Transformed from domain DiscountCode by adapter services.
+ * Value is in the currency's smallest unit for fixed discounts,
+ * or a percentage (0-100) for percentage discounts.
+ * 
+ * @example
+ * ```typescript
+ * // Fixed discount
+ * const fixedDiscount: UIDiscountCode = {
+ *   code: 'SAVE10',
+ *   value: 1000,  // $10.00 as 1000 cents
+ *   isPercentage: false,
+ *   description: 'Save $10 on your order'
+ * }
+ * 
+ * // Percentage discount
+ * const percentDiscount: UIDiscountCode = {
+ *   code: 'SAVE20',
+ *   value: 20,  // 20%
+ *   isPercentage: true,
+ *   description: 'Save 20% on your order'
+ * }
+ * ```
+ */
+export interface UIDiscountCode {
+  /** Discount code */
+  code: string;
+  
+  /** Discount value - either amount in smallest currency unit or percentage (0-100) */
+  value: number;
+  
+  /** Whether value is a percentage (true) or fixed amount (false) */
+  isPercentage: boolean;
+  
+  /** Human-readable description of the discount */
+  description?: string;
+  
+  /** Minimum purchase amount required (in smallest currency unit) */
+  minimumAmount?: number;
+  
+  /** Expiration date */
+  expiresAt?: Date;
+  
+  /** Maximum number of uses allowed */
+  maxUses?: number;
+  
+  /** Current usage count */
+  usageCount?: number;
+}
+
+/**
+ * UI-ready payment method for checkout selection
+ * 
+ * Simplified version of domain PaymentMethod with additional
+ * providerId field for backend-specific provider identification.
+ * 
+ * @example
+ * ```typescript
+ * const payment: UIPaymentMethod = {
+ *   id: 'pp_stripe_stripe',
+ *   providerId: 'stripe',
+ *   name: 'Credit Card',
+ *   description: 'Visa, Mastercard, American Express'
+ * }
+ * ```
+ */
+export interface UIPaymentMethod {
+  /** Unique identifier */
+  id: string;
+  
+  /** Provider identifier (e.g., 'stripe', 'paypal', 'manual') */
+  providerId: string;
+  
+  /** Display name for UI */
+  name: string;
+  
+  /** Optional description */
+  description?: string;
+}
+
+/**
+ * Re-export domain types that don't need transformation
+ * 
+ * These types are used as-is from L1 without modification.
+ * L3 can import them from here for convenience.
+ */
+export type { Address, Customer, DiscountCode };

package/src/utils/city-coordinates.ts

@@ -0,0 +1,40 @@
+/**
+ * City coordinates lookup table
+ *
+ * Lightweight approximation for geocoding without external APIs.
+ * Keep this small and extend as needed.
+ */
+
+export interface CityCoordinates {
+  lat: number;
+  lng: number;
+}
+
+const CITY_COORDINATES: Record<string, Record<string, CityCoordinates>> = {
+  US: {
+    'New York': { lat: 40.7128, lng: -74.0060 },
+    'Los Angeles': { lat: 34.0522, lng: -118.2437 },
+    Chicago: { lat: 41.8781, lng: -87.6298 },
+    Miami: { lat: 25.7617, lng: -80.1918 },
+  },
+  GB: {
+    London: { lat: 51.5074, lng: -0.1278 },
+    Manchester: { lat: 53.4808, lng: -2.2426 },
+  },
+  DE: {
+    Berlin: { lat: 52.52, lng: 13.405 },
+    Hamburg: { lat: 53.5511, lng: 9.9937 },
+  },
+  ES: {
+    Madrid: { lat: 40.4168, lng: -3.7038 },
+    Barcelona: { lat: 41.3851, lng: 2.1734 },
+  },
+};
+
+export function getCityCoordinates(city: string, countryCode: string): CityCoordinates | null {
+  const country = CITY_COORDINATES[countryCode.toUpperCase()];
+  if (!country) return null;
+
+  const cityKey = Object.keys(country).find((key) => key.toLowerCase() === city.toLowerCase());
+  return cityKey ? country[cityKey] : null;
+}