@thorprovider/adapters 4.2.1 → 5.0.0

package/docs/profile-management.md

@@ -1,26 +1,32 @@
-# Profile Management
-
 ---
+title: Profile Management
+purpose: Guide for managing customer profiles using capability-aware patterns for cross-backend compatibility
 type: how-to
 tags: [profile, account, customer, metadata, avatar]
 related:
   - authentication.md
   - capabilities-system.md
   - services-overview.md
-updated: 2026-02-28
+updated: 2026-05-03
 ---
 
+# Profile Management
+
 Guide for managing customer profiles using capability-aware patterns for cross-backend compatibility.
 
 ## Prerequisites
 
 - [Authentication set up](authentication.md)
-- User logged in to access profile features
+- User logged in (`commerce.auth` available and `isAuthenticated()` returns `true`)
 
 ## Quick Example
 
 ```typescript
-import { commerce } from '@/lib/commerce';
+import { createProvider } from '@thorprovider/adapters';
+
+const commerce = createProvider({ provider: 'medusa', config: { ... } });
+
+if (!commerce.auth) throw new Error('Auth not available');
 
 // Simple profile update
 const updated = await commerce.auth.updateCustomer({
@@ -41,6 +47,10 @@ const { updateEmail, updateProfile, deleteAccount } = commerce.capabilities;
 if (updateEmail) {
   // Render email update field
 }
+
+if (updateProfile) {
+  // Render name/phone fields
+}
 ```
 
 ### Step 2: Retrieve Current Profile
@@ -48,6 +58,8 @@ if (updateEmail) {
 Fetch the customer object to populate your forms.
 
 ```typescript
+if (!commerce.auth) return;
+
 const customer = await commerce.auth.getCurrentCustomer();
 ```
 
@@ -56,18 +68,24 @@ const customer = await commerce.auth.getCurrentCustomer();
 Handle updates carefully, checking for specific field support.
 
 ```typescript
-async function handleUpdate(formData) {
-  const updateData = {};
-  
+async function handleUpdate(formData: {
+  firstName: string;
+  lastName: string;
+  email?: string;
+}) {
+  if (!commerce.auth) throw new Error('Auth not available');
+
+  const updateData: Record<string, unknown> = {};
+
   if (commerce.capabilities.updateProfile) {
     updateData.first_name = formData.firstName;
     updateData.last_name = formData.lastName;
   }
-  
-  if (commerce.capabilities.updateEmail) {
+
+  if (commerce.capabilities.updateEmail && formData.email) {
     updateData.email = formData.email;
   }
-  
+
   return await commerce.auth.updateCustomer(updateData);
 }
 ```
@@ -78,42 +96,54 @@ Handle password changes based on whether the backend supports direct or email-ba
 
 ```typescript
 if (commerce.capabilities.changePasswordDirect) {
+  // Direct password change (Shopify, Spree, Magento)
   await commerce.auth.updateCustomer({
-    current_password: 'old',
-    password: 'new',
+    password: 'NewPassword123!',
   });
+} else if (commerce.capabilities.changePasswordViaEmail) {
+  // Email-based reset (Medusa v2)
+  await commerce.auth.requestPasswordReset(customer.email);
 }
 ```
 
-## ✅ DO's
-
-1. **Check Capabilities First:** Avoid rendering buttons for features the backend doesn't support.
-2. **Use Metadata for Extensions:** Store extra info like `avatar_url` or `notifications` in `customer.metadata`.
-3. **Handle Errors explicitly:** Distinguish between `EMAIL_TAKEN` and generic update errors.
-4. **Validate on Client:** Use patterns/regex for phone and email before sending to the adapter.
-5. **Protect UI with Loading States:** Backend operations can take time; show a spinner.
-
-## ❌ DONT's
+### Step 5: Account Deletion
 
-1. **Don't assume all backends are equal:** Medusa v2 has different capabilities than Shopify or WooCommerce.
-2. **Don't hardcode profile fields:** Use the `Customer` interface from `@thorprovider/adapters`.
-3. **Don't ignore account deletion:** Provide a way for users to delete their account if `deleteAccount` is true.
-4. **Don't send sensitive data in metadata:** Metadata is often visible to the user and sometimes less secure.
-5. **Don't forget to re-fetch profile:** After a successful update, the local customer state should be refreshed.
+```typescript
+if (commerce.capabilities.deleteAccount && commerce.auth) {
+  await commerce.auth.deleteCustomerAccount();
+}
+```
 
-## Common Patterns
+## Avatar Management
 
-### Metadata-based Avatar Management
-Since many backends don't support native avatars, use an external service (S3/Cloudinary) and store the URL in metadata.
+Most backends don't support native avatar uploads. Use an external service (S3, Cloudinary) and store the URL in metadata.
 
 ```typescript
-await commerce.auth.updateCustomer({
-  metadata: { avatar_url: 'https://...' }
-});
+// Check capability first
+if (commerce.capabilities.avatarViaMetadata && commerce.auth) {
+  await commerce.auth.updateCustomer({
+    metadata: { avatar_url: 'https://cdn.example.com/avatars/user-123.jpg' },
+  });
+}
 ```
 
-### Adaptive Profile Form
-Render only the fields supported by the current provider.
+> ⚠️ **Backend Disparity:** `uploadAvatar` (native file upload) is `false` for all current providers. Use `avatarViaMetadata` instead.
+
+## ✅ DO's
+
+1. **Check `commerce.capabilities` first:** Avoid rendering buttons for features the backend doesn't support.
+2. **Use metadata for extensions:** Store extra info like `avatar_url` or notification preferences in `customer.metadata`.
+3. **Handle errors explicitly:** Distinguish between `EMAIL_TAKEN` and generic update errors.
+4. **Validate on client:** Use patterns/regex for phone and email before sending to the adapter.
+5. **Re-fetch after update:** After a successful update, refresh the local customer state.
+
+## ❌ DONT's
+
+1. **Don't assume all backends are equal:** Medusa v2 has different capabilities than Shopify or WooCommerce.
+2. **Don't hardcode profile fields:** Use the `UpdateCustomerData` type from `@thorprovider/adapters`.
+3. **Don't ignore account deletion:** Provide a way for users to delete their account if `deleteAccount` is `true`.
+4. **Don't send sensitive data in metadata:** Metadata is often visible to the user and may be less secure.
+5. **Don't call `commerce.auth.updateCustomer` without checking `commerce.auth`:** It may be undefined.
 
 ## Common Errors & Solutions
 
@@ -128,16 +158,16 @@ Render only the fields supported by the current provider.
 ## Common Pitfalls
 
 > ⚠️ **Pitfall 1: Metadata Overwrites**
-> Some backends overwrite the entire metadata object instead of merging. Always fetch the current ones first if you want to preserve existing fields.
+> Some backends overwrite the entire metadata object instead of merging. Always fetch the current metadata first if you want to preserve existing fields.
 
 > ⚠️ **Pitfall 2: Password Complexity**
-> Backends have different password requirements. Let the backend validate and handle the error message.
+> Backends have different password requirements. Let the backend validate and surface the error message.
 
 ## Troubleshooting
 
 | Issue | Solution |
 |-------|----------|
-| Profile data not saving | Check if the user session is still active |
+| Profile data not saving | Check if the user session is still active (`isAuthenticated()`) |
 | Metadata field missing | Ensure the key exists in the backend's allowed metadata list |
 | 403 Forbidden | User might not have permission to update their own profile |
 

package/docs/services-overview.md

@@ -1,6 +1,6 @@
-# Services Overview
-
 ---
+title: Services Overview
+purpose: Overview of adapter services and provider capabilities
 type: guide
 tags: [architecture, services, commerce, api, architecture]
 related:
@@ -10,6 +10,8 @@ related:
 updated: 2026-02-28
 ---
 
+# Services Overview
+
 Overview of the functional services provided by Thor adapters and how they interact to provide a unified e-commerce interface.
 
 ## Overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/adapters",
-  "version": "4.2.1",
+  "version": "5.0.0",
   "description": "Framework-agnostic commerce adapters for Thor Commerce ecosystem - Multi-platform support with unified API",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/quick-reference.md

@@ -52,6 +52,39 @@ 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,15 +93,5 @@ export function createBackendMetadataAdapter(
     return new MedusaMetadataAdapter(medusa);
   }
 
-  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}`);
+  throw new Error(`Unsupported provider for metadata adapter: ${provider}. Only 'medusa' is currently supported.`);
 }

package/src/factory/index.ts

@@ -1,57 +1,93 @@
 /**
- * @thorprovider/adapters v2.0
- * Provider Factory - Create commerce providers dynamically
+ * @thorprovider/adapters v5.0
+ * Provider Factory - Dynamic registry pattern
  *
- * 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
+ * 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.
  */
 
 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);
+}
+
 /**
- * Supported provider types (imported from @thorprovider/types L1)
- * Kept for backward compatibility; prefer ProviderTypeString from @thorprovider/types
+ * Get all registered provider type strings.
  */
-export type ProviderType = ProviderTypeString;
+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 & {});
 
 /**
- * Provider configuration discriminated union
+ * Provider configuration discriminated union (built-in providers)
  */
 export type ProviderFactoryConfig =
   | { provider: 'mock'; config: MockProviderConfig }
   | { provider: 'medusa'; config: MedusaProviderConfig }
   | { provider: 'stelorder'; config: StelOrderProviderConfig }
-  | { provider: 'shopify'; config: ShopifyProviderConfig }
-  | { provider: 'bigcommerce'; config: BigCommerceProviderConfig }
-  | { provider: 'woocommerce'; config: WooCommerceProviderConfig }
-  | { provider: 'spree'; config: SpreeProviderConfig }
-  | { provider: 'magento'; config: MagentoProviderConfig };
+  | { provider: string; config: Record<string, unknown> };
 
 /**
- * Runtime provider configuration (accepts any ProviderTypeString from env vars)
+ * Runtime provider configuration (accepts any registered provider string)
  */
 export type RuntimeProviderConfig = {
-  provider: ProviderTypeString;
+  provider: string;
   config: Record<string, unknown>;
 };
 
+// ============================================
+// Factory
+// ============================================
+
 /**
- * Create a commerce provider instance
- * 
+ * Create a commerce provider instance from the registry.
+ *
  * @example
  * ```ts
  * const commerce = createProvider({
@@ -61,42 +97,28 @@ 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 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));
+
+  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?`
+    );
   }
+
+  return factory(options.config);
 }
 
 /**

package/src/index.ts

@@ -41,11 +41,6 @@ export {
   MOCK_CAPABILITIES,
   MEDUSA_CAPABILITIES,
   STELORDER_CAPABILITIES,
-  SHOPIFY_CAPABILITIES,
-  BIGCOMMERCE_CAPABILITIES,
-  WOOCOMMERCE_CAPABILITIES,
-  SPREE_CAPABILITIES,
-  MAGENTO_CAPABILITIES,
   isBackendCapabilities,
   getCapabilityDescription,
 } from './types/capabilities.types';
@@ -60,8 +55,11 @@ export {
   ResourceNotFoundError,
   ProviderAPIError,
   createLogger,
+  fetchWithRetry,
+  extractErrorMessage,
   type Logger,
   type LogLevel,
+  type RetryConfig,
 } from './core';
 
 // ============================================
@@ -183,6 +181,8 @@ export type {
 // ============================================
 export {
   createProvider,
+  registerProvider,
+  getRegisteredProviders,
   isProviderType,
   type ProviderType,
   type ProviderFactoryConfig,
@@ -198,14 +198,4 @@ 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/index.ts

@@ -1,5 +1,5 @@
 /**
- * @thorprovider/adapters v2.0
+ * @thorprovider/adapters v5.0
  * Providers index
  */
 
@@ -9,20 +9,5 @@ export type { MedusaProviderConfig } from './medusa';
 export { StelOrderProvider } from './stelorder';
 export type { StelOrderProviderConfig } from './stelorder';
 
-export { ShopifyProvider } from './shopify';
-export type { ShopifyProviderConfig } from './shopify';
-
-export { BigCommerceProvider } from './bigcommerce';
-export type { BigCommerceProviderConfig } from './bigcommerce';
-
-export { WooCommerceProvider } from './woocommerce';
-export type { WooCommerceProviderConfig } from './woocommerce';
-
-export { SpreeProvider } from './spree';
-export type { SpreeProviderConfig } from './spree';
-
-export { MagentoProvider } from './magento';
-export type { MagentoProviderConfig } from './magento';
-
 export { MockProvider } from './mock';
 export type { MockProviderConfig } from './mock';