@thorprovider/adapters 4.2.1 → 4.2.2

package/.turbo/turbo-build.log

@@ -0,0 +1,18 @@
+CLI Building entry: {"index":"src/index.ts"}
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /home/nelson/dev/thorprovider/repos/thorcommerce/packages/adapters/tsup.config.ts
+CLI Target: esnext
+CLI Cleaning output folder
+CJS Build start
+ESM Build start
+ESM dist/index.mjs     337.86 KB
+ESM dist/index.mjs.map 692.12 KB
+ESM ⚡️ Build success in 91ms
+CJS dist/index.js     342.55 KB
+CJS dist/index.js.map 692.49 KB
+CJS ⚡️ Build success in 99ms
+DTS Build start
+DTS ⚡️ Build success in 2836ms
+DTS dist/index.d.ts  95.95 KB
+DTS dist/index.d.mts 95.95 KB

package/.turbo/turbo-test.log

@@ -0,0 +1 @@
+No tests yet

package/AGENTS.md

@@ -1 +1 @@
-<!-- ADAPTERS-AGENTS-MD-START -->[@thorprovider/adapters Docs]|root: ./adapters|CRITICAL: Framework-agnostic business logic only. Never import Next.js or React. Check IMPORT_GUIDE.md for proper usage patterns.|To regenerate: yarn workspace @thorprovider/adapters generate:agent-index|.:{README.md,quick-reference.md}|docs:{RETRY_SOLUTION_SUMMARY.md,authentication.md,capabilities-system.md,category-customization.md,fetch-reliability-solution.md,getting-started.md,multi-tenant-channel-scoping.md,profile-management.md,providers-overview.md,services-overview.md,update-documentation.md}|src/resilience:{README.md}<!-- ADAPTERS-AGENTS-MD-END -->
+<!-- ADAPTERS-AGENTS-MD-START -->[@thorprovider/adapters Docs]|root: ./adapters|CRITICAL: Framework-agnostic business logic only. Never import Next.js or React. Check IMPORT_GUIDE.md for proper usage patterns.|To regenerate: yarn workspace @thorprovider/adapters generate:agent-index|.:{PROVIDER_IMPLEMENTATION_ANALYSIS.md,README.md,quick-reference.md}|docs:{RETRY_SOLUTION_SUMMARY.md,authentication.md,capabilities-system.md,category-customization.md,fetch-reliability-solution.md,getting-started.md,multi-tenant-channel-scoping.md,profile-management.md,providers-overview.md,services-overview.md,update-documentation.md}|src/resilience:{README.md}<!-- ADAPTERS-AGENTS-MD-END -->

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.2.2
+
+### Patch Changes
+
+- Align the package surface with current consumers and keep the resilience helpers available through the root export.
+
 ## 4.2.1
 
 ### Patch Changes

package/PROVIDER_IMPLEMENTATION_ANALYSIS.md

@@ -0,0 +1,659 @@
+# @thorprovider/adapters Package Analysis Report
+
+## Executive Summary
+
+The adapters package provides a unified commerce API across multiple e-commerce platforms. **3 providers are fully/substantially implemented, 5 are stub implementations with basic method skeletons.**
+
+### Provider Implementation Status
+
+- ✅ **Medusa v2**: ~4,239 LOC - PRODUCTION READY
+- ✅ **Mock**: ~427 LOC - Fixture-backed for testing/previews
+- ✅ **Stel Order ERP**: ~685 LOC - Catalog/CRM read-only (no cart/checkout/auth)
+- 🟡 **Shopify**: ~444 LOC - 60% implemented (cart/products done, orders/admin stub)
+- 🟡 **BigCommerce**: ~315 LOC - 50% implemented (cart/products done, orders/inventory/admin stub)
+- 🟡 **WooCommerce**: ~310 LOC - 50% implemented (cart/products done, orders/admin stub)
+- 🟡 **Spree**: ~344 LOC - 60% implemented (cart/products done, inventory/admin stub)
+- 🟡 **Magento**: ~387 LOC - 50% implemented (cart/products done, orders/admin stub)
+
+---
+
+## 1. PROVIDER IMPLEMENTATIONS
+
+### ✅ MEDUSA v2 (FULLY IMPLEMENTED)
+
+**Status**: Production Ready | 105 public async methods
+
+**File**: `src/providers/medusa/index.ts`
+
+#### Implemented Methods:
+
+**Products & Catalog**:
+- `getProduct(handle)` - ✅
+- `getProducts(options)` - ✅
+- `getProductRecommendations(productId)` - ✅
+- `searchProductsAdvanced(options)` - ✅
+- `getAvailableFilters(options)` - ✅
+- `getCollection(handle)` - ✅
+- `getCollections(options)` - ✅
+- `getCollectionProducts(handle, options)` - ✅
+- `getCategory(idOrHandle)` - ✅
+- `getCategories(options)` - ✅
+- `getCategoryProducts(handle, options)` - ✅
+- `getRegions()` - ✅
+
+**Cart Operations**:
+- `createCart(options)` - ✅
+- `getCart(cartId)` - ✅
+- `addToCart(cartId, lines)` - ✅
+- `removeFromCart(cartId, lineIds)` - ✅
+- `updateCart(cartId, lines)` - ✅
+- `applyDiscountCode(cartId, code)` - ✅
+- `removeDiscountCode(cartId, code)` - ✅
+
+**Checkout**:
+- `completeCheckout(cartId)` - ✅
+- `getShippingMethods(cartId)` - ✅
+- `addShippingMethod(cartId, methodId)` - ✅
+- `initiatePaymentSession(cartId, providerId)` - ✅
+- `updateShippingAddress(cartId, address)` - ✅
+- `updateBillingAddress(cartId, address)` - ✅
+- `getRegionCountries(regionId)` - ✅
+
+**Orders**:
+- `getOrders(options)` - ✅
+- `getOrder(orderId)` - ✅
+- `cancelOrder(orderId)` - ✅
+- `createRefund(orderId)` - ✅
+- `createFulfillment(orderId)` - ✅
+
+**Customers** (with JWT auth):
+- `getCustomers(options)` - ✅
+- `getCustomer(customerId)` - ✅
+- `updateCustomer(customerId, data)` - ✅
+- `getCustomerOrders(customerId)` - ✅
+- `getAdminCustomers(options)` - ✅
+- `getAdminCustomer(customerId)` - ✅
+
+**Inventory/Admin**:
+- `getStockLocations(params)` - ✅ (requires admin config)
+- `checkInventoryLevels(variantId)` - ✅
+- `validateCartStock(cartId)` - ✅
+- `getFulfillmentOptions(cartId)` - ✅
+- `getAdminOrders(options)` - ✅
+- `getAdminProducts(options)` - ✅
+- `getAdminProductStatuses(options)` - ✅
+- `getAvailableProductStatuses()` - ✅
+
+**Designer Config** (Custom):
+- `getStorefrontConfig()` - ✅
+- `getDesignerConfig()` - ✅
+- `getAdminDesignerConfig(salesChannelId)` - ✅
+- `updateAdminDesignerConfig(salesChannelId, config)` - ✅
+- `restoreAdminDesignerConfig(salesChannelId, version)` - ✅
+- `getAdminRegions()` - ✅
+- `getAdminOrder(orderId)` - ✅
+- `createDraftOrder(data)` - ✅
+- `undraftOrder(orderId)` - ✅
+
+**Special Features**:
+- Dynamic capabilities fetching (GET `/store/thor/capabilities`)
+- Multi-tenant sales channel scoping (NEXT_PUBLIC_SALES_CHANNEL_ID)
+- Automatic retry logic with exponential backoff
+- JWT/session auth with auto-token refresh
+- Channel-scoped data isolation
+
+**Capabilities**: 21/21 ✅ FULL SUPPORT
+
+---
+
+### ✅ MOCK PROVIDER (PRODUCTION READY)
+
+**Status**: For testing, previews, backend-optional storefronts
+
+**File**: `src/providers/mock/index.ts`
+
+**Implemented**:
+- `getProduct()` ✅
+- `getProducts()` ✅
+- `getProductRecommendations()` ✅
+- `getCollection()` ✅
+- `getCollections()` ✅
+- `getCollectionProducts()` ✅
+- `getCategory()` ✅
+- `getCategories()` ✅
+- `getCategoryProducts()` ✅
+- `createCart()` ✅
+- `getCart()` ✅
+- `addToCart()` ✅
+- `removeFromCart()` ✅
+- `updateCart()` ✅
+- `completeCheckout()` ✅
+- `getShippingMethods()` ✅
+- `applyDiscountCode()` ✅
+- `getPaymentMethods()` ✅
+- `getOrders()` ✅
+- `getOrder()` ✅
+- `getStorefrontContext()` ✅
+
+**Capabilities**: 12/21 partial support (covers basic flows)
+
+---
+
+### ✅ STEL ORDER ERP ADAPTER
+
+**Status**: Production Ready | Catalog/CRM read-only (no cart/checkout/auth)
+
+**File**: `src/providers/stelorder/index.ts`
+
+**Implemented**:
+- `getProduct()` ✅
+- `getProducts()` ✅ (client-side text search, server-side category filter)
+- `getCategory()` ✅
+- `getCategories()` ✅
+- `getCategoryProducts()` ✅
+- `getCustomers()` ✅ (read-only)
+- `getCustomer()` ✅ (read-only)
+- `getOrders()` ✅ (read-only, supports filters)
+- `getPaymentMethods()` ✅ (delivery/payment options)
+- `getShippingMethods()` ✅ (delivery options)
+- `getAddresses()` ✅ (customer addresses)
+- `updateCustomerAddresses()` ✅ (write support)
+- `createStockLocation()` ✅ (warehouse mapping)
+- `getStockLocations()` ✅
+- `checkInventoryLevels()` ✅
+
+**NOT Implemented**:
+- ❌ `createCart()` - ERP doesn't support carts
+- ❌ `addToCart()` - N/A
+- ❌ `completeCheckout()` - N/A
+- ❌ `auth` service - No customer auth
+- ❌ Orders write operations (cancel, refund, fulfillment) - Read-only ERP
+
+**Capabilities**: 6/21 (catalog + CRM read, no cart/auth)
+
+---
+
+## 2. STUB IMPLEMENTATIONS (PARTIAL)
+
+### 🟡 SHOPIFY PROVIDER
+
+**File**: `src/providers/shopify/index.ts` (444 LOC)
+
+**Implementation Level**: ~60%
+
+**Implemented**:
+- ✅ `getProduct()` - Via GraphQL
+- ✅ `getProducts()` - Via GraphQL with sort
+- ✅ `getProductRecommendations()` - Via GraphQL
+- ✅ `getCollection()` - Via GraphQL
+- ✅ `getCollections()` - Via GraphQL
+- ✅ `getCollectionProducts()` - Via GraphQL
+- ✅ `createCart()` - GraphQL mutation
+- ✅ `getCart()` - GraphQL query
+- ✅ `addToCart()` - GraphQL mutation
+- ✅ `removeFromCart()` - GraphQL mutation
+- ✅ `updateCart()` - GraphQL mutation
+- ✅ `applyDiscountCode()` - GraphQL mutation
+- ✅ `removeDiscountCode()` - GraphQL mutation
+
+**Return Empty/Stub** (❌):
+- `getCategory()` - Returns `undefined` with warning
+- `getCategories()` - Returns `[]` (Shopify uses collections, not categories)
+- `getCategoryProducts()` - Returns `[]`
+- `completeCheckout()` - Throws error (hosted checkout only)
+- `getShippingMethods()` - Returns `[]` (hosted checkout)
+- `getRegionCountries()` - Returns `[]`
+- `addShippingMethod()` - Throws error
+- `initiatePaymentSession()` - Throws error
+- `getOrders()` - Warns "requires Customer Account API" → returns `[]`
+- `getPaymentMethods()` - Returns `[]` (hosted checkout)
+- `getStockLocations()` - Returns `[]`
+- `checkInventoryLevels()` - Returns `[]`
+- `validateCartStock()` - Returns `{ allAvailable: true, unavailableItems: [] }`
+- `getFulfillmentOptions()` - Returns `[]`
+- `cancelOrder()` - Throws error (admin API required)
+- `createFulfillment()` - Throws error
+- `createRefund()` - Throws error
+- `getAdminOrders()` - Returns `{ orders: [], count: 0 }`
+
+**Capabilities**: 9/21 ✅ Correct
+
+**Notes**:
+- Uses Storefront API (not Admin API)
+- No native categories (uses collections)
+- Hosted checkout model (can't programmatically complete)
+- Orders require Customer Account API upgrade
+
+---
+
+### 🟡 BIGCOMMERCE PROVIDER
+
+**File**: `src/providers/bigcommerce/index.ts` (315 LOC)
+
+**Implementation Level**: ~50%
+
+**Implemented**:
+- ✅ `getProduct()` - REST Storefront API
+- ✅ `getProducts()` - REST Storefront API
+- ✅ `getCollection()` - Maps to categories
+- ✅ `getCollections()` - REST API
+- ✅ `getCollectionProducts()` - REST API
+- ✅ `getCategory()` - Alias to getCollection
+- ✅ `getCategories()` - Alias to getCollections
+- ✅ `getCategoryProducts()` - Alias to getCollectionProducts
+- ✅ `createCart()` - REST API
+- ✅ `getCart()` - REST API
+- ✅ `addToCart()` - REST API
+- ✅ `removeFromCart()` - REST API
+- ✅ `updateCart()` - REST API
+- ✅ `applyDiscountCode()` - REST API (coupons)
+- ✅ `removeDiscountCode()` - REST API
+
+**Return Empty/Stub** (❌):
+- `getProductRecommendations()` - Returns `[]` (no Storefront API)
+- `completeCheckout()` - Throws error (Embedded Checkout only)
+- `getShippingMethods()` - Returns `[]`
+- `getRegionCountries()` - Returns `[]`
+- `addShippingMethod()` - Throws error
+- `initiatePaymentSession()` - Throws error
+- `getOrders()` - Returns `[]`
+- `getPaymentMethods()` - Returns `[]`
+- `getStockLocations()` - Returns `[]`
+- `checkInventoryLevels()` - Returns `[]`
+- `validateCartStock()` - Returns `{ allAvailable: true }`
+- `getFulfillmentOptions()` - Returns `[]`
+- `cancelOrder()` - Throws error
+- `createFulfillment()` - Throws error
+- `createRefund()` - Throws error
+- `getAdminOrders()` - Returns `{ orders: [], count: 0 }`
+
+**Capabilities**: 8/21 ✅ Correct
+
+**Notes**:
+- Storefront API only (no customer/order endpoints)
+- Embedded checkout model
+- Categories mapped to collections
+
+---
+
+### 🟡 WOOCOMMERCE PROVIDER
+
+**File**: `src/providers/woocommerce/index.ts` (310 LOC)
+
+**Implementation Level**: ~50%
+
+**Implemented**:
+- ✅ `getProduct()` - Store API
+- ✅ `getProducts()` - Store API
+- ✅ `getCollection()` - Categories
+- ✅ `getCollections()` - Categories
+- ✅ `getCollectionProducts()` - Categories
+- ✅ `getCategory()` - Alias
+- ✅ `getCategories()` - Alias
+- ✅ `getCategoryProducts()` - Alias
+- ✅ `createCart()` - Store API
+- ✅ `getCart()` - Store API (cart endpoint)
+- ✅ `addToCart()` - Store API
+- ✅ `removeFromCart()` - Store API
+- ✅ `updateCart()` - Store API
+- ✅ `completeCheckout()` - Store API ✅
+- ✅ `applyDiscountCode()` - Store API
+- ✅ `removeDiscountCode()` - Store API
+- ✅ `addShippingMethod()` - Store API
+
+**Return Empty/Stub** (❌):
+- `getProductRecommendations()` - Returns `[]`
+- `getShippingMethods()` - Returns `[]`
+- `getRegionCountries()` - Returns `[]`
+- `initiatePaymentSession()` - Noop (handled during checkout)
+- `getOrders()` - Returns `[]`
+- `getPaymentMethods()` - Returns `[]`
+- `getStockLocations()` - Returns `[]`
+- `checkInventoryLevels()` - Returns `[]`
+- `validateCartStock()` - Returns `{ allAvailable: true }`
+- `getFulfillmentOptions()` - Returns `[]`
+- `cancelOrder()` - Throws error (REST API auth required)
+- `createFulfillment()` - Throws error
+- `createRefund()` - Throws error
+- `getAdminOrders()` - Returns `{ orders: [], count: 0 }`
+
+**Capabilities**: 8/21 ✅ Correct
+
+**Notes**:
+- Dual API: Store API (unauthenticated cart/products) + REST API v3 (authenticated orders)
+- Store API handles most operations
+- Orders require admin credentials
+
+---
+
+### 🟡 SPREE PROVIDER
+
+**File**: `src/providers/spree/index.ts` (344 LOC)
+
+**Implementation Level**: ~60%
+
+**Implemented**:
+- ✅ `getProduct()` - JSON:API storefront
+- ✅ `getProducts()` - JSON:API with filtering
+- ✅ `getCollection()` - Taxons (JSON:API)
+- ✅ `getCollections()` - JSON:API
+- ✅ `getCollectionProducts()` - JSON:API filtering
+- ✅ `getCategory()` - Alias to getCollection
+- ✅ `getCategories()` - Alias to getCollections
+- ✅ `getCategoryProducts()` - Alias
+- ✅ `createCart()` - JSON:API mutation
+- ✅ `getCart()` - JSON:API query
+- ✅ `addToCart()` - JSON:API mutation
+- ✅ `removeFromCart()` - JSON:API delete
+- ✅ `updateCart()` - JSON:API PATCH
+- ✅ `completeCheckout()` - JSON:API
+- ✅ `getShippingMethods()` - JSON:API (shipping rates)
+- ✅ `addShippingMethod()` - JSON:API
+- ✅ `applyDiscountCode()` - JSON:API
+- ✅ `removeDiscountCode()` - JSON:API
+- ✅ `getOrders()` - Attempts `account/orders`
+
+**Return Empty/Stub** (❌):
+- `getProductRecommendations()` - Returns `[]`
+- `getRegionCountries()` - Returns `[]`
+- `initiatePaymentSession()` - Noop
+- `getPaymentMethods()` - Returns `[]` (attempts checkout API)
+- `getStockLocations()` - Returns `[]`
+- `checkInventoryLevels()` - Returns `[]`
+- `validateCartStock()` - Returns `{ allAvailable: true }`
+- `getFulfillmentOptions()` - Returns `[]`
+- `cancelOrder()` - Throws error (admin API required)
+- `createFulfillment()` - Throws error
+- `createRefund()` - Throws error
+- `getAdminOrders()` - Returns `{ orders: [], count: 0 }`
+
+**Capabilities**: 8/21 ✅ Correct
+
+**Notes**:
+- JSON:API format (not REST/GraphQL)
+- Guest token + bearer token auth support
+- `getOrders()` attempts but may fail if customer not authenticated
+
+---
+
+### 🟡 MAGENTO PROVIDER
+
+**File**: `src/providers/magento/index.ts` (387 LOC)
+
+**Implementation Level**: ~50%
+
+**Implemented**:
+- ✅ `getProduct()` - GraphQL by URL key
+- ✅ `getProducts()` - GraphQL with sort/pagination
+- ✅ `getCollection()` - GraphQL categories by URL key
+- ✅ `getCollections()` - GraphQL categories
+- ✅ `getCollectionProducts()` - GraphQL filtered
+- ✅ `getCategory()` - Alias
+- ✅ `getCategories()` - Alias
+- ✅ `getCategoryProducts()` - Alias
+- ✅ `createCart()` - GraphQL mutation
+- ✅ `getCart()` - GraphQL query
+- ✅ `addToCart()` - GraphQL mutation
+- ✅ `removeFromCart()` - GraphQL mutation (loop per item)
+- ✅ `updateCart()` - GraphQL mutation
+- ✅ `applyDiscountCode()` - GraphQL mutation
+- ✅ `removeDiscountCode()` - GraphQL mutation
+- ✅ `getOrders()` - GraphQL (requires customerToken)
+
+**Return Empty/Stub** (❌):
+- `getProductRecommendations()` - Returns `[]`
+- `completeCheckout()` - Throws error (multi-step process)
+- `getShippingMethods()` - Returns `[]` (multi-step)
+- `getRegionCountries()` - Returns `[]`
+- `addShippingMethod()` - Throws error
+- `initiatePaymentSession()` - Noop
+- `getPaymentMethods()` - Returns `[]`
+- `getStockLocations()` - Returns `[]`
+- `checkInventoryLevels()` - Returns `[]`
+- `validateCartStock()` - Returns `{ allAvailable: true }`
+- `getFulfillmentOptions()` - Returns `[]`
+- `cancelOrder()` - Throws error (admin API)
+- `createFulfillment()` - Throws error
+- `createRefund()` - Throws error
+- `getAdminOrders()` - Returns `{ orders: [], count: 0 }`
+
+**Capabilities**: 8/21 ✅ Correct
+
+**Notes**:
+- GraphQL-first approach
+- Checkout is multi-step (not single-call completeCheckout)
+- Requires customerToken for orders
+
+---
+
+## 3. CORE TYPES & INTERFACES
+
+**File**: `src/types/provider.ts`
+
+Re-exports from `@thorprovider/types`:
+- `CommerceProvider` interface
+- `BackendCapabilities` interface
+- `ProviderConfig` type
+
+**File**: `src/types/capabilities.types.ts`
+
+Defines 21 capabilities across 5 categories:
+
+**Profile Management** (6):
+- `updateProfile`
+- `updateEmail`
+- `changePasswordDirect`
+- `changePasswordViaEmail`
+- `deleteAccount`
+
+**Avatar** (2):
+- `uploadAvatar`
+- `avatarViaMetadata`
+
+**Cart/Checkout** (7):
+- `customAttributes`
+- `applyDiscounts`
+- `shippingCalculation`
+- `guestCheckout`
+- `savedPaymentMethods`
+- `listPaymentProviders`
+- `regionSpecificPayments`
+
+**Products** (4):
+- `advancedSearch`
+- `facetedFilters`
+- `productReviews`
+- `wishlist`
+
+**Loyalty** (1):
+- `loyaltyProgram`
+
+**Orders** (2):
+- `fetchOrders`
+- `cancelOrder`
+
+**Addresses** (2):
+- `manageAddresses`
+- `defaultAddress`
+
+---
+
+## 4. MISSING IMPLEMENTATIONS SUMMARY
+
+### ✅ Fully Implemented
+- **Medusa**: All 105+ methods, all 21 capabilities
+- **Mock**: 21 methods, 12 capabilities (sufficient for testing)
+- **Stel Order**: Catalog + CRM focused, 14 methods, 6 capabilities
+
+### 🟡 Significantly Missing (All Stubs)
+
+**Inventory/Stock Management** (❌ All stubs except Medusa):
+- `getStockLocations()` - Empty in: Shopify, BigCommerce, WooCommerce, Spree, Magento
+- `checkInventoryLevels()` - Empty in: Shopify, BigCommerce, WooCommerce, Spree, Magento
+- `validateCartStock()` - Returns hardcoded true in all stubs
+- `getFulfillmentOptions()` - Empty in: Shopify, BigCommerce, WooCommerce, Spree, Magento
+
+**Admin Operations** (❌ All stubs):
+- `getAdminOrders()` - Returns `{ orders: [], count: 0 }` in all stubs
+- `cancelOrder()` - Throws "requires admin API" error in all stubs
+- `createFulfillment()` - Throws error in all stubs
+- `createRefund()` - Throws error in all stubs
+- `getAdminProducts()` - Not implemented in any stub
+
+**Customer/Order Management** (❌ Partial stubs):
+- `getOrders()` - Empty in: Shopify, BigCommerce, WooCommerce
+- `getPaymentMethods()` - Empty in: Shopify, BigCommerce, Magento
+
+**Shipping** (❌ All stubs):
+- `getShippingMethods()` - Returns `[]` in: Shopify, BigCommerce, Magento
+- `addShippingMethod()` - Throws error in: Shopify, BigCommerce, Magento
+- `getRegionCountries()` - Returns `[]` in all stubs
+
+**Checkout** (❌ Partial):
+- `completeCheckout()` - Throws error in: Shopify (hosted), BigCommerce (embedded), Magento (multi-step)
+- `initiatePaymentSession()` - Noop/throws in all stubs
+
+**Discovery** (❌ All stubs):
+- `getProductRecommendations()` - Returns `[]` in all stubs
+
+---
+
+## 5. ERROR HANDLING PATTERNS
+
+### Medusa (Best Practice):
+```typescript
+private async withRetry<T>(
+  fn: () => Promise<T>,
+  operationName: string,
+  retryConfig?: RetryConfig
+): Promise<T> {
+  // Exponential backoff + jitter
+  // Circuit breaker patterns
+  // Detailed error logging
+}
+```
+
+### Shopify/BigCommerce/WooCommerce/Spree/Magento:
+```typescript
+try {
+  // Fetch operation
+} catch (error) {
+  // Log or return []
+}
+```
+
+**Issue**: Limited error context in stubs; should use `ProviderAPIError` consistently.
+
+---
+
+## 6. ADMIN SERVICES
+
+**File**: `src/admin/`
+
+- `AdminAuthService.ts` - Session/JWT management
+- `AdminSessionService.ts` - Session persistence
+- `MetricsService.ts` - Order/product metrics
+
+**Note**: These are utilities, not provider-level admin APIs. Actual admin endpoints are in provider implementations (Medusa only).
+
+---
+
+## 7. COMPARISON AGAINST THOR API CONTRACT
+
+### Expected Endpoints (from Thor Commerce API):
+
+#### Storefront API ✅
+| Method | Medusa | Shopify | BigCommerce | WooCommerce | Spree | Magento | Mock |
+|--------|--------|---------|-------------|------------|-------|---------|------|
+| `getProducts()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `getProduct()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `getCategories()` | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `getCategory()` | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `getCollections()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `getCollection()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+#### Cart & Checkout ✅
+| Method | Medusa | Shopify | BigCommerce | WooCommerce | Spree | Magento | Mock |
+|--------|--------|---------|-------------|------------|-------|---------|------|
+| `createCart()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `getCart()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `addToCart()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `removeFromCart()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `updateCart()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `applyDiscountCode()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `removeDiscountCode()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `completeCheckout()` | ✅ | ❌* | ❌* | ✅ | ✅ | ❌* | ✅ |
+
+**\*** Hosted checkout models (Shopify, BigCommerce, Magento) cannot complete programmatically
+
+#### Orders 🟡
+| Method | Medusa | Shopify | BigCommerce | WooCommerce | Spree | Magento | Mock |
+|--------|--------|---------|-------------|------------|-------|---------|------|
+| `getOrders()` | ✅ | ❌ | ❌ | ❌ | ⚠️ | ✅* | ✅ |
+| `getOrder()` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| `cancelOrder()` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+
+**\*** Requires customerToken
+
+#### Admin 🟡
+| Method | Medusa | Shopify | BigCommerce | WooCommerce | Spree | Magento | Mock |
+|--------|--------|---------|-------------|------------|-------|---------|------|
+| `getAdminOrders()` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `getAdminProducts()` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `createFulfillment()` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `createRefund()` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+#### Inventory 🟡
+| Method | Medusa | Shopify | BigCommerce | WooCommerce | Spree | Magento | Mock |
+|--------|--------|---------|-------------|------------|-------|---------|------|
+| `getStockLocations()` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `checkInventoryLevels()` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| `validateCartStock()` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+---
+
+## SUMMARY OF FINDINGS
+
+### Overall Implementation Status
+
+**Tier 1 - Production Ready**:
+- Medusa: 105+ methods, 21/21 capabilities
+- Mock: 21 methods, 12/21 capabilities (sufficient)
+
+**Tier 2 - Partial Implementation**:
+- Shopify: ~40 methods, 9/21 capabilities (storefront-only API)
+- BigCommerce: ~35 methods, 8/21 capabilities (storefront-only API)
+- WooCommerce: ~35 methods, 8/21 capabilities (storefront + basic checkout)
+- Spree: ~40 methods, 8/21 capabilities (JSON:API with guest checkout)
+- Magento: ~35 methods, 8/21 capabilities (GraphQL-first, multi-step checkout)
+
+**Tier 3 - Catalog-Only**:
+- Stel Order: 14 methods, 6/21 capabilities (catalog + CRM read-only)
+
+### Key Gaps Across All Non-Medusa Providers
+
+❌ **Inventory/Stock Management**: No stock location or inventory level data
+❌ **Admin Operations**: No order management, fulfillment, or refund operations
+❌ **Payment Methods Listing**: Returns empty except Spree (which attempts)
+❌ **Product Recommendations**: Returns empty across all stubs
+❌ **Shipping Methods**: Limited/missing in most
+❌ **Programmatic Checkout Completion**: Hosted models (Shopify, BigCommerce, Magento) throw errors
+
+### Medusa Advantages
+
+✅ Admin SDK integration (secret key support)
+✅ Inventory & fulfillment tracking
+✅ Dynamic capabilities fetching
+✅ Sales channel scoping (multi-tenant)
+✅ Complete order lifecycle (create, cancel, refund, fulfill)
+✅ Custom storefront/designer config endpoints
+✅ Retry logic with exponential backoff
+
+### Recommendations
+
+1. **Prioritize**: Orders API for Shopify (requires Customer Account API upgrade in Shopify)
+2. **Inventory**: BigCommerce, WooCommerce need inventory endpoints research
+3. **Admin APIs**: All stubs need admin SDK integration (currently blocked)
+4. **Error Handling**: Standardize error context across providers
+5. **Testing**: Implement smoke tests for each provider (Stel Order has live-smoke.test.ts example)
+