@thorprovider/adapters 4.2.1 → 5.0.0

package/docs/RETRY_SOLUTION_SUMMARY.md

@@ -1,13 +1,24 @@
-# Resumen Ejecutivo - Solución a Errores de Fetch
+---
+title: Retry Solution Summary
+purpose: Executive summary of the fetch retry and circuit breaker resilience solution
+type: reference
+tags: [resilience, retry, fetch, summary]
+related:
+  - fetch-reliability-solution.md
+updated: 2026-05-03
+---
+
+# Resumen Ejecutivo — Solución a Errores de Fetch
 
 ## ❌ Problema
 Errores frecuentes `Failed to fetch products: fetch failed` en el V0 starter al cargar productos desde el backend de Medusa.
 
 ## ✅ Solución Implementada
 
-### 1. Nuevo Módulo de Retry Logic (`fetch-utils.ts`)
+### 1. Módulo de Retry Logic (`fetch-utils.ts`)
 - **Ubicación**: `packages/adapters/src/core/fetch-utils.ts`
-- **Funcionalidad**: 
+- **Importación**: `import { fetchWithRetry } from '@thorprovider/adapters'` (no subpath exports)
+- **Funcionalidad**:
   - Reintentos automáticos con exponential backoff
   - Timeout configurable (10s por defecto)
   - Detección inteligente de errores retryables
@@ -17,10 +28,14 @@ Errores frecuentes `Failed to fetch products: fetch failed` en el V0 starter al
 - **Ubicación**: `packages/adapters/src/providers/medusa/index.ts`
 - **Cambios**:
   - Nueva propiedad `retry?: RetryConfig` en `MedusaProviderConfig`
-  - Método privado `withRetry()` que envuelve todas las llamadas al SDK
-  - Métodos `getProduct()` y `getProducts()` actualizados para usar retry logic
+  - Custom fetch inyectado en el constructor del SDK
+
+### 3. Circuit Breaker (implementado)
+- **Ubicación**: `packages/adapters/src/resilience/`
+- **Estado**: ✅ Implementado y exportado desde `@thorprovider/adapters`
+- **Uso**: `import { CircuitBreaker, backendCircuitBreaker } from '@thorprovider/adapters'`
 
-### 3. Configuración por Defecto en V0 Starter
+### 4. Configuración por Defecto en V0 Starter
 - **Ubicación**: `packages/core/lib/commerce.ts`
 - **Configuración**:
   ```typescript
@@ -33,7 +48,7 @@ Errores frecuentes `Failed to fetch products: fetch failed` en el V0 starter al
   }
   ```
 
-## 📊 Impacto Esperado
+## 📊 Impacto
 - **90-98% reducción** en errores visibles al usuario
 - Resiliencia ante problemas de red transitorios
 - Mejor experiencia de usuario sin interrupciones
@@ -41,15 +56,15 @@ Errores frecuentes `Failed to fetch products: fetch failed` en el V0 starter al
 ## 🧪 Estado
 - ✅ Código compila sin errores TypeScript
 - ✅ Build de adapters exitoso
-- ✅ Build de elements exitoso
-- ✅ Documentación completa creada
-- 🔄 Pendiente: Testing en dev/staging
+- ✅ Tests unitarios con vitest (`yarn workspace @thorprovider/adapters test`)
+- ✅ Circuit Breaker implementado
+- 🔄 Pendiente: Validación en staging con métricas reales
 
 ## 📝 Documentación Completa
 Ver [fetch-reliability-solution.md](./fetch-reliability-solution.md) para análisis detallado de causas, soluciones, y configuraciones avanzadas.
 
 ## 🚀 Next Steps
-1. Probar en desarrollo: `yarn dev:showcase` o `yarn workspace @thorprovider/core dev`
+1. Probar en desarrollo: `yarn workspace @thorprovider/core dev`
 2. Verificar logs en consola mostrando reintentos
 3. Confirmar reducción de errores en producción
 4. (Opcional) Ajustar configuración de retry según métricas reales

package/docs/authentication.md

@@ -1,54 +1,61 @@
-# Authentication
-
 ---
+title: Authentication
+purpose: Guide for setting up and using customer authentication with Thor adapters
 type: how-to
 tags: [auth, security, login, jwt, session, registration]
 related:
   - profile-management.md
   - services-overview.md
   - getting-started.md
-updated: 2026-02-28
+updated: 2026-05-03
 ---
 
+# Authentication
+
 Complete guide to setting up and using authentication with Thor adapters.
 
+> ⚠️ **Backend Disparity:** Authentication is only available on providers that expose an `auth` object. Check `commerce.auth` before calling any auth method. Stel Order and Mock providers do not support customer authentication.
+
 ## Prerequisites
 
-- [Thor Adapters installed](getting-started.md#installation)
+- [Thor Adapters installed](getting-started.md)
 - A Medusa.js v2 backend configured with authentication providers
 
 ## Quick Example
 
 ```typescript
-import { commerce } from '@/lib/commerce';
+import { createProvider } from '@thorprovider/adapters';
+
+const commerce = createProvider({
+  provider: 'medusa',
+  config: {
+    baseUrl: process.env.NEXT_PUBLIC_COMMERCE_API_URL!,
+    publishableKey: process.env.NEXT_PUBLIC_COMMERCE_API_KEY!,
+  },
+});
+
+if (!commerce.auth) throw new Error('Auth not available for this provider');
 
-// Simple login
+// Login
 const { customer } = await commerce.auth.login({
   email: 'user@example.com',
   password: 'SecurePassword123!',
 });
 
-console.log(`Welcome back, ${customer.first_name}!`);
+console.log(`Welcome back, ${customer?.first_name}!`);
 ```
 
 ## Step-by-Step Instructions
 
-### Step 1: Configure Auth Method
+### Step 1: Check Auth Availability
 
-Choose between JWT (SPAs) or Session (SSR) in your provider configuration.
+Not all providers support authentication. Always guard before calling auth methods.
 
 ```typescript
-// lib/commerce.ts
-export const commerce = createProvider({
-  provider: 'medusa',
-  config: {
-    // ... basic config
-    auth: {
-      method: 'jwt',           // Recommended for SPAs
-      storage: 'localStorage', // Where to persist tokens
-    },
-  },
-});
+if (!commerce.auth) {
+  // Provider does not support customer auth (e.g. StelOrder, Mock)
+  return;
+}
 ```
 
 ### Step 2: Handle Registration
@@ -66,69 +73,89 @@ const { customer } = await commerce.auth.register({
 
 ### Step 3: Implement Login Flow
 
-Create a login handler in your UI components.
-
 ```typescript
-async function handleLogin(credentials) {
+async function handleLogin(credentials: { email: string; password: string }) {
+  if (!commerce.auth) throw new Error('Auth not supported');
+
   try {
-    await commerce.auth.login(credentials);
-    // Redirect on success
+    const { customer } = await commerce.auth.login(credentials);
+    return customer;
   } catch (error) {
-    // Handle AuthError
+    // Handle CommerceError / invalid credentials
+    throw error;
   }
 }
 ```
 
 ### Step 4: Check Auth State
 
-Protect routes or update UI based on authentication status.
-
 ```typescript
 const isAuth = await commerce.auth.isAuthenticated();
 const customer = await commerce.auth.getCurrentCustomer();
 ```
 
-## ✅ DO's
+### Step 5: Logout
+
+```typescript
+await commerce.auth.logout();
+```
 
-1. **Use JWT for Headless SPAs:** It's more flexible and works better across different origins.
-2. **Use Session for SSR:** If you use Next.js Server Components, Session cookies are more secure.
-3. **Handle AuthErrors specifically:** Use `instanceof AuthError` to show user-friendly messages.
-4. **Enable Auto-refresh:** Keep `autoRefresh: true` (default) to ensure seamless user sessions.
-5. **Clear local state on logout:** Always call `commerce.auth.logout()` to clear stored tokens.
+## Password Management
 
-## ❌ DONT's
+### Request Password Reset
 
-1. **Don't store sensitive data in customer object:** Only use public profile fields.
-2. **Don't handle JWT tokens manually:** Let the adapter manage storage and refresh headers.
-3. **Don't use Secret Keys in the browser:** Authentication should only use Publishable Keys.
-4. **Don't ignore the `isAuthenticated` check:** Verify auth status before performing protected operations.
-5. **Don't hardcode login URLs:** The adapter knows where to send requests based on the provider.
+```typescript
+await commerce.auth.requestPasswordReset('user@example.com');
+// Backend sends reset email
+```
 
-## Common Patterns
+### Confirm Password Reset
 
-### Protected Route Hook (React)
 ```typescript
-function useRequireAuth() {
-  const { customer, loading } = useAuth(); // custom hook
-  const router = useRouter();
-
-  useEffect(() => {
-    if (!loading && !customer) router.push('/login');
-  }, [customer, loading]);
-  
-  return { customer, loading };
-}
+await commerce.auth.resetPassword(tokenFromEmail, 'NewPassword123!');
 ```
 
-### Server-Side Auth Check (Next.js)
+## Address Management
+
+Auth providers also expose address operations:
+
 ```typescript
-export async function getServerSideProps() {
-  const customer = await commerce.auth.getCurrentCustomer();
-  if (!customer) return { redirect: { destination: '/login' } };
-  return { props: { customer } };
-}
+// List addresses
+const addresses = await commerce.auth.getAddresses();
+
+// Create address
+const address = await commerce.auth.createAddress({
+  firstName: 'Jane',
+  lastName: 'Doe',
+  address1: '123 Main St',
+  city: 'Madrid',
+  postalCode: '28001',
+  countryCode: 'ES',
+});
+
+// Update address
+await commerce.auth.updateAddress(address.id, { city: 'Barcelona' });
+
+// Delete address
+await commerce.auth.deleteAddress(address.id);
 ```
 
+## ✅ DO's
+
+1. **Guard with `commerce.auth`:** Always check the property exists before calling auth methods.
+2. **Use JWT for headless SPAs:** More flexible and works better across different origins.
+3. **Use Session for SSR:** Cookie-based sessions are more secure in server-rendered contexts.
+4. **Handle errors specifically:** Catch and surface meaningful messages to the user.
+5. **Clear state on logout:** Always call `commerce.auth.logout()` to clear stored tokens.
+
+## ❌ DONT's
+
+1. **Don't store sensitive data in the customer object:** Only use public profile fields.
+2. **Don't handle JWT tokens manually:** Let the adapter manage storage and refresh headers.
+3. **Don't use Secret Keys in the browser:** Authentication should only use Publishable Keys.
+4. **Don't ignore the `isAuthenticated` check:** Verify auth status before protected operations.
+5. **Don't import React or Next.js in adapter code:** Keep adapters framework-agnostic.
+
 ## Common Errors & Solutions
 
 ### Error: `AUTH_FAILED`
@@ -148,18 +175,44 @@ export async function getServerSideProps() {
 > ⚠️ **Pitfall 1: CORS issues with Session cookies**
 > Session-based auth requires matching domains or properly configured `cross-site` cookies in the backend.
 
-> ⚠️ **Pitfall 2: LocalStorage availability in SSR**
-> Ensure token management logic checks for `window` availability if using `localStorage`.
+> ⚠️ **Pitfall 2: `commerce.auth` is undefined**
+> Not all providers implement auth. Always check `if (commerce.auth)` before calling any method.
 
 ## Troubleshooting
 
 | Issue | Solution |
 |-------|----------|
-| Token not sent in headers | Check if `auth.method` matches backend expectation |
-| Login works but profile fails | Verify `storage` type is correctly configured and working |
+| Token not sent in headers | Verify the provider config and that `publishableKey` is set |
+| Login works but profile fails | Ensure `commerce.auth.getCurrentCustomer()` is called after login |
 | Infinite login loop | Check cookie path and domain settings on the backend |
 
+## Multi-Tenant: Linking Customer to Sales Channel
+
+After login or registration, call `linkCustomerToChannel()` to associate the customer with the storefront's sales channel. This is **required** for the customer to appear in the admin panel of the correct tenant and is idempotent.
+
+```typescript
+if (!commerce.auth) throw new Error('Auth not available');
+
+const { customer } = await commerce.auth.login({
+  email: 'user@example.com',
+  password: 'SecurePassword123!',
+});
+
+// Link the customer to the sales channel resolved from the publishable key
+const { linked, reason } = await commerce.auth.linkCustomerToChannel();
+// linked === true   → new link created
+// linked === true, reason === 'already_linked' → idempotent — no action needed
+```
+
+**Throws:**
+- `ProviderAPIError('NOT_AUTHENTICATED', 401)` — login must succeed first
+- `ProviderAPIError('CHANNEL_RESOLUTION_FAILED', 400)` — publishable key doesn't map to a channel
+- `ProviderAPIError('CONFIGURATION_ERROR')` — provider instantiated without `baseUrl`/`publishableKey`
+
+**Provider support:** Medusa only. Shopify and other stubs return `{ linked: false, reason: 'not_applicable' }`.
+
 ## Next Steps
 
 - [Profile Management](profile-management.md)
 - [Services Overview](services-overview.md)
+- [Multi-Tenant Channel Scoping](multi-tenant-channel-scoping.md)

package/docs/capabilities-system.md

@@ -1,6 +1,6 @@
-# Capabilities System
-
 ---
+title: Capabilities System
+purpose: Reference for backend capability detection and matrices
 type: reference
 tags: [architecture, capabilities, backend, detection]
 related:
@@ -9,6 +9,8 @@ related:
 updated: 2026-02-28
 ---
 
+# Capabilities System
+
 The capabilities system exposes which operations each backend provider supports, enabling adaptive UIs across platforms.
 
 ## Quick Reference

package/docs/category-customization.md

@@ -1,3 +1,15 @@
+---
+title: Category Customization & Inheritance
+purpose: Explains the 5-phase system for hiding, renaming, and adding custom categories on top of backend-provided ones
+type: guide
+tags: [categories, customization, metadata, multi-tenant, architecture]
+related:
+  - providers-overview.md
+  - services-overview.md
+  - multi-tenant-channel-scoping.md
+updated: 2026-05-03
+---
+
 # Category Customization & Inheritance
 
 ## The Problem (Simple Version)
@@ -58,7 +70,7 @@ Your store sells **only shoes**. But the backend (Medusa) gives you 10 categorie
     "hidden": ["sandalias"],
     "renamed": { "accesorios": "Extras" },
     "custom": [
-      { "id": "bestsellers", "name": "Bestsellers", ... }
+      { "id": "bestsellers", "name": "Bestsellers" }
     ]
   }
 }
@@ -74,7 +86,9 @@ What is a customization?
 → { hidden: ["id1", "id2"], renamed: {id: "newname"}, custom: [{...}] }
 ```
 
-We define this **once** in `@thorprovider/types` so every layer speaks the same language.
+Defined once in `@thorprovider/types` so every layer speaks the same language.
+
+> ⚠️ **Implementation status**: Category customization types are planned but not yet merged into `@thorprovider/types`. This document describes the intended architecture.
 
 ---
 
@@ -87,12 +101,12 @@ BackendMetadataAdapter
 Your customizations
 ```
 
-**Key principle**: We use the backend's native **metadata storage**, not a separate database.
+**Key principle**: Uses the backend's native **metadata storage**, not a separate database.
 
 Why?
 - **Simple**: No external SQLite/Supabase
 - **Multi-tenant ready**: Each sales channel has its own metadata
-- **Agnóstic**: Medusa, Shopify, WordPress — same interface
+- **Agnostic**: Medusa, Shopify, WordPress — same interface
 
 ---
 
@@ -114,6 +128,8 @@ Output:
 
 **Why L2?** This is business logic (not UI, not type definition). It belongs with the adapter.
 
+> ⚠️ **Implementation status**: `mergeCategories()` service is planned. Not yet implemented in `packages/adapters/src/`.
+
 ---
 
 ### Phase 4: Expose via API (L5 — Route Handler)
@@ -123,13 +139,12 @@ GET /api/admin/categories
 
 POST /api/admin/categories
 → Dashboard sends new customizations, backend saves them
-
-PUT /api/admin/categories
-→ (Optional) Update a single category (hide/rename)
 ```
 
 **Why L5?** Only the app knows HTTP. Only the app can validate requests.
 
+> ⚠️ **Implementation status**: API route is planned. Not yet implemented in `packages/core/`.
+
 ---
 
 ### Phase 5: Dashboard UI (L4 — Component)
@@ -149,18 +164,17 @@ PUT /api/admin/categories
 │ ✨ Bestsellers                  │
 │    [Edit] [Delete]              │
 ├─────────────────────────────────┤
-│                                 │
 │     [+ Add Custom]  [Save]      │
 └─────────────────────────────────┘
 ```
 
-**Why L4?** Reusable component (could work in different apps). Doesn't know about HTTP/databases.
+> ⚠️ **Implementation status**: Dashboard component is planned. Not yet implemented in `packages/components/`.
 
 ---
 
-## Why This Architecture Is "Agnóstic"
+## Why This Architecture Is "Agnostic"
 
-**Agnóstic** = "Works with any backend, no vendor lock-in."
+**Agnostic** = "Works with any backend, no vendor lock-in."
 
 ### Data Flow
 
@@ -176,7 +190,6 @@ PUT /api/admin/categories
 │    BackendMetadataAdapter (Interface)│
 │ - getMetadata()                      │
 │ - setMetadata()                      │
-│ (Same methods for all backends)      │
 └──────────┬───────────────────────────┘
            │ (Phase 3: mergeCategories)
            ↓
@@ -210,8 +223,6 @@ PUT /api/admin/categories
 - Phase 4 (API route)
 - Phase 5 (UI component)
 
-**Why?** All non-Phase-2 code depends on the **interface**, not the **implementation**.
-
 ---
 
 ## Key Concepts
@@ -243,21 +254,17 @@ Medusa: sales_channel.metadata = { category_customizations: {...} }
 Shopify: custom field or app data store (same interface)
 ```
 
-Result: One less database to maintain.
-
 ---
 
 ## Implementation Order (For Next Agent)
 
-See `.development-guides/category-customization-implementation.md` for detailed step-by-step.
-
 **TL;DR:**
-1. Add types in L1
-2. Extend metadata adapter in L2
+1. Add types in L1 (`@thorprovider/types`)
+2. Extend metadata adapter in L2 (`BackendMetadataAdapter`)
 3. Create `mergeCategories()` service in L2
 4. Integrate into `CommerceProvider.getCategories()` in L2
-5. Create API route in L5
-6. Create UI component in L4
+5. Create API route in L5 (`packages/core/app/api/admin/categories/route.ts`)
+6. Create UI component in L4 (`packages/components/`)
 7. Integrate into dashboard in L5
 
 ---
@@ -299,11 +306,12 @@ Storefront should render it like base categories.
 
 ## Related Files
 
-- **Implementation plan**: `.development-guides/category-customization-implementation.md`
-- **Types**: `packages/types/src/admin/category-customizations.ts`
-- **Metadata adapter**: `packages/adapters/src/backend/BackendMetadataAdapter.ts`
-- **Service**: `packages/adapters/src/services/category-service.ts`
-- **Provider integration**: `packages/adapters/src/providers/medusa/index.ts` (getCategories)
-- **API route**: `packages/core/app/api/admin/categories/route.ts`
-- **Component**: `packages/components/src/patterns/modules/dashboard/CategoryCustomization.tsx`
+> ⚠️ The following files are **planned** and do not yet exist in the codebase:
 
+| File | Status |
+|------|--------|
+| `packages/types/src/admin/category-customizations.ts` | 🗓️ Planned |
+| `packages/adapters/src/backend/BackendMetadataAdapter.ts` | ✅ Exists (extend for categories) |
+| `packages/adapters/src/services/category-service.ts` | 🗓️ Planned |
+| `packages/core/app/api/admin/categories/route.ts` | 🗓️ Planned |
+| `packages/components/src/patterns/modules/dashboard/CategoryCustomization.tsx` | 🗓️ Planned |