@thorprovider/adapters 3.0.2

package/src/resilience/README.md

@@ -0,0 +1,299 @@
+# Resilience Patterns
+
+**Framework-agnostic resilience patterns for robust backend integration.**
+
+---
+
+## 🎯 Overview
+
+This module provides enterprise-grade resilience patterns for handling backend failures gracefully. All patterns are framework-agnostic and can be used in any JavaScript/TypeScript environment.
+
+---
+
+## 📦 Export
+
+```typescript
+import { CircuitBreaker, backendCircuitBreaker } from '@thorprovider/adapters/resilience';
+```
+
+---
+
+## 🔌 Circuit Breaker Pattern
+
+The Circuit Breaker pattern prevents cascading failures when the backend is unavailable by failing fast after a threshold of consecutive failures.
+
+### How It Works
+
+```
+┌──────────┐
+│  CLOSED  │ ◄─── Normal operation (requests pass through)
+└────┬─────┘
+     │ 5 failures
+     ↓
+┌──────────┐
+│   OPEN   │ ◄─── Failing fast (requests rejected immediately)
+└────┬─────┘
+     │ 60 seconds timeout
+     ↓
+┌──────────┐
+│ HALF_OPEN│ ◄─── Testing recovery (1 request allowed)
+└────┬─────┘
+     │ Success? → CLOSED
+     │ Failure? → OPEN
+```
+
+### States
+
+| State | Behavior | Purpose |
+|-------|----------|---------|
+| **CLOSED** | All requests pass through normally | Normal operation |
+| **OPEN** | Requests fail immediately with fallback | Prevent hammering failed backend |
+| **HALF_OPEN** | Single test request allowed | Check if backend recovered |
+
+### Basic Usage
+
+```typescript
+import { CircuitBreaker } from '@thorprovider/adapters/resilience';
+
+const breaker = new CircuitBreaker({
+  failureThreshold: 5,      // Open after 5 failures
+  resetTimeout: 60000,      // Try recovery after 1 minute
+  name: 'my-api'
+});
+
+// With fallback
+const data = await breaker.execute(
+  () => fetch('/api/data'),
+  { default: 'value' }  // Fallback if circuit is open
+);
+
+// Without fallback (throws on failure)
+try {
+  const result = await breaker.execute(() => apiCall());
+} catch (error) {
+  // Circuit is open or API call failed
+}
+```
+
+### Configuration Options
+
+```typescript
+interface CircuitBreakerConfig {
+  /** Number of failures before opening circuit */
+  failureThreshold: number;
+  
+  /** Time in ms to wait before attempting recovery */
+  resetTimeout: number;
+  
+  /** Name for logging/监控 */
+  name?: string;
+}
+```
+
+### Monitoring
+
+```typescript
+// Get current state
+console.log(breaker.state); // 'CLOSED' | 'OPEN' | 'HALF_OPEN'
+
+// Get statistics
+const stats = breaker.stats;
+console.log({
+  state: stats.state,
+  failureCount: stats.failureCount,
+  totalRequests: stats.totalRequests,
+  totalFailures: stats.totalFailures,
+  totalSuccesses: stats.totalSuccesses
+});
+
+// Manual reset (force recovery)
+breaker.manualReset();
+```
+
+---
+
+## 🌐 Global Backend Circuit Breaker
+
+A pre-configured global instance for backend API calls:
+
+```typescript
+import { backendCircuitBreaker } from '@thorprovider/adapters/resilience';
+
+// Use in adapters
+async function getProducts() {
+  return backendCircuitBreaker.execute(
+    () => fetch('/api/products'),
+    [] // Empty array fallback
+  );
+}
+```
+
+**Configuration:**
+- `failureThreshold`: 5 failures
+- `resetTimeout`: 60,000ms (1 minute)
+- `name`: 'backend-api'
+
+---
+
+## 🎨 Usage Patterns
+
+### Pattern 1: L2 Adapter with Graceful Degradation
+
+```typescript
+// packages/adapters/src/medusa/product-adapter.ts
+import { backendCircuitBreaker } from '@thorprovider/adapters/resilience';
+
+export async function getProducts(options: GetProductsOptions) {
+  return backendCircuitBreaker.execute(
+    () => medusaClient.products.list(options),
+    [] // Return empty array if backend is down
+  );
+}
+```
+
+**Benefits:**
+- ✅ Frontend stays functional with empty state
+- ✅ User sees "No products" instead of error page
+- ✅ Backend gets time to recover
+
+### Pattern 2: L5 Server Component with Fallback UI
+
+```typescript
+// packages/core/app/products/page.tsx
+import { backendCircuitBreaker } from '@thorprovider/adapters/resilience';
+import { getProducts } from '@thorprovider/adapters/medusa';
+
+export default async function ProductsPage() {
+  const products = await backendCircuitBreaker.execute(
+    () => getProducts(),
+    [] // Fallback to empty array
+  );
+  
+  if (products.length === 0) {
+    return <EmptyState message="Products temporarily unavailable" />;
+  }
+  
+  return <ProductsGrid products={products} />;
+}
+```
+
+### Pattern 3: Critical Operations (No Fallback)
+
+```typescript
+// Critical operations should fail explicitly
+async function completeCheckout(data: CheckoutData) {
+  try {
+    return await backendCircuitBreaker.execute(
+      () => medusaClient.carts.complete(data)
+      // 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.');
+  }
+}
+```
+
+---
+
+## 🧪 Testing
+
+### Unit Test Example
+
+```typescript
+import { CircuitBreaker } from '@thorprovider/adapters/resilience';
+
+describe('CircuitBreaker', () => {
+  it('opens after threshold failures', async () => {
+    const breaker = new CircuitBreaker({
+      failureThreshold: 3,
+      resetTimeout: 1000,
+    });
+    
+    const mockFn = jest.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'));
+    
+    // Open circuit
+    await breaker.execute(mockFn, 'fallback').catch(() => {});
+    
+    // Should return fallback immediately
+    const result = await breaker.execute(mockFn, 'fallback');
+    expect(result).toBe('fallback');
+    expect(mockFn).toHaveBeenCalledTimes(1); // Not called again
+  });
+});
+```
+
+---
+
+## 📐 Architecture Decisions
+
+### Why L2 (Adapters)?
+
+1. **Framework Agnostic**: Works in Next.js, Remix, Vite, Node.js
+2. **Reusable**: All starters can use the same circuit breaker
+3. **No Dependencies**: Zero external dependencies (pure TypeScript)
+4. **Type Safe**: Full TypeScript support
+
+### Why Not L5 (Starters)?
+
+- ❌ Not reusable across starters
+- ❌ Mixed with framework-specific code
+- ❌ Harder to test in isolation
+
+---
+
+## 🚀 Best Practices
+
+### DO ✅
+
+- Use for all backend API calls
+- Provide sensible fallbacks for non-critical operations
+- Monitor circuit breaker stats in production
+- Use separate instances for different services
+
+### DON'T ❌
+
+- 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)
+
+---
+
+## 🔮 Future Enhancements
+
+- [ ] **Retry Pattern**: Exponential backoff for transient failures
+- [ ] **Bulkhead Pattern**: Isolate resource pools
+- [ ] **Rate Limiting**: Prevent API abuse
+- [ ] **Metrics Export**: Prometheus/Datadog integration
+- [ ] **Health Check Integration**: Auto-open circuit on health check fail
+
+---
+
+## 📚 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)
+- [Netflix Hystrix](https://github.com/Netflix/Hystrix/wiki)
+
+---
+
+**Last Updated**: March 24, 2026
+**Status**: ✅ Active
+**Layer**: L2 (Adapters)

package/src/resilience/circuit-breaker.ts

@@ -0,0 +1,222 @@
+/**
+ * Circuit Breaker Pattern Implementation
+ * 
+ * Prevents cascading failures when the backend is unavailable.
+ * Implements the Circuit Breaker pattern as described by Martin Fowler.
+ * 
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Too many failures, requests fail fast
+ * - HALF_OPEN: Testing if backend has recovered
+ * 
+ * @see https://martinfowler.com/bliki/CircuitBreaker.html
+ */
+
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+export interface CircuitBreakerConfig {
+  /** Number of failures before opening circuit */
+  failureThreshold: number;
+  /** Time in ms to wait before attempting recovery */
+  resetTimeout: number;
+  /** Name for logging/monitoring */
+  name?: string;
+}
+
+export interface CircuitBreakerStats {
+  state: CircuitState;
+  failureCount: number;
+  lastFailureTime: number | null;
+  totalRequests: number;
+  totalFailures: number;
+  totalSuccesses: number;
+}
+
+/**
+ * Circuit Breaker Class
+ * 
+ * Monitors backend calls and prevents cascading failures by
+ * failing fast when the backend is unhealthy.
+ * 
+ * @example
+ * ```ts
+ * const breaker = new CircuitBreaker({
+ *   failureThreshold: 3,
+ *   resetTimeout: 60000, // 1 minute
+ *   name: 'backend-api'
+ * });
+ * 
+ * const result = await breaker.execute(
+ *   () => fetch('/api/data'),
+ *   fallbackData
+ * );
+ * ```
+ */
+export class CircuitBreaker {
+  private failureCount = 0;
+  private lastFailureTime: number | null = null;
+  private totalRequests = 0;
+  private totalFailures = 0;
+  private totalSuccesses = 0;
+  
+  constructor(private config: CircuitBreakerConfig) {
+    this.config = {
+      failureThreshold: config.failureThreshold || 5,
+      resetTimeout: config.resetTimeout || 60000, // 1 minute default
+      name: config.name || 'circuit-breaker',
+    };
+  }
+  
+  /**
+   * Get current circuit state
+   */
+  get state(): CircuitState {
+    if (this.failureCount >= this.config.failureThreshold) {
+      // Circuit is open (failing fast)
+      if (this.shouldAttemptReset()) {
+        return 'HALF_OPEN'; // Try to recover
+      }
+      return 'OPEN';
+    }
+    return 'CLOSED'; // Normal operation
+  }
+  
+  /**
+   * Get circuit breaker statistics
+   */
+  get stats(): CircuitBreakerStats {
+    return {
+      state: this.state,
+      failureCount: this.failureCount,
+      lastFailureTime: this.lastFailureTime,
+      totalRequests: this.totalRequests,
+      totalFailures: this.totalFailures,
+      totalSuccesses: this.totalSuccesses,
+    };
+  }
+  
+  /**
+   * Execute a function with circuit breaker protection
+   * 
+   * @param fn - Function to execute
+   * @param fallback - Fallback value if circuit is open
+   * @returns Result from fn or fallback
+   */
+  async execute<T>(
+    fn: () => Promise<T>,
+    fallback?: T
+  ): Promise<T> {
+    this.totalRequests++;
+    
+    const currentState = this.state;
+    
+    // If circuit is OPEN and we have a fallback, return it immediately
+    if (currentState === 'OPEN') {
+      this.log('Circuit is OPEN - failing fast');
+      if (fallback !== undefined) {
+        return fallback;
+      }
+      throw new CircuitBreakerOpenError(
+        `Circuit breaker "${this.config.name}" is OPEN - backend may be unavailable`
+      );
+    }
+    
+    // Try to execute the function
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      
+      // If we have a fallback, use it
+      if (fallback !== undefined) {
+        this.log('Returning fallback due to error:', error);
+        return fallback;
+      }
+      
+      // Otherwise, re-throw the error
+      throw error;
+    }
+  }
+  
+  /**
+   * Check if circuit should attempt to reset
+   */
+  private shouldAttemptReset(): boolean {
+    if (!this.lastFailureTime) return false;
+    
+    const timeSinceLastFailure = Date.now() - this.lastFailureTime;
+    return timeSinceLastFailure >= this.config.resetTimeout;
+  }
+  
+  /**
+   * Record a successful call
+   */
+  private onSuccess(): void {
+    this.totalSuccesses++;
+    this.reset();
+    this.log('Request succeeded - circuit reset');
+  }
+  
+  /**
+   * Record a failed call
+   */
+  private onFailure(): void {
+    this.failureCount++;
+    this.totalFailures++;
+    this.lastFailureTime = Date.now();
+    
+    if (this.state === 'OPEN') {
+      this.log(`Circuit OPENED after ${this.failureCount} failures`);
+    } else {
+      this.log(`Failure recorded (${this.failureCount}/${this.config.failureThreshold})`);
+    }
+  }
+  
+  /**
+   * Reset circuit to CLOSED state
+   */
+  private reset(): void {
+    this.failureCount = 0;
+    this.lastFailureTime = null;
+  }
+  
+  /**
+   * Manually reset the circuit breaker
+   */
+  public manualReset(): void {
+    this.reset();
+    this.log('Circuit manually reset');
+  }
+  
+  /**
+   * Log messages (only in development)
+   */
+  private log(...args: unknown[]): void {
+    if (process.env.NODE_ENV === 'development') {
+      console.log(`[CircuitBreaker:${this.config.name}]`, ...args);
+    }
+  }
+}
+
+/**
+ * Custom error for when circuit is open
+ */
+export class CircuitBreakerOpenError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CircuitBreakerOpenError';
+  }
+}
+
+/**
+ * Global circuit breaker instance for backend API calls
+ * 
+ * Can be imported and used throughout the application
+ */
+export const backendCircuitBreaker = new CircuitBreaker({
+  failureThreshold: 5,      // Open after 5 failures
+  resetTimeout: 60000,      // Try to recover after 1 minute
+  name: 'backend-api',
+});

package/src/resilience/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Resilience Patterns
+ * 
+ * Framework-agnostic resilience patterns for robust backend integration.
+ * Includes circuit breaker, retry logic, and failure handling.
+ * 
+ * @packageDocumentation
+ */
+
+export * from './circuit-breaker';

package/src/types/capabilities.types.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * @thorprovider/adapters v2.0
+ * Backend Capabilities System
+ *
+ * Defines what operations each backend platform supports.
+ * This is a compile-time capability detection system, NOT runtime feature flags.
+ *
+ * NOTE: BackendCapabilities interface is defined in @thorprovider/types (L1: Foundation).
+ * This file re-exports it and provides platform-specific implementations.
+ *
+ * @see packages/core/docs/BACKEND_CAPABILITIES_ANALYSIS.md
+ * @see packages/core/docs/COMMERCE_PROVIDER_ARCHITECTURE.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHOPIFY_CAPABILITIES = exports.MEDUSA_CAPABILITIES = void 0;
+exports.isBackendCapabilities = isBackendCapabilities;
+exports.getCapabilityDescription = getCapabilityDescription;
+/**
+ * Medusa backend capabilities
+ *
+ * @see https://docs.medusajs.com/api/store
+ */
+exports.MEDUSA_CAPABILITIES = {
+    // Profile Management
+    updateProfile: true,
+    updateEmail: false, // Security restriction
+    changePasswordDirect: false, // Email flow only
+    changePasswordViaEmail: true,
+    deleteAccount: true, // Implemented via ThorMedusaClient
+    // Avatar
+    uploadAvatar: false,
+    avatarViaMetadata: true,
+    // Custom Attributes
+    customAttributes: true,
+    // Orders
+    fetchOrders: true,
+    cancelOrder: true,
+    // Addresses
+    manageAddresses: true,
+    defaultAddress: true,
+    // Cart/Checkout
+    applyDiscounts: true,
+    shippingCalculation: true,
+    guestCheckout: true,
+    savedPaymentMethods: false, // Depends on payment provider
+    listPaymentProviders: true,
+    regionSpecificPayments: true,
+    // Wishlist
+    wishlist: false, // Requires custom implementation
+    // Search
+    advancedSearch: true,
+    facetedFilters: true,
+    // Reviews
+    productReviews: false, // Requires custom implementation
+    // Loyalty
+    loyaltyProgram: false, // Requires custom implementation
+};
+/**
+ * Shopify backend capabilities
+ *
+ * @see https://shopify.dev/docs/api/storefront
+ */
+exports.SHOPIFY_CAPABILITIES = {
+    // Profile Management
+    updateProfile: true,
+    updateEmail: true,
+    changePasswordDirect: true,
+    changePasswordViaEmail: true,
+    deleteAccount: false, // Requires admin API
+    // Avatar
+    uploadAvatar: false,
+    avatarViaMetadata: true,
+    // Custom Attributes
+    customAttributes: true,
+    // Orders
+    fetchOrders: true,
+    cancelOrder: true,
+    // Addresses
+    manageAddresses: true,
+    defaultAddress: true,
+    // Cart/Checkout
+    applyDiscounts: true,
+    shippingCalculation: true,
+    guestCheckout: true,
+    savedPaymentMethods: true,
+    listPaymentProviders: true,
+    regionSpecificPayments: false, // Global payment methods
+    // Wishlist
+    wishlist: false, // Requires app
+    // Search
+    advancedSearch: true,
+    facetedFilters: true,
+    // Reviews
+    productReviews: false, // Requires app
+    // Loyalty
+    loyaltyProgram: false, // Requires app
+};
+/**
+ * Type guard to check if an object is a valid BackendCapabilities
+ */
+function isBackendCapabilities(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    var capabilities = obj;
+    // Check required profile management capabilities
+    return (typeof capabilities.updateProfile === 'boolean' &&
+        typeof capabilities.updateEmail === 'boolean' &&
+        typeof capabilities.changePasswordDirect === 'boolean');
+}
+/**
+ * Get capability description for UI display
+ */
+function getCapabilityDescription(capability) {
+    var descriptions = {
+        updateProfile: 'Update profile information (name, phone)',
+        updateEmail: 'Change email address',
+        changePasswordDirect: 'Change password directly',
+        changePasswordViaEmail: 'Request password reset via email',
+        deleteAccount: 'Delete account (self-service)',
+        uploadAvatar: 'Upload profile picture',
+        avatarViaMetadata: 'Store avatar URL in metadata',
+        customAttributes: 'Custom customer attributes',
+        fetchOrders: 'View order history',
+        cancelOrder: 'Cancel orders',
+        manageAddresses: 'Add/update/delete addresses',
+        defaultAddress: 'Set default address',
+        applyDiscounts: 'Apply discount codes',
+        shippingCalculation: 'Calculate shipping rates',
+        guestCheckout: 'Checkout without account',
+        savedPaymentMethods: 'Save payment methods',
+        listPaymentProviders: 'List available payment providers',
+        regionSpecificPayments: 'Region-specific payment methods',
+        wishlist: 'Wishlist/favorites',
+        advancedSearch: 'Advanced product search',
+        facetedFilters: 'Filter by product attributes',
+        productReviews: 'Product reviews and ratings',
+        loyaltyProgram: 'Loyalty/rewards program',
+    };
+    return descriptions[capability] || capability;
+}