@thorprovider/adapters 4.2.1 → 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/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/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.1",
+  "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",
@@ -22,7 +22,8 @@
     "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": {

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/src/index.ts

@@ -59,9 +59,13 @@ export {
   ConfigurationError,
   ResourceNotFoundError,
   ProviderAPIError,
+  extractErrorMessage,
   createLogger,
+  fetchWithRetry,
+  createFetchWithRetry,
   type Logger,
   type LogLevel,
+  type RetryConfig,
 } from './core';
 
 // ============================================