@thorprovider/adapters 5.0.0 → 5.0.2

package/docs/RETRY_SOLUTION_SUMMARY.md

@@ -17,7 +17,7 @@ Errores frecuentes `Failed to fetch products: fetch failed` en el V0 starter al
 
 ### 1. Módulo de Retry Logic (`fetch-utils.ts`)
 - **Ubicación**: `packages/adapters/src/core/fetch-utils.ts`
-- **Importación**: `import { fetchWithRetry } from '@thorprovider/adapters'` (no subpath exports)
+- **Importación**: utilidad interna — no está re-exportada desde `@thorprovider/adapters`. Úsala dentro del paquete como `import { fetchWithRetry } from '../core/fetch-utils'`.
 - **Funcionalidad**:
   - Reintentos automáticos con exponential backoff
   - Timeout configurable (10s por defecto)

package/docs/authentication.md

@@ -186,33 +186,7 @@ await commerce.auth.deleteAddress(address.id);
 | Login works but profile fails | Ensure `commerce.auth.getCurrentCustomer()` is called after login |
 | Infinite login loop | Check cookie path and domain settings on the backend |
 
-## Multi-Tenant: Linking Customer to Sales Channel
-
-After login or registration, call `linkCustomerToChannel()` to associate the customer with the storefront's sales channel. This is **required** for the customer to appear in the admin panel of the correct tenant and is idempotent.
-
-```typescript
-if (!commerce.auth) throw new Error('Auth not available');
-
-const { customer } = await commerce.auth.login({
-  email: 'user@example.com',
-  password: 'SecurePassword123!',
-});
-
-// Link the customer to the sales channel resolved from the publishable key
-const { linked, reason } = await commerce.auth.linkCustomerToChannel();
-// linked === true   → new link created
-// linked === true, reason === 'already_linked' → idempotent — no action needed
-```
-
-**Throws:**
-- `ProviderAPIError('NOT_AUTHENTICATED', 401)` — login must succeed first
-- `ProviderAPIError('CHANNEL_RESOLUTION_FAILED', 400)` — publishable key doesn't map to a channel
-- `ProviderAPIError('CONFIGURATION_ERROR')` — provider instantiated without `baseUrl`/`publishableKey`
-
-**Provider support:** Medusa only. Shopify and other stubs return `{ linked: false, reason: 'not_applicable' }`.
-
 ## Next Steps
 
 - [Profile Management](profile-management.md)
 - [Services Overview](services-overview.md)
-- [Multi-Tenant Channel Scoping](multi-tenant-channel-scoping.md)

package/docs/capabilities-system.md

@@ -6,7 +6,7 @@ tags: [architecture, capabilities, backend, detection]
 related:
   - providers-overview.md
   - services-overview.md
-updated: 2026-02-28
+updated: 2026-05-23
 ---
 
 # Capabilities System
@@ -37,27 +37,52 @@ if (commerce.capabilities.updateEmail) {
 | `changePasswordViaEmail` | `boolean` | Supports `requestPasswordReset` method. |
 | `deleteAccount` | `boolean` | Supports `deleteAccount` method. |
 | `uploadAvatar` | `boolean` | Supports native file upload for avatars. |
+| `avatarViaMetadata` | `boolean` | Can store avatar URL in customer metadata/attributes. |
+| `customAttributes` | `boolean` | Supports custom customer attributes/metadata. |
 
-### Cart Operations
+### Order Management
 
 | Capability | Type | Description |
 |------------|------|-------------|
-| `cartPromoCode` | `boolean` | Can apply discount/promo codes to cart. |
-| `cartGiftCards` | `boolean` | Supports gift card application. |
-| `cartNotes` | `boolean` | Supports order/cart notes. |
-| `cartCustomAttributes` | `boolean` | Supports metadata/attributes at cart level. |
+| `fetchOrders` | `boolean` | Can fetch customer order history. |
+| `cancelOrder` | `boolean` | Can cancel orders before fulfillment. |
 
-### Product & Discovery
+### Address Management
 
 | Capability | Type | Description |
 |------------|------|-------------|
-| `productVariants` | `boolean` | Backend supports multiple variants per product. |
-| `productCategories` | `boolean` | Supports nested categories or collections. |
-| `productInventory` | `boolean` | Real-time inventory tracking available. |
-| `productDigital` | `boolean` | Supports digital/downloadable products. |
-| `productReviews` | `boolean` | Native review system support. |
+| `manageAddresses` | `boolean` | Can add/update/delete shipping addresses. |
+| `defaultAddress` | `boolean` | Can set a default shipping address. |
 
-## Type Definitions
+### Cart & Checkout
+
+| Capability | Type | Description |
+|------------|------|-------------|
+| `applyDiscounts` | `boolean` | Can apply discount codes to cart. |
+| `shippingCalculation` | `boolean` | Can calculate shipping rates before checkout. |
+| `guestCheckout` | `boolean` | Supports checkout without an account. |
+| `savedPaymentMethods` | `boolean` | Can save payment methods for future use. |
+| `listPaymentProviders` | `boolean` | Can list available payment providers dynamically. |
+| `regionSpecificPayments` | `boolean` | Payment providers vary by region. |
+
+### Discovery & Search
+
+| Capability | Type | Description |
+|------------|------|-------------|
+| `advancedSearch` | `boolean` | Supports full-text / filtered product search. |
+| `facetedFilters` | `boolean` | Supports faceted filtering by attributes. |
+
+### Social & Loyalty
+
+| Capability | Type | Description |
+|------------|------|-------------|
+| `productReviews` | `boolean` | Native product reviews/ratings system. |
+| `wishlist` | `boolean` | Native wishlist/favorites feature. |
+| `loyaltyProgram` | `boolean` | Native loyalty/rewards program. |
+
+## Type Definition (source of truth)
+
+> Canonical source: `packages/types/src/commerce-provider.ts` — `BackendCapabilities`
 
 ```typescript
 export interface BackendCapabilities {
@@ -68,28 +93,33 @@ export interface BackendCapabilities {
   changePasswordViaEmail: boolean;
   deleteAccount: boolean;
   uploadAvatar: boolean;
-  
-  // Avatar Extensions
   avatarViaMetadata: boolean;
-  
-  // Cart
-  cartPromoCode: boolean;
-  cartGiftCards: boolean;
-  cartNotes: boolean;
-  cartCustomAttributes: boolean;
-  
-  // Products
-  productVariants: boolean;
-  productCategories: boolean;
-  productInventory: boolean;
-  productDigital: boolean;
+  customAttributes: boolean;
+
+  // Orders
+  fetchOrders: boolean;
+  cancelOrder: boolean;
+
+  // Addresses
+  manageAddresses: boolean;
+  defaultAddress: boolean;
+
+  // Cart / Checkout
+  applyDiscounts: boolean;
+  shippingCalculation: boolean;
+  guestCheckout: boolean;
+  savedPaymentMethods: boolean;
+  listPaymentProviders: boolean;
+  regionSpecificPayments: boolean;
+
+  // Discovery
+  advancedSearch: boolean;
+  facetedFilters: boolean;
+
+  // Social / Loyalty
   productReviews: boolean;
-  
-  // Auth Integration
-  authJWT: boolean;
-  authSession: boolean;
-  authOAuth: boolean;
-  authPasswordless: boolean;
+  wishlist: boolean;
+  loyaltyProgram: boolean;
 }
 ```
 
@@ -111,15 +141,15 @@ return (
 async function handleAvatarUpdate(file: File) {
   if (caps.uploadAvatar) {
     return await commerce.auth.uploadAvatar(file);
-  } 
-  
+  }
+
   if (caps.avatarViaMetadata) {
     const url = await externalUpload(file);
     return await commerce.auth.updateCustomer({
       metadata: { avatar_url: url }
     });
   }
-  
+
   throw new Error('Avatar updates not supported on this backend');
 }
 ```

package/docs/getting-started.md

@@ -17,7 +17,7 @@ Quick setup guide for integrating Thor adapters into your project. Start with `m
 ## Prerequisites
 
 - Node.js 18+
-- Yarn 4+ (PnP mode)
+- Yarn 4+ (this monorepo currently uses the `node-modules` linker)
 - Optional: access to a Medusa.js v2 backend
 - Optional: Medusa Publishable API Key
 

package/docs/providers-overview.md

@@ -30,20 +30,26 @@ Thor Adapters eliminate these problems by wrapping the data layer in a consisten
 
 ## Current Support Matrix
 
+The `createProvider` factory currently accepts these provider identifiers:
+
+- `mock`
+- `medusa`
+- `stelorder`
+- `shopify`
+- `bigcommerce`
+- `woocommerce`
+- `spree`
+- `magento`
+
+The package docs explicitly describe these currently documented integrations:
+
 ### Mock
-**Status:** ✅ Production Ready
 Fixture-backed provider for local development, previews, design-mode storefront work, and backend-optional scaffolds.
 
-### Medusa (v2.0)
-**Status:** ✅ Production Ready
-Our primary integration, highly optimized for headless performance.
-
-### Shopify
-**Status:** 🚧 In Development (Phase 1)
-Focusing on Storefront API integration for product discovery and cart.
+### Medusa
+Primary storefront integration used by the checked-in `@thorprovider/core` package.
 
 ### Stel Order
-**Status:** ✅ ERP Adapter (v1)
 Single-company ERP integration for catalog, categories, inventory visibility, customers (STEL clients), sales orders, and payment/delivery option listing.
 
 **Scope & Limitations:**
@@ -54,9 +60,7 @@ Single-company ERP integration for catalog, categories, inventory visibility, cu
 - **No variants:** STEL products are single-SKU; the adapter creates one synthetic variant per product
 - **Client-side search:** STEL has no fulltext search; `getProducts({ query })` filters in-memory after fetch
 
-### WooCommerce
-**Status:** 🗓️ Planned
-Targeting the REST API for hybrid headless setups.
+For the other accepted provider identifiers, verify source-level capability coverage before treating them as production-ready.
 
 ## Conceptual Foundation
 
@@ -102,4 +106,3 @@ graph TD
 
 - [Reference: Capabilities System](capabilities-system.md)
 - [How-to: Getting Started](getting-started.md)
-- [Workflow: Add New Provider](../../../docs/workflows/legacy/add-provider.md)

package/docs/update-documentation.md

@@ -1,23 +1,25 @@
-# Update Documentation
-
 ---
+title: Update Documentation
+purpose: Guidelines for updating @thorprovider/adapters documentation correctly
 type: how-to
 tags: [documentation, maintenance, adapters, standards, copilot]
 related:
   - ../../../docs/templates/README.md
-  - ../../../docs/update-documentation.md
-updated: 2026-02-28
+  - ../../../docs/standards/documentation.md
+updated: 2026-05-23
 ---
 
+# Update Documentation
+
 **Specific guidelines for updating @thorprovider/adapters documentation.**
 
-Global guidelines: [docs/update-documentation.md](../../../docs/update-documentation.md)
+Global guidelines: [docs/standards/documentation.md](../../../docs/standards/documentation.md)
 
 ## Prerequisites
 
-- Read [global guidelines](../../../docs/update-documentation.md) for doc types and templates
+- Read [global guidelines](../../../docs/standards/documentation.md) for doc types and templates
 - Understand the [Providers System](providers-overview.md) and [Capabilities System](capabilities-system.md)
-- Ensure understanding of the [Adapter Strategy](../../ARCHITECTURE.md) (Strategy Pattern)
+- Ensure understanding of the [Architecture Overview](../../../docs/architecture/overview.md) (Strategy Pattern)
 
 ## Step-by-Step Process for Adapters
 
@@ -109,5 +111,5 @@ async function performTask() {
 
 ## Next Steps
 
-- [global update-documentation.md](../../../docs/update-documentation.md)
+- [global documentation standards](../../../docs/standards/documentation.md)
 - [How-to: Getting Started](getting-started.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/adapters",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Framework-agnostic commerce adapters for Thor Commerce ecosystem - Multi-platform support with unified API",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -22,13 +22,14 @@
     "dev": "tsup --watch",
     "type-check": "tsc --noEmit",
     "test": "vitest run --config vitest.config.ts",
-    "test:live": "vitest run --config vitest.config.ts src/providers/stelorder/live-smoke.test.ts",
+    "test:live": "vitest run --config vitest.live.config.ts src/providers/stelorder/live-smoke.test.ts",
+    "test:live:medusa": "vitest run --config vitest.live.config.ts src/providers/medusa/live-smoke.test.ts",
     "generate:agent-index": "node ../../scripts/generate-package-agents-index.cjs packages/adapters @thorprovider/adapters"
   },
   "dependencies": {
-    "@medusajs/js-sdk": "2.11.3",
-    "@medusajs/types": "2.11.3",
-    "@thorprovider/types": "^3.0.0",
+    "@medusajs/js-sdk": "2.16.0",
+    "@medusajs/types": "2.16.0",
+    "@thorprovider/types": "^4.0.0",
     "bcryptjs": "^3.0.3",
     "jose": "^6.2.2"
   },

package/quick-reference.md

@@ -52,39 +52,6 @@ Framework-agnostic business logic SDK for e-commerce operations. Provides unifie
 - **Collections**: Product collections/categories
 - **Customer**: Authentication, profile management
 - **Orders**: Order history, details, tracking
-- **Auth — Multi-Tenant**: `linkCustomerToChannel()` — links authenticated customer to sales channel (Medusa only)
-
-### Admin Client (Medusa only)
-`provider.admin` — available when `adminConfig.apiKey` is set. Exposes 15 methods for the `/admin/thor/` endpoints:
-```typescript
-const commerce = createProvider({ provider: 'medusa', config: { ..., adminConfig: { apiKey: '...' } } })
-if (!commerce.admin) throw new Error('Admin not configured')
-
-// Sales Channel — Customers / API Keys / Categories
-await commerce.admin.getChannelCustomers(salesChannelId, { limit, offset })
-await commerce.admin.getChannelApiKeys(salesChannelId)
-await commerce.admin.getChannelCategories(salesChannelId, { limit, offset, include_descendants })
-
-// Category ↔ Sales Channel assignments
-await commerce.admin.getCategorySalesChannels(categoryId)
-await commerce.admin.assignCategoryToChannels(categoryId, { sales_channel_ids: [...] })
-await commerce.admin.unassignCategoryFromChannels(categoryId, { sales_channel_ids: [...] })
-
-// Collection ↔ Sales Channel assignments
-await commerce.admin.getCollectionSalesChannels(collectionId)
-await commerce.admin.assignCollectionToChannels(collectionId, { sales_channel_ids: [...] })
-await commerce.admin.unassignCollectionFromChannels(collectionId, { sales_channel_ids: [...] })
-
-// Storefront Config (visual theme, SEO defaults)
-await commerce.admin.getStorefrontConfig(salesChannelId)
-await commerce.admin.updateStorefrontConfig(salesChannelId, { theme_accent_color, logo_url, currency_code, seo_defaults })
-
-// Site Designer Config (page builder config with history)
-await commerce.admin.getSiteConfig(salesChannelId)
-await commerce.admin.updateSiteConfig(salesChannelId, { config: { ... } })
-await commerce.admin.getSiteConfigHistory(salesChannelId, { limit, offset })
-await commerce.admin.restoreSiteConfig(salesChannelId, version)
-```
 
 ### Provider Architecture
 ```

package/src/backend/factory.ts

@@ -93,5 +93,15 @@ export function createBackendMetadataAdapter(
     return new MedusaMetadataAdapter(medusa);
   }
 
-  throw new Error(`Unsupported provider for metadata adapter: ${provider}. Only 'medusa' is currently supported.`);
+  if (provider === 'shopify') {
+    // TODO: Implement Shopify metadata adapter
+    throw new Error('Shopify metadata adapter not yet implemented');
+  }
+
+  if (provider === 'woocommerce') {
+    // TODO: Implement WooCommerce metadata adapter
+    throw new Error('WooCommerce metadata adapter not yet implemented');
+  }
+
+  throw new Error(`Unsupported provider: ${provider}`);
 }

package/src/factory/index.ts

@@ -1,93 +1,57 @@
 /**
- * @thorprovider/adapters v5.0
- * Provider Factory - Dynamic registry pattern
+ * @thorprovider/adapters v2.0
+ * Provider Factory - Create commerce providers dynamically
  *
- * Providers register themselves at import time via `registerProvider()`.
- * The factory no longer statically imports every backend — only the ones
- * the consumer explicitly imports will be available.
- *
- * Built-in providers (medusa, stelorder, mock) are registered automatically.
+ * This factory is bound to SupportedProviderType from @thorprovider/types (L1).
+ * When adding a new provider:
+ * 1. Update SupportedProviderType enum in packages/types/src/provider.ts
+ * 2. Add new discriminated union case here
+ * 3. Create packages/adapters/src/providers/[platform]/
+ * 4. Implement CommerceProvider interface
  */
 
 import type { CommerceProvider } from '../types';
 import { MedusaProvider, type MedusaProviderConfig } from '../providers/medusa';
+import { ShopifyProvider, type ShopifyProviderConfig } from '../providers/shopify';
+import { BigCommerceProvider, type BigCommerceProviderConfig } from '../providers/bigcommerce';
+import { WooCommerceProvider, type WooCommerceProviderConfig } from '../providers/woocommerce';
+import { SpreeProvider, type SpreeProviderConfig } from '../providers/spree';
+import { MagentoProvider, type MagentoProviderConfig } from '../providers/magento';
 import { StelOrderProvider, type StelOrderProviderConfig } from '../providers/stelorder';
 import { MockProvider, type MockProviderConfig } from '../providers/mock';
 import { ProviderNotFoundError, ConfigurationError } from '../core/errors';
 import type { ProviderTypeString } from '@thorprovider/types';
 
-// ============================================
-// Registry
-// ============================================
-
-type ProviderFactory = (config: any) => CommerceProvider;
-
-const registry = new Map<string, ProviderFactory>();
-
-/**
- * Register a provider factory for a given type string.
- * Call this to make a provider available to `createProvider()`.
- *
- * @example
- * ```ts
- * import { registerProvider } from '@thorprovider/adapters';
- * import { MyProvider } from './my-provider';
- *
- * registerProvider('my-provider', (config) => new MyProvider(config));
- * ```
- */
-export function registerProvider(type: string, factory: ProviderFactory): void {
-  registry.set(type, factory);
-}
-
 /**
- * Get all registered provider type strings.
+ * Supported provider types (imported from @thorprovider/types L1)
+ * Kept for backward compatibility; prefer ProviderTypeString from @thorprovider/types
  */
-export function getRegisteredProviders(): string[] {
-  return Array.from(registry.keys());
-}
-
-// ============================================
-// Built-in registrations
-// ============================================
-
-registerProvider('mock', (config) => new MockProvider(config));
-registerProvider('medusa', (config) => new MedusaProvider(config));
-registerProvider('stelorder', (config) => new StelOrderProvider(config));
-
-// ============================================
-// Types
-// ============================================
-
-/**
- * Supported provider types
- */
-export type ProviderType = ProviderTypeString | (string & {});
+export type ProviderType = ProviderTypeString;
 
 /**
- * Provider configuration discriminated union (built-in providers)
+ * Provider configuration discriminated union
  */
 export type ProviderFactoryConfig =
   | { provider: 'mock'; config: MockProviderConfig }
   | { provider: 'medusa'; config: MedusaProviderConfig }
   | { provider: 'stelorder'; config: StelOrderProviderConfig }
-  | { provider: string; config: Record<string, unknown> };
+  | { provider: 'shopify'; config: ShopifyProviderConfig }
+  | { provider: 'bigcommerce'; config: BigCommerceProviderConfig }
+  | { provider: 'woocommerce'; config: WooCommerceProviderConfig }
+  | { provider: 'spree'; config: SpreeProviderConfig }
+  | { provider: 'magento'; config: MagentoProviderConfig };
 
 /**
- * Runtime provider configuration (accepts any registered provider string)
+ * Runtime provider configuration (accepts any ProviderTypeString from env vars)
  */
 export type RuntimeProviderConfig = {
-  provider: string;
+  provider: ProviderTypeString;
   config: Record<string, unknown>;
 };
 
-// ============================================
-// Factory
-// ============================================
-
 /**
- * Create a commerce provider instance from the registry.
- *
+ * Create a commerce provider instance
+ * 
  * @example
  * ```ts
  * const commerce = createProvider({
@@ -97,28 +61,42 @@ export type RuntimeProviderConfig = {
  *     publishableKey: process.env.MEDUSA_PUBLISHABLE_KEY,
  *   }
  * });
+ * 
+ * const products = await commerce.getProducts();
  * ```
  */
 export function createProvider(options: ProviderFactoryConfig | RuntimeProviderConfig): CommerceProvider {
   if (!options || !options.provider) {
     throw new ConfigurationError('Provider type is required');
   }
-
+  
   if (!options.config) {
     throw new ConfigurationError('Provider configuration is required');
   }
-
-  const factory = registry.get(options.provider);
-
-  if (!factory) {
-    const available = getRegisteredProviders().join(', ');
-    throw new ProviderNotFoundError(
-      `Provider "${options.provider}" is not registered. Available: ${available}. ` +
-      `Did you forget to import the provider package?`
-    );
+  
+  const config = options.config as any;
+  
+  switch (options.provider) {
+    case 'mock':
+      return new MockProvider(config);
+    case 'medusa':
+      return new MedusaProvider(config);
+    case 'stelorder':
+      return new StelOrderProvider(config);
+    case 'shopify':
+      return new ShopifyProvider(config);
+    case 'bigcommerce':
+      return new BigCommerceProvider(config);
+    case 'woocommerce':
+      return new WooCommerceProvider(config);
+    case 'spree':
+      return new SpreeProvider(config);
+    case 'magento':
+      return new MagentoProvider(config);
+    
+    default:
+      throw new ProviderNotFoundError(String((options as any).provider));
   }
-
-  return factory(options.config);
 }
 
 /**

package/src/index.ts

@@ -41,6 +41,11 @@ export {
   MOCK_CAPABILITIES,
   MEDUSA_CAPABILITIES,
   STELORDER_CAPABILITIES,
+  SHOPIFY_CAPABILITIES,
+  BIGCOMMERCE_CAPABILITIES,
+  WOOCOMMERCE_CAPABILITIES,
+  SPREE_CAPABILITIES,
+  MAGENTO_CAPABILITIES,
   isBackendCapabilities,
   getCapabilityDescription,
 } from './types/capabilities.types';
@@ -54,9 +59,10 @@ export {
   ConfigurationError,
   ResourceNotFoundError,
   ProviderAPIError,
+  extractErrorMessage,
   createLogger,
   fetchWithRetry,
-  extractErrorMessage,
+  createFetchWithRetry,
   type Logger,
   type LogLevel,
   type RetryConfig,
@@ -181,8 +187,6 @@ export type {
 // ============================================
 export {
   createProvider,
-  registerProvider,
-  getRegisteredProviders,
   isProviderType,
   type ProviderType,
   type ProviderFactoryConfig,
@@ -198,4 +202,14 @@ export {
   type StelOrderProviderConfig,
   MockProvider,
   type MockProviderConfig,
+  ShopifyProvider,
+  type ShopifyProviderConfig,
+  BigCommerceProvider,
+  type BigCommerceProviderConfig,
+  WooCommerceProvider,
+  type WooCommerceProviderConfig,
+  SpreeProvider,
+  type SpreeProviderConfig,
+  MagentoProvider,
+  type MagentoProviderConfig,
 } from './providers';

package/src/providers/bigcommerce/bigcommerce.ts

@@ -0,0 +1,6 @@
+/**
+ * @thorprovider/adapters — BigCommerce Provider exports
+ */
+export { BigCommerceProvider } from './index';
+export type { BigCommerceProviderConfig } from './index';
+export * from './transforms';