@thorprovider/adapters 4.2.0 → 4.2.2

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/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": "4.2.0",
+  "version": "4.2.2",
   "description": "Framework-agnostic commerce adapters for Thor Commerce ecosystem - Multi-platform support with unified API",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -11,16 +11,19 @@
   "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.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": {
@@ -31,8 +34,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/publish.log

@@ -0,0 +1,93 @@
+npm warn Unknown project config "network-concurrency". This will stop working in the next major version of npm.
+npm warn publish npm auto-corrected some errors in your package.json when publishing.  Please run "npm pkg fix" to address these errors.
+npm warn publish errors corrected:
+npm warn publish "repository.url" was normalized to "git+https://github.com/thorprovider/thor-commerce.git"
+npm notice
+npm notice 📦  @thor/adapters@3.0.1
+npm notice Tarball Contents
+npm notice 629B AGENTS.md
+npm notice 9.1kB CHANGELOG.md
+npm notice 19.2kB README.md
+npm notice 73.6kB dist/index.d.mts
+npm notice 73.6kB dist/index.d.ts
+npm notice 191.6kB dist/index.js
+npm notice 377.7kB dist/index.js.map
+npm notice 187.4kB dist/index.mjs
+npm notice 377.4kB dist/index.mjs.map
+npm notice 4.7kB docs/authentication.md
+npm notice 4.3kB docs/capabilities-system.md
+npm notice 9.9kB docs/category-customization.md
+npm notice 11.0kB docs/fetch-reliability-solution.md
+npm notice 4.4kB docs/getting-started.md
+npm notice 7.8kB docs/multi-tenant-channel-scoping.md
+npm notice 4.5kB docs/profile-management.md
+npm notice 3.7kB docs/providers-overview.md
+npm notice 2.1kB docs/RETRY_SOLUTION_SUMMARY.md
+npm notice 5.2kB docs/services-overview.md
+npm notice 4.0kB docs/update-documentation.md
+npm notice 1.2kB package.json
+npm notice 6.3kB quick-reference.md
+npm notice 2.5kB src/admin/AdminAuthService.ts
+npm notice 2.4kB src/admin/AdminSessionService.ts
+npm notice 414B src/admin/index.ts
+npm notice 4.2kB src/admin/MetricsService.ts
+npm notice 2.5kB src/backend/BackendMetadataAdapter.ts
+npm notice 3.5kB src/backend/factory.ts
+npm notice 312B src/backend/index.ts
+npm notice 3.9kB src/backend/medusa/MedusaMetadataAdapter.ts
+npm notice 6.3kB src/core/errors.js
+npm notice 3.5kB src/core/errors.ts
+npm notice 11.3kB src/core/fetch-utils.js
+npm notice 6.0kB src/core/fetch-utils.ts
+npm notice 141B src/core/index.ts
+npm notice 2.3kB src/core/logger.js
+npm notice 1.1kB src/core/logger.ts
+npm notice 2.0kB src/factory/index.ts
+npm notice 4.5kB src/index.ts
+npm notice 2.7kB src/lib/money-transform.ts
+npm notice 6.2kB src/metadata/channel-scope-validation.js
+npm notice 5.1kB src/metadata/channel-scope-validation.ts
+npm notice 7.6kB src/metadata/channel-scope.js
+npm notice 8.2kB src/metadata/channel-scope.ts
+npm notice 3.3kB src/metadata/index.js
+npm notice 810B src/metadata/index.ts
+npm notice 148B src/providers/index.ts
+npm notice 30.0kB src/providers/medusa/auth.js
+npm notice 15.1kB src/providers/medusa/auth.ts
+npm notice 6.2kB src/providers/medusa/fulfillment-planner.ts
+npm notice 151.8kB src/providers/medusa/index.js
+npm notice 147.6kB src/providers/medusa/index.ts
+npm notice 184B src/providers/medusa/medusa.ts
+npm notice 11.0kB src/providers/medusa/payment.js
+npm notice 7.2kB src/providers/medusa/payment.ts
+npm notice 25.8kB src/providers/medusa/transforms.js
+npm notice 19.8kB src/providers/medusa/transforms.ts
+npm notice 5.5kB src/resilience/circuit-breaker.ts
+npm notice 238B src/resilience/index.ts
+npm notice 7.6kB src/resilience/README.md
+npm notice 4.8kB src/types/capabilities.types.js
+npm notice 4.7kB src/types/capabilities.types.ts
+npm notice 513B src/types/index.ts
+npm notice 350B src/types/provider.js
+npm notice 365B src/types/provider.ts
+npm notice 6.5kB src/types/ui-responses.ts
+npm notice 1.1kB src/utils/city-coordinates.ts
+npm notice 1.3kB src/utils/geolocation.ts
+npm notice 5.6kB src/utils/payment-utils.js
+npm notice 6.5kB src/utils/payment-utils.ts
+npm notice 357B tsconfig.json
+npm notice 370B tsup.config.ts
+npm notice Tarball Details
+npm notice name: @thor/adapters
+npm notice version: 3.0.1
+npm notice filename: thor-adapters-3.0.1.tgz
+npm notice package size: 413.9 kB
+npm notice unpacked size: 1.9 MB
+npm notice shasum: 696c58c4b5629ad1ec09336238ea157aad015e3d
+npm notice integrity: sha512-tIweHlz73prg8[...]3KYkFTyNlUX4w==
+npm notice total files: 72
+npm notice
+npm notice Publishing to https://npm.pkg.github.com with tag latest and restricted access
+npm error code E401
+npm error 401 Unauthorized - PUT https://npm.pkg.github.com/@thor%2fadapters - unauthenticated: User cannot be authenticated with the token provided.
+npm error A complete log of this run can be found in: /home/nelson/.npm/_logs/2026-04-16T15_45_37_415Z-debug-0.log

package/quick-reference.md

@@ -57,6 +57,7 @@ Framework-agnostic business logic SDK for e-commerce operations. Provides unifie
 ```
 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,
@@ -58,9 +59,13 @@ export {
   ConfigurationError,
   ResourceNotFoundError,
   ProviderAPIError,
+  extractErrorMessage,
   createLogger,
+  fetchWithRetry,
+  createFetchWithRetry,
   type Logger,
   type LogLevel,
+  type RetryConfig,
 } from './core';
 
 // ============================================
@@ -193,6 +198,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';