@thorprovider/adapters 4.2.0 → 4.3.0

package/docs/fetch-reliability-solution.md

@@ -1,14 +1,26 @@
-# Solución a Errores Frecuentes de "Failed to fetch products"
+---
+title: Fetch Reliability Solution
+purpose: Documents the retry and circuit breaker patterns implemented for robust backend communication
+type: reference
+tags: [resilience, retry, circuit-breaker, fetch, network, medusa]
+related:
+  - RETRY_SOLUTION_SUMMARY.md
+  - providers-overview.md
+  - ../src/resilience/README.md
+updated: 2026-05-03
+---
+
+# Fetch Reliability Solution
 
-**Problema identificado**: Febrero 10, 2026  
-**Estado**: ✅ Resuelto  
-**Severidad**: Alta (afectaba experiencia de usuario con fallos intermitentes)
+**Problem identified**: February 10, 2026
+**Status**: ✅ Resolved + Extended with Circuit Breaker
+**Severity**: High (intermittent user-facing failures)
 
 ---
 
-## 🔴 Problema Original
+## 🔴 Original Problem
 
-El error `ProviderAPIError: Failed to fetch products: fetch failed` ocurría con frecuencia en el V0 starter, interrumpiendo la carga de productos desde el backend de Medusa.
+The error `ProviderAPIError: Failed to fetch products: fetch failed` occurred intermittently in the V0 starter when loading products from the Medusa backend.
 
 ```
 ⨯ Error [ProviderAPIError]: Failed to fetch products: fetch failed
@@ -18,80 +30,55 @@ El error `ProviderAPIError: Failed to fetch products: fetch failed` ocurría con
   provider: 'medusa',
 ```
 
-**Características del problema**:
-- Ocurría cada cierto tiempo sin patrón predecible
-- El backend funcionaba con normalidad cuando se probaba directamente
-- El error era `fetch failed` sin más detalles
-- No había información de qué causaba el fallo
+**Characteristics:**
+- Occurred without a predictable pattern
+- Backend was healthy when tested directly
+- Error was `fetch failed` with no further detail
+- No information about the root cause
 
 ---
 
-## 🔍 Causas Identificadas
+## 🔍 Root Causes
 
-### 1. **Ausencia de Retry Logic**
-- **Problema**: Cualquier fallo temporal de red causaba error inmediato
-- **Impacto**: Fallos transitorios (picos de latencia, pérdida momentánea de paquetes) causaban errores visibles al usuario
-- **Solución**: Implementar reintentos automáticos con exponential backoff
+### 1. No Retry Logic
+Any transient network failure caused an immediate error. Spikes in latency or momentary packet loss were visible to the user.
 
-### 2. **Sin Timeout Configurado**
-- **Problema**: Requests sin límite de tiempo, podían quedarse colgadas indefinidamente
-- **Impacto**: Requests lentos bloqueaban la aplicación sin dar feedback
-- **Solución**: Timeout de 10 segundos por request
+### 2. No Timeout
+Requests had no time limit and could hang indefinitely.
 
-### 3. **Falta de Keep-Alive en Conexiones HTTP**
-- **Problema**: Cada request creaba nueva conexión TCP (handshake completo cada vez)
-- **Impacto**: Mayor latencia, mayor probabilidad de fallos de conexión
-- **Solución**: Implementada implícitamente en el SDK de Medusa (reutiliza conexiones)
+### 3. No Keep-Alive
+Each request created a new TCP connection (full handshake every time), increasing latency and failure probability.
 
-### 4. **Sin Manejo de Errores de Red Específico**
-- **Problema**: Error genérico "fetch failed" sin información útil
-- **Impacto**: Difícil diagnosticar la causa raíz
-- **Solución**: Logging detallado con contexto de reintentos
-
-### 5. **Configuración de URL del Backend**
-- **Observación**: URL con trailing slash `https://erpthor.com/` 
-- **Riesgo potencial**: Redirecciones innecesarias dependiendo de la configuración del servidor
-- **Recomendación**: Verificar que el backend esté bien configurado para manejar trailing slashes
+### 4. Generic Error Messages
+`fetch failed` with no context made root-cause diagnosis difficult.
 
 ---
 
-## ✅ Soluciones Implementadas
-
-### 1. Nuevo Módulo `fetch-utils.ts` (`@thorprovider/adapters/core`)
+## ✅ Solutions Implemented
 
-Creamos utilidades centralizadas para manejo robusto de requests HTTP:
+### 1. Retry Logic with Exponential Backoff (`fetch-utils.ts`)
 
-**Características**:
-- ✅ **Retry automático con exponential backoff**
-  - 3 reintentos por defecto (4 intentos totales)
-  - Delay inicial: 300ms
-  - Backoff multiplicador: 2x (300ms → 600ms → 1200ms)
-  - Delay máximo: 5 segundos
+Located at `packages/adapters/src/core/fetch-utils.ts`. Exported from the main package entry point:
 
-- ✅ **Timeout configurable**
-  - 10 segundos por defecto
-  - Usa `AbortController` nativo
-  - Timeout independiente por cada intento
+```typescript
+import { fetchWithRetry, createFetchWithRetry } from '@thorprovider/adapters';
+```
 
-- ✅ **Detección inteligente de errores retryables**
-  - Network errors (fetch failed, connection refused)
-  - Timeout errors
-  - HTTP status codes específicos: 408, 429, 500, 502, 503, 504
+> ⚠️ **Note:** `@thorprovider/adapters` does not expose subpath exports (e.g. `@thorprovider/adapters/core/fetch-utils`). Always import from the main entry point.
 
-- ✅ **Logging detallado**
-  - Debug info de cada intento
-  - Warnings en reintentos con tiempo restante
-  - Errors con contexto completo
+**Features:**
+- ✅ Automatic retry with exponential backoff (3 retries by default, 4 total attempts)
+- ✅ Configurable timeout via `AbortController` (10s default)
+- ✅ Smart retryable error detection: network errors, timeouts, HTTP 408/429/500/502/503/504
+- ✅ Detailed logging per attempt
 
-**API**:
+**API:**
 
 ```typescript
-// Uso básico
-import { fetchWithRetry } from '@thorprovider/adapters/core/fetch-utils';
-
+// Basic usage
 const response = await fetchWithRetry('https://api.example.com/products');
 
-// Configuración personalizada
+// Custom configuration
 const response = await fetchWithRetry(
   'https://api.example.com/products',
   { method: 'POST', body: JSON.stringify(data) },
@@ -102,298 +89,160 @@ const response = await fetchWithRetry(
   }
 );
 
-// Factory para crear fetch personalizado
-import { createFetchWithRetry } from '@thorprovider/adapters/core/fetch-utils';
-
+// Factory for a reusable configured fetch
 const customFetch = createFetchWithRetry({ maxRetries: 5 });
 const response = await customFetch(url);
 ```
 
-### 2. Actualización del `MedusaProvider`
+### 2. MedusaProvider Integration
 
-**Cambios**:
-
-1. **Import de fetch utilities**:
-```typescript
-import { createFetchWithRetry, type RetryConfig } from '../../core/fetch-utils';
-```
-
-2. **Nueva propiedad en `MedusaProviderConfig`**:
-```typescript
-export interface MedusaProviderConfig extends ProviderConfig {
-  // ... propiedades existentes
-  
-  /**
-   * Retry configuration for fetch requests (optional)
-   */
-  retry?: RetryConfig;
-}
-```
-
-3. **Inyección de fetch personalizado en el constructor**:
-```typescript
-constructor(config: MedusaProviderConfig) {
-  // ... código existente
-  
-  // Create fetch with retry logic
-  const fetchWithRetry = createFetchWithRetry(config.retry);
-  
-  this.sdk = new Medusa({
-    baseUrl: config.baseUrl,
-    publishableKey: config.publishableKey,
-    fetch: fetchWithRetry as any,  // ← Custom fetch with retries!
-    // ... resto de configuración
-  });
-}
-```
-
-### 3. Configuración por Defecto en V0 Starter
-
-Actualizamos `/packages/core/lib/commerce.ts`:
+The `MedusaProviderConfig` accepts an optional `retry` field:
 
 ```typescript
 export const commerce = createProvider({
-  provider: providerType,
+  provider: 'medusa',
   config: {
-    baseUrl: NEXT_PUBLIC_COMMERCE_API_URL,
-    publishableKey: NEXT_PUBLIC_COMMERCE_API_KEY,
-    
-    // ✨ Nueva configuración de retry
+    baseUrl: process.env.NEXT_PUBLIC_COMMERCE_API_URL!,
+    publishableKey: process.env.NEXT_PUBLIC_COMMERCE_API_KEY!,
     retry: {
-      maxRetries: 3,         // 4 intentos totales
-      timeoutMs: 10000,      // 10 segundos por request
-      initialDelayMs: 300,   // Delay inicial 300ms
-      backoffMultiplier: 2,  // Exponential backoff (2x cada vez)
-      maxDelayMs: 5000,      // Cap en 5 segundos
+      maxRetries: 3,        // 4 total attempts
+      timeoutMs: 10000,     // 10s per request
+      initialDelayMs: 300,  // Initial delay
+      backoffMultiplier: 2, // Exponential backoff (2x each retry)
+      maxDelayMs: 5000,     // Cap at 5s
     },
-    
-    // ... resto de configuración
   },
 });
 ```
 
----
+### 3. Circuit Breaker Pattern
 
-## 📊 Impacto Esperado
+The Circuit Breaker is **fully implemented** in `packages/adapters/src/resilience/`. It prevents cascading failures when the backend is consistently unavailable.
 
-### Antes (Sin Retry Logic)
-```
-Request 1 → Network glitch → ❌ FAIL → Error al usuario
-Probabilidad de fallo visible: ~5-10% en condiciones normales
-```
+```typescript
+import { CircuitBreaker, backendCircuitBreaker } from '@thorprovider/adapters';
 
-### Después (Con Retry Logic)
-```
-Request 1 → Network glitch → ⏳ Retry 1 (300ms) → ⏳ Retry 2 (600ms) → ✅ SUCCESS
-Probabilidad de fallo visible: ~0.1-0.5% (reducción de 90-98%)
+// Use the pre-configured global instance
+const products = await backendCircuitBreaker.execute(
+  () => commerce.getProducts(),
+  [] // Fallback: return empty array if circuit is open
+);
+
+// Or create a custom instance
+const breaker = new CircuitBreaker({
+  failureThreshold: 5,
+  resetTimeout: 60000,
+  name: 'medusa-api',
+});
 ```
 
-**Beneficios cuantificables**:
-- ✅ **90-98% reducción en errores visibles** al usuario
-- ✅ **Mejor experiencia de usuario** sin interrupciones
-- ✅ **Resiliencia ante problemas de red transitorios**
-- ✅ **Mejor observabilidad** con logs detallados
-- ✅ **Configuración flexible** por entorno (dev/staging/prod)
+See [resilience/README.md](../src/resilience/README.md) for full Circuit Breaker documentation.
 
 ---
 
-## 🧪 Testing
-
-### Escenarios de Prueba
-
-1. **Backend funcionando normalmente**
-   - ✅ Debe funcionar igual que antes
-   - ✅ Sin delays innecesarios
-   - ✅ Log: "Fetch successful" en primer intento
-
-2. **Backend lento (respuesta > 10s)**
-   - ✅ Timeout después de 10 segundos
-   - ✅ Retry automático
-   - ✅ Log: "Request timeout", luego reintento
-
-3. **Backend temporalmente caído**
-   - ✅ 4 intentos totales (1 original + 3 retries)
-   - ✅ Delays: 300ms, 600ms, 1200ms
-   - ✅ Log: "Fetch failed after all retries"
-
-4. **Red intermitente**
-   - ✅ Recovery automático en siguiente intento exitoso
-   - ✅ Sin error visible al usuario si se recupera antes del 4º intento
+## 📊 Expected Impact
 
-### Comandos de Testing
-
-```bash
-# Build y verificar que compila sin errores
-yarn build
-
-# Verificar tipos
-yarn type-check
-
-# Correr tests (cuando existan)
-yarn test
+### Before (No Retry Logic)
+```
+Request → Network glitch → ❌ FAIL → Error shown to user
+Visible failure rate: ~5-10% under normal conditions
+```
 
-# Dev mode para probar en navegador
-yarn dev:showcase  # Puerto 3002
-yarn workspace @thorprovider/core dev  # Puerto 3000
+### After (With Retry Logic)
+```
+Request → Network glitch → ⏳ Retry 1 (300ms) → ⏳ Retry 2 (600ms) → ✅ SUCCESS
+Visible failure rate: ~0.1-0.5% (90-98% reduction)
 ```
 
 ---
 
-## 🎛️ Configuración por Entorno
+## 🎛️ Configuration by Environment
 
-### Development (más agresivo con timeouts)
+### Development (fast feedback)
 ```typescript
 retry: {
-  maxRetries: 2,         // Menos reintentos para feedback rápido
-  timeoutMs: 5000,       // 5 segundos (más estricto)
+  maxRetries: 2,
+  timeoutMs: 5000,
   initialDelayMs: 200,
 }
 ```
 
-### Production (más tolerante)
+### Production (maximum availability)
 ```typescript
 retry: {
-  maxRetries: 5,         // Más reintentos para máxima disponibilidad
-  timeoutMs: 15000,      // 15 segundos (más tolerante)
+  maxRetries: 5,
+  timeoutMs: 15000,
   initialDelayMs: 500,
   maxDelayMs: 10000,
 }
 ```
 
-### Testing/CI (sin reintentos)
+### Testing / CI (fail fast)
 ```typescript
 retry: {
-  maxRetries: 0,         // Sin reintentos, fallar rápido
-  timeoutMs: 3000,       // 3 segundos máximo
+  maxRetries: 0,
+  timeoutMs: 3000,
 }
 ```
 
 ---
 
-## 📝 Logging y Monitoreo
-
-### Logs Generados
+## 📝 Logging
 
-**Nivel DEBUG** (solo en development):
+**DEBUG** (development only):
 ```
 [FetchUtils] Fetch attempt { url, attempt: 1, maxAttempts: 4, timeout: 10000 }
 [FetchUtils] Fetch successful { url, attempt: 1 }
 ```
 
-**Nivel WARN** (retry attempts):
+**WARN** (retry attempts):
 ```
-[FetchUtils] Fetch failed, retrying... { 
-  url, 
-  attempt: 2, 
-  maxAttempts: 4, 
-  nextRetryIn: '600ms',
-  error: 'fetch failed' 
-}
+[FetchUtils] Fetch failed, retrying... { url, attempt: 2, maxAttempts: 4, nextRetryIn: '600ms', error: 'fetch failed' }
 ```
 
-**Nivel ERROR** (failure final):
+**ERROR** (all retries exhausted):
 ```
-[FetchUtils] Fetch failed after all retries { 
-  url, 
-  totalAttempts: 4, 
-  error: 'fetch failed' 
-}
+[FetchUtils] Fetch failed after all retries { url, totalAttempts: 4, error: 'fetch failed' }
 [MedusaProvider] Failed to fetch products { error: 'fetch failed' }
 ```
 
-### Métricas Recomendadas (Future Work)
-
-Para producción, considerar agregar:
-- ✅ Contador de reintentos exitosos vs fallidos
-- ✅ Latencia promedio de requests
-- ✅ Rate de timeout por endpoint
-- ✅ Alertas cuando retry rate > 10%
-
 ---
 
-## 🚀 Próximos Pasos (Opcional - Future Work)
-
-### 1. Circuit Breaker Pattern
-Si el backend está completamente caído, evitar reintentos innecesarios:
-
-```typescript
-// Después de N fallos consecutivos, "abrir el circuito"
-// y fallar rápido por X segundos antes de intentar de nuevo
-```
-
-### 2. Cache Layer
-Para reducir dependencia en el backend:
-
-```typescript
-// Cache en memoria/Redis de productos frecuentes
-// Fallback a cache si backend falla
-```
-
-### 3. Health Check Endpoint
-Endpoint ligero para verificar salud del backend:
+## 🧪 Testing
 
-```typescript
-// GET /health
-// Si falla, skip productos complejos y usar cache
-```
+```bash
+# Run adapter unit tests (includes fetch-utils and circuit breaker)
+yarn workspace @thorprovider/adapters test
 
-### 4. Retry Budget
-Limitar % de requests totales que pueden hacer retry:
+# Type check
+yarn workspace @thorprovider/adapters type-check
 
-```typescript
-// Protección contra thundering herd cuando backend se cae
+# Build
+yarn workspace @thorprovider/adapters build
 ```
 
 ---
 
-## 🔗 Referencias
-
-### Archivos Modificados
-
-1. **`packages/adapters/src/core/fetch-utils.ts`** (NUEVO)
-   - Utilidades de retry y timeout
+## ✅ Validation Checklist
 
-2. **`packages/adapters/src/core/index.ts`**
-   - Export de fetch-utils
-
-3. **`packages/adapters/src/providers/medusa/index.ts`**
-   - Import fetch-utils
-   - Actualización de `MedusaProviderConfig`
-   - Inyección de custom fetch en constructor
-
-4. **`packages/core/lib/commerce.ts`**
-   - Configuración por defecto de retry
-
-### Documentación Relacionada
-
-- `packages/adapters/README.md` - Arquitectura de adapters
-- `packages/adapters/docs/providers-overview.md` - Providers overview
-- `.github/copilot-instructions.md` - Copilot patterns
-
-### Patrones Implementados
-
-- ✅ **Retry Pattern** con Exponential Backoff
-- ✅ **Timeout Pattern** con AbortController
-- ✅ **Strategy Pattern** (configurable retry strategies)
-- ✅ **Dependency Injection** (custom fetch en SDK)
+- [x] Code compiles without TypeScript errors
+- [x] Exports updated in `core/index.ts`
+- [x] Default retry config added in V0 starter
+- [x] Logging implemented at appropriate levels
+- [x] Backward compatible (`retry` is optional)
+- [x] Unit tests added (vitest)
+- [x] Circuit Breaker implemented and exported
+- [ ] Validation in staging environment (TODO)
+- [ ] Production metrics baseline (TODO)
 
 ---
 
-## ✅ Checklist de Validación
-
-- [x] Código compila sin errores TypeScript
-- [x] Exports actualizados en `core/index.ts`
-- [x] Configuración por defecto agregada en V0 starter
-- [x] Logging implementado en niveles apropiados
-- [x] Documentación completa creada
-- [x] Backward compatible (retry es opcional)
-- [ ] Tests unitarios agregados (TODO)
-- [ ] Tests de integración con backend real (TODO)
-- [ ] Validación en entorno de staging (TODO)
-- [ ] Deploy a producción (TODO)
-
----
+## 🔗 Related Files
 
-**Autor**: GitHub Copilot (Claude Sonnet 4.5)  
-**Fecha**: Febrero 10, 2026  
-**Versión**: 1.0
+| File | Purpose |
+|------|---------|
+| `packages/adapters/src/core/fetch-utils.ts` | Retry + timeout utilities |
+| `packages/adapters/src/core/index.ts` | Core exports |
+| `packages/adapters/src/resilience/` | Circuit Breaker implementation |
+| `packages/adapters/src/providers/medusa/index.ts` | MedusaProvider with retry injection |
+| `packages/core/lib/commerce.ts` | Default retry config in V0 starter |

package/docs/getting-started.md

@@ -1,7 +1,7 @@
 ---
 title: "Getting started"
 purpose: "Provide a quick setup guide for integrating Thor adapters in mock or live backend mode"
-lastReviewed: "2026-05-01"
+lastReviewed: "2026-05-03"
 type: how-to
 tags: [setup, installation, adapters, medusa, configuration]
 related:
@@ -12,7 +12,7 @@ related:
 
 # Getting Started
 
-Quick setup guide for integrating Thor adapters into our project. Start with `mock` for backend-optional development, or configure a real backend immediately.
+Quick setup guide for integrating Thor adapters into your project. Start with `mock` for backend-optional development, or configure a real backend immediately.
 
 ## Prerequisites
 
@@ -42,7 +42,7 @@ const liveCommerce = createProvider({
   },
 });
 
-// Fetch products
+// Fetch products (framework-agnostic)
 const products = await commerce.getProducts({ first: 10 });
 ```
 
@@ -56,7 +56,7 @@ yarn add @thorprovider/adapters
 
 ### Step 2: Initialize the Provider
 
-Create a shared instance for our application.
+Create a shared singleton instance for your application.
 
 ```typescript
 // lib/commerce.ts
@@ -95,30 +95,60 @@ NEXT_PUBLIC_COMMERCE_API_URL=http://localhost:9000
 NEXT_PUBLIC_COMMERCE_API_KEY=your_publishable_key_here
 ```
 
-### Step 4: Use in Server Components (Next.js)
+### Step 4: Use in Your Application
+
+The adapters are framework-agnostic. Use them in any server or client context:
+
+```typescript
+// Pure TypeScript / Node.js
+import { commerce } from './lib/commerce';
+
+const products = await commerce.getProducts();
+console.log(products.map(p => p.title));
+```
+
+#### Framework Integration Example (Next.js App Router)
 
 ```typescript
-// app/products/page.tsx
+// app/products/page.tsx  ← This is framework code, NOT adapter code
 import { commerce } from '@/lib/commerce';
 
 export default async function ProductsPage() {
   const products = await commerce.getProducts();
-  
+
   return (
-    <div>
+    <ul>
       {products.map(product => (
-        <div key={product.id}>{product.title}</div>
+        <li key={product.id}>{product.title}</li>
       ))}
-    </div>
+    </ul>
   );
 }
 ```
 
+> ℹ️ The adapter (`commerce`) is framework-agnostic. Only the page component is Next.js-specific.
+
+## Capability Checks
+
+Before calling optional features, always check the provider's capabilities:
+
+```typescript
+// ✅ Correct: check capability before calling
+if (commerce.capabilities.advancedSearch && commerce.searchProductsAdvanced) {
+  const result = await commerce.searchProductsAdvanced({ query: 'laptop' });
+}
+
+// ✅ Correct: check auth availability before calling auth methods
+if (commerce.auth) {
+  const customer = await commerce.auth.getCurrentCustomer();
+}
+```
+
 ## ✅ DO's
 
 1. **Use Singleton Pattern:** Create one instance of the provider and export it.
 2. **Handle Environment Variables:** Require `baseUrl` only for real backends.
-3. **Prefer Server-Side:** Fetch data in Server Components whenever possible.
+3. **Check Capabilities:** Use `commerce.capabilities.featureName` before calling optional methods.
 4. **Use TypeScript Types:** Leverage the exported types from `@thorprovider/adapters` for better DX.
 5. **Configure Debug Mode:** Enable `debug: true` during development to trace API issues.
 
@@ -127,16 +157,8 @@ export default async function ProductsPage() {
 1. **Don't hardcode credentials:** Never put URLs or API keys directly in the code.
 2. **Don't create multiple instances:** Creating providers inside components causes memory leaks and inconsistent state.
 3. **Don't expose Secret Keys:** Only use Publishable Keys in frontend code.
-4. **Don't ignore Capability checks:** Use `commerce.can('feature')` before calling optional methods.
-5. **Don't import React in Adapters:** Keep adapters framework-agnostic.
-
-## Common Patterns
-
-### Shared Client and Server Instance
-Using a single file to export the provider ensure both SSR and Client-side transitions use the same configuration.
-
-### Dynamic Backend Switching
-You can switch providers (e.g., from 'medusa' to 'mock') for testing purposes by changing the configuration.
+4. **Don't import React or Next.js in adapter code:** Keep adapters framework-agnostic.
+5. **Don't call optional methods without checking:** `commerce.auth`, `commerce.searchProductsAdvanced`, etc. may be undefined.
 
 ## Common Errors & Solutions
 
@@ -152,14 +174,6 @@ You can switch providers (e.g., from 'medusa' to 'mock') for testing purposes by
 **Cause:** Backend doesn't allow the frontend origin.
 **Solution:** Add your frontend URL to Medusa server configuration.
 
-## Common Pitfalls
-
-> ⚠️ **Pitfall 1: Mixing Session and JWT**
-> Ensure you consistently use one authentication method. JWT is preferred for headless setups.
-
-> ⚠️ **Pitfall 2: Forgetting to regenerate types**
-> If the backend data structure changes, ensure your adapter matches the expected interface.
-
 ## Troubleshooting
 
 | Issue | Solution |