@thorprovider/adapters 4.2.1 → 4.3.0

package/src/providers/medusa/index.ts

@@ -49,6 +49,7 @@ import { validatePaymentId } from '../../utils/payment-utils';
 import { transformProduct, transformCart, transformCollection, transformCategory, transformOrder, transformCustomer, transformStockLocation, transformInventoryLevel, transformAddress, transformStorefrontConfig } from './transforms';
 import { MedusaAuthProvider } from './auth';
 import { getPaymentMethods } from './payment';
+import { MedusaAdminClient } from './admin';
 import {
   buildChannelScopeMetadata,
   filterByChannel,
@@ -163,6 +164,19 @@ export class MedusaProvider implements CommerceProvider {
    * Only created when adminConfig.apiKey is provided.
    */
   private sdkAdmin?: Medusa;
+
+  /**
+   * Admin client for Thor multi-tenant endpoints (`/admin/thor/`).
+   * Available when `adminConfig.apiKey` is provided.
+   *
+   * @example
+   * ```typescript
+   * const { customers } = await commerce.admin.getChannelCustomers('sc_01JXXXXX');
+   * const { api_keys } = await commerce.admin.getChannelApiKeys('sc_01JXXXXX');
+   * await commerce.admin.updateStorefrontConfig('sc_01JXXXXX', { theme_accent_color: '#EF4444', ... });
+   * ```
+   */
+  public readonly admin?: MedusaAdminClient;
   /** Cached distinct product status values — rarely changes, cached for process lifetime */
   private _cachedProductStatuses: string[] | null = null;
 
@@ -253,12 +267,18 @@ export class MedusaProvider implements CommerceProvider {
         debug: config.debug ?? false,
         // No publishableKey or auth config: this instance is admin-only, no JWT needed
       });
+      // Admin client for Thor multi-tenant custom endpoints (/admin/thor/)
+      (this as any).admin = new MedusaAdminClient({
+        baseUrl: config.baseUrl,
+        apiKey: config.adminConfig.apiKey,
+        debug: config.debug,
+      });
       this.logger.info('[Admin Auth] Dedicated admin SDK instance created with API key');
     }
 
     // Initialize auth provider if config is provided
     if (config.auth) {
-      this.auth = new MedusaAuthProvider(this.sdk, config.auth, config.debug);
+      this.auth = new MedusaAuthProvider(this.sdk, config.auth, config.debug, config.baseUrl, config.publishableKey);
       this.logger.info('Auth provider initialized');
     }
 

package/src/providers/shopify/auth.ts

@@ -399,4 +399,10 @@ export class ShopifyAuthProvider implements AuthProvider {
   async deleteCustomerAccount(): Promise<void> {
     throw new ProviderAPIError('Shopify customer self-service deletion requires Admin API and is not supported.', 'shopify', 501);
   }
+
+  async linkCustomerToChannel(): Promise<{ linked: boolean; reason?: string }> {
+    // Shopify does not have the concept of Thor sales channels.
+    // Return a no-op response so multi-tenant flows don't break when running against Shopify.
+    return { linked: false, reason: 'not_applicable' };
+  }
 }

package/src/resilience/README.md

@@ -1,3 +1,14 @@
+---
+title: Resilience Patterns
+purpose: Documents the Circuit Breaker and retry patterns for robust backend integration
+type: reference
+tags: [resilience, circuit-breaker, retry, fetch, patterns]
+related:
+  - ../../docs/fetch-reliability-solution.md
+  - ../../docs/RETRY_SOLUTION_SUMMARY.md
+updated: 2026-05-03
+---
+
 # Resilience Patterns
 
 **Framework-agnostic resilience patterns for robust backend integration.**
@@ -10,10 +21,17 @@ This module provides enterprise-grade resilience patterns for handling backend f
 
 ---
 
-## 📦 Export
+## 📦 Exports
 
 ```typescript
-import { CircuitBreaker, backendCircuitBreaker } from '@thorprovider/adapters/resilience';
+import {
+  CircuitBreaker,
+  backendCircuitBreaker,
+  CircuitBreakerOpenError,
+  type CircuitState,
+  type CircuitBreakerConfig,
+  type CircuitBreakerStats,
+} from '@thorprovider/adapters';
 ```
 
 ---
@@ -53,7 +71,7 @@ The Circuit Breaker pattern prevents cascading failures when the backend is unav
 ### Basic Usage
 
 ```typescript
-import { CircuitBreaker } from '@thorprovider/adapters/resilience';
+import { CircuitBreaker } from '@thorprovider/adapters';
 
 const breaker = new CircuitBreaker({
   failureThreshold: 5,      // Open after 5 failures
@@ -63,7 +81,7 @@ const breaker = new CircuitBreaker({
 
 // With fallback
 const data = await breaker.execute(
-  () => fetch('/api/data'),
+  () => fetch('/api/data').then(r => r.json()),
   { default: 'value' }  // Fallback if circuit is open
 );
 
@@ -81,11 +99,11 @@ try {
 interface CircuitBreakerConfig {
   /** Number of failures before opening circuit */
   failureThreshold: number;
-  
+
   /** Time in ms to wait before attempting recovery */
   resetTimeout: number;
-  
-  /** Name for logging/监控 */
+
+  /** Name for logging/monitoring */
   name?: string;
 }
 ```
@@ -103,7 +121,7 @@ console.log({
   failureCount: stats.failureCount,
   totalRequests: stats.totalRequests,
   totalFailures: stats.totalFailures,
-  totalSuccesses: stats.totalSuccesses
+  totalSuccesses: stats.totalSuccesses,
 });
 
 // Manual reset (force recovery)
@@ -117,35 +135,34 @@ breaker.manualReset();
 A pre-configured global instance for backend API calls:
 
 ```typescript
-import { backendCircuitBreaker } from '@thorprovider/adapters/resilience';
+import { backendCircuitBreaker } from '@thorprovider/adapters';
 
 // Use in adapters
 async function getProducts() {
   return backendCircuitBreaker.execute(
-    () => fetch('/api/products'),
+    () => commerce.getProducts(),
     [] // Empty array fallback
   );
 }
 ```
 
-**Configuration:**
+**Default configuration:**
 - `failureThreshold`: 5 failures
 - `resetTimeout`: 60,000ms (1 minute)
-- `name`: 'backend-api'
+- `name`: `'backend-api'`
 
 ---
 
 ## 🎨 Usage Patterns
 
-### Pattern 1: L2 Adapter with Graceful Degradation
+### Pattern 1: Adapter with Graceful Degradation
 
 ```typescript
-// packages/adapters/src/medusa/product-adapter.ts
-import { backendCircuitBreaker } from '@thorprovider/adapters/resilience';
+import { backendCircuitBreaker } from '@thorprovider/adapters';
 
 export async function getProducts(options: GetProductsOptions) {
   return backendCircuitBreaker.execute(
-    () => medusaClient.products.list(options),
+    () => commerce.getProducts(options),
     [] // Return empty array if backend is down
   );
 }
@@ -156,23 +173,23 @@ export async function getProducts(options: GetProductsOptions) {
 - ✅ User sees "No products" instead of error page
 - ✅ Backend gets time to recover
 
-### Pattern 2: L5 Server Component with Fallback UI
+### Pattern 2: Server Component with Fallback UI
 
 ```typescript
-// packages/core/app/products/page.tsx
-import { backendCircuitBreaker } from '@thorprovider/adapters/resilience';
-import { getProducts } from '@thorprovider/adapters/medusa';
+// app/products/page.tsx
+import { backendCircuitBreaker } from '@thorprovider/adapters';
+import { commerce } from '@/lib/commerce';
 
 export default async function ProductsPage() {
   const products = await backendCircuitBreaker.execute(
-    () => getProducts(),
-    [] // Fallback to empty array
+    () => commerce.getProducts(),
+    []
   );
-  
+
   if (products.length === 0) {
-    return <EmptyState message="Products temporarily unavailable" />;
+    return <p>Products temporarily unavailable</p>;
   }
-  
+
   return <ProductsGrid products={products} />;
 }
 ```
@@ -181,14 +198,13 @@ export default async function ProductsPage() {
 
 ```typescript
 // Critical operations should fail explicitly
-async function completeCheckout(data: CheckoutData) {
+async function completeCheckout(cartId: string) {
   try {
     return await backendCircuitBreaker.execute(
-      () => medusaClient.carts.complete(data)
-      // NO fallback - we want this to fail if backend is down
+      () => commerce.completeCheckout(cartId)
+      // NO fallback — we want this to fail if backend is down
     );
   } catch (error) {
-    // Show error message to user
     throw new Error('Checkout unavailable. Please try again later.');
   }
 }
@@ -198,10 +214,9 @@ async function completeCheckout(data: CheckoutData) {
 
 ## 🧪 Testing
 
-### Unit Test Example
-
 ```typescript
-import { CircuitBreaker } from '@thorprovider/adapters/resilience';
+import { describe, it, expect, vi } from 'vitest';
+import { CircuitBreaker } from '@thorprovider/adapters';
 
 describe('CircuitBreaker', () => {
   it('opens after threshold failures', async () => {
@@ -209,28 +224,28 @@ describe('CircuitBreaker', () => {
       failureThreshold: 3,
       resetTimeout: 1000,
     });
-    
-    const mockFn = jest.fn().mockRejectedValue(new Error('fail'));
-    
+
+    const mockFn = vi.fn().mockRejectedValue(new Error('fail'));
+
     // 3 failures
     await expect(breaker.execute(mockFn)).rejects.toThrow();
     await expect(breaker.execute(mockFn)).rejects.toThrow();
     await expect(breaker.execute(mockFn)).rejects.toThrow();
-    
+
     expect(breaker.state).toBe('OPEN');
   });
-  
+
   it('uses fallback when circuit is open', async () => {
     const breaker = new CircuitBreaker({
       failureThreshold: 1,
       resetTimeout: 1000,
     });
-    
-    const mockFn = jest.fn().mockRejectedValue(new Error('fail'));
-    
+
+    const mockFn = vi.fn().mockRejectedValue(new Error('fail'));
+
     // Open circuit
     await breaker.execute(mockFn, 'fallback').catch(() => {});
-    
+
     // Should return fallback immediately
     const result = await breaker.execute(mockFn, 'fallback');
     expect(result).toBe('fallback');
@@ -239,6 +254,12 @@ describe('CircuitBreaker', () => {
 });
 ```
 
+Run tests:
+
+```bash
+yarn workspace @thorprovider/adapters test
+```
+
 ---
 
 ## 📐 Architecture Decisions
@@ -271,29 +292,30 @@ describe('CircuitBreaker', () => {
 
 - Don't use for client-side only operations
 - Don't ignore OPEN state errors silently
-- Don't set failureThreshold too low (causes flapping)
-- Don't set resetTimeout too high (slow recovery)
+- Don't set `failureThreshold` too low (causes flapping)
+- Don't set `resetTimeout` too high (slow recovery)
 
 ---
 
 ## 🔮 Future Enhancements
 
-- [ ] **Retry Pattern**: Exponential backoff for transient failures
-- [ ] **Bulkhead Pattern**: Isolate resource pools
+- [ ] **Bulkhead Pattern**: Isolate resource pools per service
 - [ ] **Rate Limiting**: Prevent API abuse
 - [ ] **Metrics Export**: Prometheus/Datadog integration
 - [ ] **Health Check Integration**: Auto-open circuit on health check fail
 
+> ✅ **Retry Pattern** with exponential backoff is already implemented in `src/core/fetch-utils.ts`.
+
 ---
 
 ## 📚 References
 
-- [Martin Fowler - Circuit Breaker](https://martinfowler.com/bliki/CircuitBreaker.html)
-- [Microsoft - Resilience Patterns](https://docs.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker)
+- [Martin Fowler — Circuit Breaker](https://martinfowler.com/bliki/CircuitBreaker.html)
+- [Microsoft — Resilience Patterns](https://docs.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker)
 - [Netflix Hystrix](https://github.com/Netflix/Hystrix/wiki)
 
 ---
 
-**Last Updated**: March 24, 2026
+**Last Updated**: 2026-05-03
 **Status**: ✅ Active
 **Layer**: L2 (Adapters)

package/src/core/errors.js

@@ -1,161 +0,0 @@
-"use strict";
-/**
- * @thorprovider/adapters v2.0
- * Core errors
- */
-var __extends = (this && this.__extends) || (function () {
-    var extendStatics = function (d, b) {
-        extendStatics = Object.setPrototypeOf ||
-            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
-            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
-        return extendStatics(d, b);
-    };
-    return function (d, b) {
-        if (typeof b !== "function" && b !== null)
-            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
-        extendStatics(d, b);
-        function __() { this.constructor = d; }
-        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProviderAPIError = exports.ResourceNotFoundError = exports.ConfigurationError = exports.ProviderNotFoundError = exports.CommerceError = void 0;
-exports.extractErrorMessage = extractErrorMessage;
-/**
- * Base error class for commerce providers
- */
-var CommerceError = /** @class */ (function (_super) {
-    __extends(CommerceError, _super);
-    function CommerceError(message, code, status) {
-        var _this = _super.call(this, message) || this;
-        _this.code = code;
-        _this.status = status;
-        _this.name = 'CommerceError';
-        return _this;
-    }
-    return CommerceError;
-}(Error));
-exports.CommerceError = CommerceError;
-/**
- * Provider not found error
- */
-var ProviderNotFoundError = /** @class */ (function (_super) {
-    __extends(ProviderNotFoundError, _super);
-    function ProviderNotFoundError(providerName) {
-        var _this = _super.call(this, "Provider not found: ".concat(providerName), 'PROVIDER_NOT_FOUND') || this;
-        _this.name = 'ProviderNotFoundError';
-        return _this;
-    }
-    return ProviderNotFoundError;
-}(CommerceError));
-exports.ProviderNotFoundError = ProviderNotFoundError;
-/**
- * Configuration error
- */
-var ConfigurationError = /** @class */ (function (_super) {
-    __extends(ConfigurationError, _super);
-    function ConfigurationError(message) {
-        var _this = _super.call(this, message, 'CONFIGURATION_ERROR') || this;
-        _this.name = 'ConfigurationError';
-        return _this;
-    }
-    return ConfigurationError;
-}(CommerceError));
-exports.ConfigurationError = ConfigurationError;
-/**
- * Resource not found error
- */
-var ResourceNotFoundError = /** @class */ (function (_super) {
-    __extends(ResourceNotFoundError, _super);
-    function ResourceNotFoundError(resource, identifier) {
-        var _this = _super.call(this, "".concat(resource, " not found: ").concat(identifier), 'RESOURCE_NOT_FOUND', 404) || this;
-        _this.name = 'ResourceNotFoundError';
-        return _this;
-    }
-    return ResourceNotFoundError;
-}(CommerceError));
-exports.ResourceNotFoundError = ResourceNotFoundError;
-/**
- * API error from provider
- */
-var ProviderAPIError = /** @class */ (function (_super) {
-    __extends(ProviderAPIError, _super);
-    function ProviderAPIError(message, provider, status) {
-        var _this = _super.call(this, message, 'PROVIDER_API_ERROR', status) || this;
-        _this.provider = provider;
-        _this.name = 'ProviderAPIError';
-        return _this;
-    }
-    return ProviderAPIError;
-}(CommerceError));
-exports.ProviderAPIError = ProviderAPIError;
-/**
- * Extract error message from various error types
- * Handles standard Error objects, API responses, and unknown error types
- */
-function extractErrorMessage(error) {
-    var _a, _b, _c, _d, _e, _f;
-    // Standard Error object
-    if (error instanceof Error && error.message) {
-        // Don't return generic messages if there's more data
-        if (error.message !== 'An unknown error occurred.') {
-            return error.message;
-        }
-    }
-    // Object with message property
-    if (typeof error === 'object' && error !== null) {
-        var err = error;
-        // Check for response body (common in fetch errors)
-        if (err.body) {
-            if (typeof err.body === 'string')
-                return err.body;
-            if (err.body.message)
-                return String(err.body.message);
-            if ((_a = err.body.error) === null || _a === void 0 ? void 0 : _a.message)
-                return String(err.body.error.message);
-        }
-        // Check for response object
-        if (err.response) {
-            if ((_b = err.response.data) === null || _b === void 0 ? void 0 : _b.message)
-                return String(err.response.data.message);
-            if ((_c = err.response.data) === null || _c === void 0 ? void 0 : _c.error)
-                return String(err.response.data.error);
-            if (err.response.statusText)
-                return "".concat(err.response.status || '', " ").concat(err.response.statusText).trim();
-        }
-        // Check for data property
-        if ((_d = err.data) === null || _d === void 0 ? void 0 : _d.message)
-            return String(err.data.message);
-        if ((_e = err.data) === null || _e === void 0 ? void 0 : _e.error)
-            return String(err.data.error);
-        // Check for error property
-        if ((_f = err.error) === null || _f === void 0 ? void 0 : _f.message)
-            return String(err.error.message);
-        // Check for statusText with status code
-        if (err.status && err.statusText) {
-            return "HTTP ".concat(err.status, ": ").concat(err.statusText);
-        }
-        if (err.status && !err.statusText) {
-            return "HTTP ".concat(err.status, " Error");
-        }
-        // Check for message property (not generic)
-        if (err.message && err.message !== 'An unknown error occurred.') {
-            return String(err.message);
-        }
-        // Try to stringify the error object
-        try {
-            var stringified = JSON.stringify(error);
-            if (stringified !== '{}')
-                return stringified;
-        }
-        catch (_g) {
-            // Ignore JSON.stringify errors
-        }
-    }
-    // String error
-    if (typeof error === 'string') {
-        return error;
-    }
-    // Fallback
-    return 'An unknown error occurred';
-}