@thorprovider/adapters 3.0.2

package/docs/RETRY_SOLUTION_SUMMARY.md

@@ -0,0 +1,55 @@
+# 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`)
+- **Ubicación**: `packages/adapters/src/core/fetch-utils.ts`
+- **Funcionalidad**: 
+  - Reintentos automáticos con exponential backoff
+  - Timeout configurable (10s por defecto)
+  - Detección inteligente de errores retryables
+  - Logging detallado
+
+### 2. Integración en MedusaProvider
+- **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
+
+### 3. Configuración por Defecto en V0 Starter
+- **Ubicación**: `packages/core/lib/commerce.ts`
+- **Configuración**:
+  ```typescript
+  retry: {
+    maxRetries: 3,         // 4 intentos totales
+    timeoutMs: 10000,      // 10 segundos por request
+    initialDelayMs: 300,   // Delay inicial 300ms
+    backoffMultiplier: 2,  // Exponential backoff (2x)
+    maxDelayMs: 5000,      // Cap en 5 segundos
+  }
+  ```
+
+## 📊 Impacto Esperado
+- **90-98% reducción** en errores visibles al usuario
+- Resiliencia ante problemas de red transitorios
+- Mejor experiencia de usuario sin interrupciones
+
+## 🧪 Estado
+- ✅ Código compila sin errores TypeScript
+- ✅ Build de adapters exitoso
+- ✅ Build de elements exitoso
+- ✅ Documentación completa creada
+- 🔄 Pendiente: Testing en dev/staging
+
+## 📝 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`
+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

@@ -0,0 +1,165 @@
+# Authentication
+
+---
+type: how-to
+tags: [auth, security, login, jwt, session, registration]
+related:
+  - profile-management.md
+  - services-overview.md
+  - getting-started.md
+updated: 2026-02-28
+---
+
+Complete guide to setting up and using authentication with Thor adapters.
+
+## Prerequisites
+
+- [Thor Adapters installed](getting-started.md#installation)
+- A Medusa.js v2 backend configured with authentication providers
+
+## Quick Example
+
+```typescript
+import { commerce } from '@/lib/commerce';
+
+// Simple login
+const { customer } = await commerce.auth.login({
+  email: 'user@example.com',
+  password: 'SecurePassword123!',
+});
+
+console.log(`Welcome back, ${customer.first_name}!`);
+```
+
+## Step-by-Step Instructions
+
+### Step 1: Configure Auth Method
+
+Choose between JWT (SPAs) or Session (SSR) in your provider configuration.
+
+```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
+    },
+  },
+});
+```
+
+### Step 2: Handle Registration
+
+Capture user data and create a new customer account.
+
+```typescript
+const { customer } = await commerce.auth.register({
+  email: 'new@example.com',
+  password: 'Password123!',
+  first_name: 'Jane',
+  last_name: 'Doe',
+});
+```
+
+### Step 3: Implement Login Flow
+
+Create a login handler in your UI components.
+
+```typescript
+async function handleLogin(credentials) {
+  try {
+    await commerce.auth.login(credentials);
+    // Redirect on success
+  } catch (error) {
+    // Handle AuthError
+  }
+}
+```
+
+### 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
+
+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.
+
+## ❌ DONT's
+
+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.
+
+## Common Patterns
+
+### 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 };
+}
+```
+
+### Server-Side Auth Check (Next.js)
+```typescript
+export async function getServerSideProps() {
+  const customer = await commerce.auth.getCurrentCustomer();
+  if (!customer) return { redirect: { destination: '/login' } };
+  return { props: { customer } };
+}
+```
+
+## Common Errors & Solutions
+
+### Error: `AUTH_FAILED`
+**Cause:** Incorrect email or password.
+**Solution:** Show "Invalid credentials" message to the user.
+
+### Error: `TOKEN_EXPIRED`
+**Cause:** Refresh token expired or user was logged out elsewhere.
+**Solution:** Redirect to login page to re-authenticate.
+
+### Error: `USER_NOT_FOUND`
+**Cause:** Attempting to login with a non-existent email.
+**Solution:** Prompt user to register if they don't have an account.
+
+## Common Pitfalls
+
+> ⚠️ **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`.
+
+## 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 |
+| Infinite login loop | Check cookie path and domain settings on the backend |
+
+## Next Steps
+
+- [Profile Management](profile-management.md)
+- [Services Overview](services-overview.md)

package/docs/capabilities-system.md

@@ -0,0 +1,143 @@
+# Capabilities System
+
+---
+type: reference
+tags: [architecture, capabilities, backend, detection]
+related:
+  - providers-overview.md
+  - services-overview.md
+updated: 2026-02-28
+---
+
+The capabilities system exposes which operations each backend provider supports, enabling adaptive UIs across platforms.
+
+## Quick Reference
+
+```typescript
+import { commerce } from '@/lib/commerce';
+
+// Check any capability
+if (commerce.capabilities.updateEmail) {
+  // Safe to call
+  await commerce.auth.updateCustomer({ email: 'new@email.com' });
+}
+```
+
+## Available Capabilities
+
+### Profile Operations
+
+| Capability | Type | Description |
+|------------|------|-------------|
+| `updateProfile` | `boolean` | Can update name, phone, etc. |
+| `updateEmail` | `boolean` | Can change the primary email address. |
+| `changePasswordDirect` | `boolean` | Supports `password` field in `updateCustomer`. |
+| `changePasswordViaEmail` | `boolean` | Supports `requestPasswordReset` method. |
+| `deleteAccount` | `boolean` | Supports `deleteAccount` method. |
+| `uploadAvatar` | `boolean` | Supports native file upload for avatars. |
+
+### Cart Operations
+
+| Capability | Type | Description |
+|------------|------|-------------|
+| `cartPromoCode` | `boolean` | Can apply discount/promo codes to cart. |
+| `cartGiftCards` | `boolean` | Supports gift card application. |
+| `cartNotes` | `boolean` | Supports order/cart notes. |
+| `cartCustomAttributes` | `boolean` | Supports metadata/attributes at cart level. |
+
+### Product & Discovery
+
+| Capability | Type | Description |
+|------------|------|-------------|
+| `productVariants` | `boolean` | Backend supports multiple variants per product. |
+| `productCategories` | `boolean` | Supports nested categories or collections. |
+| `productInventory` | `boolean` | Real-time inventory tracking available. |
+| `productDigital` | `boolean` | Supports digital/downloadable products. |
+| `productReviews` | `boolean` | Native review system support. |
+
+## Type Definitions
+
+```typescript
+export interface BackendCapabilities {
+  // Profile
+  updateProfile: boolean;
+  updateEmail: boolean;
+  changePasswordDirect: boolean;
+  changePasswordViaEmail: boolean;
+  deleteAccount: boolean;
+  uploadAvatar: boolean;
+  
+  // Avatar Extensions
+  avatarViaMetadata: boolean;
+  
+  // Cart
+  cartPromoCode: boolean;
+  cartGiftCards: boolean;
+  cartNotes: boolean;
+  cartCustomAttributes: boolean;
+  
+  // Products
+  productVariants: boolean;
+  productCategories: boolean;
+  productInventory: boolean;
+  productDigital: boolean;
+  productReviews: boolean;
+  
+  // Auth Integration
+  authJWT: boolean;
+  authSession: boolean;
+  authOAuth: boolean;
+  authPasswordless: boolean;
+}
+```
+
+## Examples
+
+### Basic: Conditional UI
+```tsx
+const { canDelete } = useCapabilities();
+
+return (
+  <Button disabled={!canDelete} color="red">
+    Delete Account
+  </Button>
+);
+```
+
+### Advanced: Multi-provider Fallback
+```typescript
+async function handleAvatarUpdate(file: File) {
+  if (caps.uploadAvatar) {
+    return await commerce.auth.uploadAvatar(file);
+  } 
+  
+  if (caps.avatarViaMetadata) {
+    const url = await externalUpload(file);
+    return await commerce.auth.updateCustomer({
+      metadata: { avatar_url: url }
+    });
+  }
+  
+  throw new Error('Avatar updates not supported on this backend');
+}
+```
+
+## Edge Cases
+
+- **Runtime Changes:** Capabilities are static per provider instance. If a backend configuration changes, the provider must be re-initialized.
+- **Partial Support:** A capability might be `true` but only for specific users. Local validation still applies.
+- **Provider Switching:** When switching providers (e.g., Medusa to Shopify), ensure the UI handles the change in capabilities instantly.
+
+## Performance
+
+Capabilities are calculated once during provider initialization. Accessing `commerce.capabilities` is a zero-latency O(1) operation.
+
+## Accessibility
+
+- **Disabled States:** When a capability is `false`, ensure inputs are correctly marked as `disabled` and provide an `aria-description` explaining why.
+- **Dynamic Content:** Use `aria-live` regions if UI sections disappear based on backend capabilities during initialization.
+
+## See Also
+
+- [Providers Overview](providers-overview.md)
+- [Services Overview](services-overview.md)

package/docs/category-customization.md

@@ -0,0 +1,309 @@
+# Category Customization & Inheritance
+
+## The Problem (Simple Version)
+
+Your store sells **only shoes**. But the backend (Medusa) gives you 10 categories: "Formales", "Deportivos", "Sandalias", "Accesorios", etc.
+
+**Question**: What do you do with categories you don't use?
+
+### Option A: Take It Or Leave It (Bad)
+- Accept all 10 categories as-is
+- Can't hide unwanted ones
+- Can't rename for your market (Spain: "fundas" vs USA: "covers")
+- **Result**: Broken UX, confused customers
+
+### Option B: Personalize Inheritance (Good ✨)
+- Get all categories from backend
+- But you can:
+  - **Hide** ones you don't need
+  - **Rename** to match your market
+  - **Add new** custom categories if Medusa doesn't have them
+  - **Toggle** inheritance on/off
+
+**Result**: Flexible, multi-market ready, no backend changes needed.
+
+---
+
+## Real-World Example
+
+### Scenario: "Zapatos Cubanos Online"
+
+**Backend (Medusa) provides:**
+```
+- Formales
+- Deportivos
+- Sandalias
+- Accesorios
+```
+
+**You customize in dashboard:**
+```
+❌ Hide "Sandalias"     (you don't sell sandals)
+✏️ Rename "Accesorios" → "Extras"
+✨ Add "Bestsellers"    (custom category)
+```
+
+**Customer sees in storefront:**
+```
+- Formales
+- Deportivos
+- Extras               (renamed)
+- Bestsellers          (custom)
+```
+
+**Database stores (in metadata):**
+```json
+{
+  "categoryCustomizations": {
+    "hidden": ["sandalias"],
+    "renamed": { "accesorios": "Extras" },
+    "custom": [
+      { "id": "bestsellers", "name": "Bestsellers", ... }
+    ]
+  }
+}
+```
+
+---
+
+## How It Works (The 5-Phase System)
+
+### Phase 1: Define Vocabulary (L1 — Types)
+```
+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.
+
+---
+
+### Phase 2: Store in Backend (L2 — Metadata Adapter)
+```
+Backend (Medusa, Shopify, etc.)
+  ↓
+BackendMetadataAdapter
+  ↓ (reads/writes JSON in sales_channel.metadata)
+Your customizations
+```
+
+**Key principle**: We use 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
+
+---
+
+### Phase 3: Merge Logic (L2 — Service)
+```
+Input:
+  baseCategories = [Formales, Deportivos, Sandalias]
+  customizations = { hidden: [Sandalias], renamed: {...}, custom: [...] }
+
+Function mergeCategories(base, customizations):
+  1. Remove hidden categories
+  2. Rename categories per config
+  3. Add custom categories
+  4. Return final list
+
+Output:
+  effectiveCategories = [Formales, Deportivos, Extras, Bestsellers]
+```
+
+**Why L2?** This is business logic (not UI, not type definition). It belongs with the adapter.
+
+---
+
+### Phase 4: Expose via API (L5 — Route Handler)
+```
+GET /api/admin/categories
+→ Returns merged categories (dashboard reads state)
+
+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.
+
+---
+
+### Phase 5: Dashboard UI (L4 — Component)
+```
+┌─────────────────────────────────┐
+│ ⚙️ Manage Categories            │
+├─────────────────────────────────┤
+│ ☑️ Use inherited categories     │ ← Toggle
+├─────────────────────────────────┤
+│ Base Categories:                │
+│ ☑️ Formales                     │
+│ ☑️ Deportivos                   │
+│ ☐ Sandalias            [HIDDEN] │
+│ (Extras) ← Renamed from "Accesorios"
+├─────────────────────────────────┤
+│ Custom Categories:              │
+│ ✨ Bestsellers                  │
+│    [Edit] [Delete]              │
+├─────────────────────────────────┤
+│                                 │
+│     [+ Add Custom]  [Save]      │
+└─────────────────────────────────┘
+```
+
+**Why L4?** Reusable component (could work in different apps). Doesn't know about HTTP/databases.
+
+---
+
+## Why This Architecture Is "Agnóstic"
+
+**Agnóstic** = "Works with any backend, no vendor lock-in."
+
+### Data Flow
+
+```
+┌─────────────────────┐
+│      Medusa         │ (or Shopify, WordPress)
+│  sales_channel.     │
+│  metadata           │
+└──────────┬──────────┘
+           │ (Phase 2: BackendMetadataAdapter)
+           ↓
+┌──────────────────────────────────────┐
+│    BackendMetadataAdapter (Interface)│
+│ - getMetadata()                      │
+│ - setMetadata()                      │
+│ (Same methods for all backends)      │
+└──────────┬───────────────────────────┘
+           │ (Phase 3: mergeCategories)
+           ↓
+┌──────────────────────────────────────┐
+│       CategoryService                │
+│ mergeCategories(base, custom)        │
+│ (Pure function, no dependencies)     │
+└──────────┬───────────────────────────┘
+           │ (Phase 4: API exposes)
+           ↓
+┌──────────────────────────────────────┐
+│    /api/admin/categories             │
+│ (GET merged, POST customizations)    │
+└──────────┬───────────────────────────┘
+           │ (Phase 5: UI consumes)
+           ↓
+┌──────────────────────────────────────┐
+│   CategoryCustomization Component    │
+│   (Dashboard controls)               │
+└──────────────────────────────────────┘
+```
+
+### If You Change Backend: Medusa → Shopify
+
+**What changes:**
+- Phase 2 implementation (MedusaMetadataAdapter → ShopifyMetadataAdapter)
+
+**What stays the same:**
+- Phase 1 (types)
+- Phase 3 (mergeCategories function)
+- Phase 4 (API route)
+- Phase 5 (UI component)
+
+**Why?** All non-Phase-2 code depends on the **interface**, not the **implementation**.
+
+---
+
+## Key Concepts
+
+### 1. Inheritance = Default Categories
+
+The backend provides a default set (e.g., Medusa categories). You inherit them by default, but can modify.
+
+### 2. Customization = Your Changes
+
+Your modifications (hidden, renamed, custom) are stored **independently** from base categories.
+
+This way:
+- Base categories can update from Medusa (new image, new subcategories)
+- Your customizations persist and reapply on top
+
+### 3. Effective Categories = Result
+
+What the storefront **actually sees** = base + customizations merged.
+
+The storefront never knows about inheritance. It just fetches categories and displays them.
+
+### 4. Metadata Storage = No Extra Database
+
+We use the backend's **metadata** field (exists in Medusa, Shopify, etc.).
+
+```
+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
+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
+7. Integrate into dashboard in L5
+
+---
+
+## FAQ
+
+### Q: Can I hide a category if customers already have it in their cart?
+
+**A**: Yes, but consider adding a migration script:
+- Categories hidden after purchase → show warning on checkout
+- Don't render "orphan" categories in storefront
+- Backend (Medusa) still serves the products (they exist, just not categorized)
+
+### Q: What if I rename a category but Medusa updates the base category name?
+
+**A**: The renamed version wins. Custom > Base.
+
+If you want to un-rename, just delete the entry from the `renamed` map.
+
+### Q: Can I have nested custom categories?
+
+**A**: Yes, use `parentCategoryId` in custom category objects.
+
+But ensure your storefront supports hierarchical rendering.
+
+### Q: What happens if I toggle inheritance off?
+
+**A**: Only custom categories show. Base categories are ignored (but not deleted).
+
+If you toggle back on, base categories reappear (minus any you've hidden).
+
+### Q: How do I add an image to a custom category?
+
+**A**: Custom categories support `metadata: { image: "..." }`.
+
+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`
+