@thorprovider/adapters 4.2.0 → 4.3.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/providers-overview.md

@@ -42,6 +42,18 @@ Our primary integration, highly optimized for headless performance.
 **Status:** 🚧 In Development (Phase 1)
 Focusing on Storefront API integration for product discovery and cart.
 
+### 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:**
+- **Supported:** Products, categories (aliased as collections), warehouses/inventory, customers, orders, payment methods, delivery options, storefront context
+- **Unsupported:** Cart, checkout, customer auth/profile self-service, discount codes, fulfillment orchestration, recommendations, advanced search
+- **Rate limits:** 60 req/min + low daily limits — designed to minimize API round-trips
+- **Single-company:** No multi-tenant/storefront channel assumptions; `requiresStorefront: false`
+- **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.
@@ -62,9 +74,11 @@ graph TD
   B --> C[Medusa Provider]
   B --> D[Shopify Provider]
   B --> E[Mock Provider]
+  B --> F2[Stel Order Provider]
   C --> F[Unified Commerce Interface]
   D --> F
   E --> F
+  F2 --> F
 ```
 
 ## Design Decisions

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
@@ -63,6 +65,22 @@ Handles customer account management and secure sessions.
 - Profile and address management
 - Metadata extensions
 
+### 5. ERP Adapters (Stel Order)
+Not all providers are full storefronts. ERP adapters like **Stel Order** expose a subset of services:
+
+| Service | Stel Order Support |
+|---------|-------------------|
+| Products & Categories | ✅ Read-only catalog with inventory visibility |
+| Collections | ✅ Aliased from categories |
+| Cart & Checkout | ❌ Not supported (ERP has no cart concept) |
+| Authentication | ❌ Not supported (API-key auth only, no customer login) |
+| Customers (CRM) | ✅ Read + update via STEL clients endpoint |
+| Orders | ✅ Read sales orders; no create/cancel from adapter |
+| Payment Methods | ✅ List STEL payment options |
+| Shipping/Delivery | ✅ List STEL delivery options |
+
+Unsupported methods throw `ProviderAPIError` (501) with a clear message explaining the ERP limitation.
+
 ## Service Interactions
 
 ```mermaid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/adapters",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Framework-agnostic commerce adapters for Thor Commerce ecosystem - Multi-platform support with unified API",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -11,16 +11,18 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "development": "./src/index.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "development": "./dist/index.mjs",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.mjs"
     }
   },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "type-check": "tsc --noEmit",
-    "test": "echo \"No tests yet\" && exit 0",
+    "test": "vitest run --config vitest.config.ts",
+    "test:live": "vitest run --config vitest.config.ts src/providers/stelorder/live-smoke.test.ts",
     "generate:agent-index": "node ../../scripts/generate-package-agents-index.cjs packages/adapters @thorprovider/adapters"
   },
   "dependencies": {
@@ -31,8 +33,10 @@
     "jose": "^6.2.2"
   },
   "devDependencies": {
+    "msw": "^2.12.3",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
   },
   "repository": {
     "type": "git",

package/quick-reference.md

@@ -52,11 +52,45 @@ 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
 ```
 createProvider() → Provider instance
 ├── MedusaProvider (complete implementation)
+├── StelOrderProvider (ERP: catalog, CRM, orders — no cart/checkout/auth)
 ├── ShopifyProvider (planned)
 └── Custom providers (extensible)
 ```

package/src/factory/index.ts

@@ -17,6 +17,7 @@ import { BigCommerceProvider, type BigCommerceProviderConfig } from '../provider
 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';
@@ -33,6 +34,7 @@ export type ProviderType = ProviderTypeString;
 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 }
@@ -79,6 +81,8 @@ export function createProvider(options: ProviderFactoryConfig | RuntimeProviderC
       return new MockProvider(config);
     case 'medusa':
       return new MedusaProvider(config);
+    case 'stelorder':
+      return new StelOrderProvider(config);
     case 'shopify':
       return new ShopifyProvider(config);
     case 'bigcommerce':

package/src/index.ts

@@ -40,6 +40,7 @@ export {
 export {
   MOCK_CAPABILITIES,
   MEDUSA_CAPABILITIES,
+  STELORDER_CAPABILITIES,
   SHOPIFY_CAPABILITIES,
   BIGCOMMERCE_CAPABILITIES,
   WOOCOMMERCE_CAPABILITIES,
@@ -193,6 +194,8 @@ export {
 export {
   MedusaProvider,
   type MedusaProviderConfig,
+  StelOrderProvider,
+  type StelOrderProviderConfig,
   MockProvider,
   type MockProviderConfig,
   ShopifyProvider,

package/src/providers/index.ts

@@ -6,6 +6,9 @@
 export { MedusaProvider } from './medusa';
 export type { MedusaProviderConfig } from './medusa';
 
+export { StelOrderProvider } from './stelorder';
+export type { StelOrderProviderConfig } from './stelorder';
+
 export { ShopifyProvider } from './shopify';
 export type { ShopifyProviderConfig } from './shopify';