@nocios/crudify-ui 1.3.1 → 1.3.2

package/README_DEPTH.md

@@ -0,0 +1,1046 @@
+# @nocios/crudify-ui - Documentación Completa
+
+[![npm version](https://badge.fury.io/js/%40nocios%2Fcrudify-ui.svg)](https://badge.fury.io/js/%40nocios%2Fcrudify-ui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**@nocios/crudify-ui** es una biblioteca completa de componentes UI y hooks de React para aplicaciones que utilizan el sistema Crudify. Proporciona autenticación moderna con Refresh Token Pattern, manejo de sesiones, componentes de UI listos para usar y una API unificada.
+
+## 🚀 Características Principales
+
+- **🔐 Autenticación Moderna**: Sistema completo con Refresh Token Pattern
+- **⚡ Manejo de Sesiones**: Persistencia automática y sincronización cross-tab
+- **🎨 Componentes UI**: Componentes React pre-construidos con Material-UI
+- **🪝 React Hooks**: Hooks especializados para operaciones CRUD y autenticación
+- **🔄 API Unificada**: Re-exporta completamente @nocios/crudify-browser
+- **🌍 Internacionalización**: Soporte completo para múltiples idiomas
+- **💾 Almacenamiento Seguro**: Encriptación de tokens con múltiples opciones de storage
+- **📱 TypeScript**: Completamente tipado para mejor experiencia de desarrollo
+
+## 📦 Instalación
+
+```bash
+npm install @nocios/crudify-ui
+
+# Peer dependencies (si no las tienes instaladas)
+npm install @mui/material @mui/icons-material react react-dom
+```
+
+### Peer Dependencies Requeridas
+
+```json
+{
+  "@mui/icons-material": "^7.1.0",
+  "@mui/material": "^7.1.0",
+  "react": "^19.1.0",
+  "react-dom": "^19.1.0"
+}
+```
+
+## 🏗️ Configuración Inicial
+
+### 1. Configurar SessionProvider
+
+El `SessionProvider` es el punto de entrada principal para manejar la autenticación y sesiones en tu aplicación:
+
+```tsx
+import React from 'react';
+import { SessionProvider } from '@nocios/crudify-ui';
+
+function App() {
+  return (
+    <SessionProvider
+      options={{
+        // Configuración automática basada en variables de entorno
+        // o configuración manual si es necesario
+        storageType: 'localStorage', // 'localStorage' | 'sessionStorage'
+        onSessionExpired: () => {
+          console.log('Sesión expirada');
+        },
+        onSessionRestored: (tokens) => {
+          console.log('Sesión restaurada:', tokens);
+        }
+      }}
+    >
+      <YourApp />
+    </SessionProvider>
+  );
+}
+```
+
+### 2. Variables de Entorno
+
+La biblioteca detecta automáticamente la configuración desde las variables de entorno:
+
+```bash
+# .env
+REACT_APP_CRUDIFY_PUBLIC_API_KEY=tu_api_key_aquí
+REACT_APP_CRUDIFY_ENV=dev # dev | stg | api | prod
+```
+
+## 🪝 Hooks Principales
+
+### useAuth - Autenticación
+
+Hook principal para manejo completo de autenticación:
+
+```tsx
+import { useAuth } from '@nocios/crudify-ui';
+
+function LoginPage() {
+  const {
+    login,
+    logout,
+    isAuthenticated,
+    isLoading,
+    error,
+    clearError
+  } = useAuth();
+
+  const handleLogin = async () => {
+    try {
+      const result = await login('user@example.com', 'password');
+      console.log('Login exitoso:', result);
+    } catch (error) {
+      console.error('Error de login:', error);
+    }
+  };
+
+  const handleLogout = async () => {
+    await logout();
+  };
+
+  return (
+    <div>
+      {isAuthenticated ? (
+        <button onClick={handleLogout}>Cerrar Sesión</button>
+      ) : (
+        <button onClick={handleLogin} disabled={isLoading}>
+          {isLoading ? 'Iniciando...' : 'Iniciar Sesión'}
+        </button>
+      )}
+      {error && <div>Error: {error}</div>}
+    </div>
+  );
+}
+```
+
+**Características del useAuth:**
+- ✅ Login/logout automático con refresh tokens
+- ✅ Estado de autenticación en tiempo real
+- ✅ Manejo de errores integrado
+- ✅ Sincronización cross-tab
+- ✅ Validación automática de tokens
+
+### useUserData - Datos del Usuario
+
+Hook para obtener y manejar los datos completos del usuario:
+
+```tsx
+import { useUserData } from '@nocios/crudify-ui';
+
+function UserProfile() {
+  const {
+    userData,
+    sessionData,
+    isLoading,
+    error,
+    refetch
+  } = useUserData({
+    autoFetch: true, // Fetch automático al montar
+    retryOnError: true, // Retry automático en errores
+    cacheTime: 300000 // Cache por 5 minutos
+  });
+
+  if (isLoading) return <div>Cargando usuario...</div>;
+  if (error) return <div>Error: {error}</div>;
+
+  return (
+    <div>
+      <h2>Perfil de Usuario</h2>
+
+      {/* Datos del JWT (sessionData) */}
+      <p>Email: {sessionData?.email}</p>
+      <p>ID: {sessionData?._id}</p>
+
+      {/* Datos de la base de datos (userData) */}
+      <p>Nombre completo: {userData?.fullName}</p>
+      <p>Avatar: <img src={userData?.avatar} alt="Avatar" /></p>
+      <p>Último login: {userData?.lastLogin}</p>
+
+      <button onClick={() => refetch()}>
+        Actualizar Datos
+      </button>
+    </div>
+  );
+}
+```
+
+**Características del useUserData:**
+- ✅ Combina datos del JWT (sessionData) y de la BD (userData)
+- ✅ Auto-fetch con deduplicación inteligente
+- ✅ Retry automático en errores de red
+- ✅ Cache configurable
+- ✅ Refetch manual
+
+### useData - Operaciones CRUD
+
+Hook para realizar operaciones CRUD type-safe:
+
+```tsx
+import { useData } from '@nocios/crudify-ui';
+
+function ProductManager() {
+  const { create, read, update, remove, isInitialized } = useData();
+
+  const createProduct = async () => {
+    try {
+      const result = await create('products', {
+        name: 'Nuevo Producto',
+        price: 99.99,
+        category: 'electronics'
+      });
+      console.log('Producto creado:', result);
+    } catch (error) {
+      console.error('Error creando producto:', error);
+    }
+  };
+
+  const getProducts = async () => {
+    try {
+      const products = await read('products', {
+        filters: { category: 'electronics' },
+        limit: 10,
+        offset: 0
+      });
+      console.log('Productos:', products);
+    } catch (error) {
+      console.error('Error obteniendo productos:', error);
+    }
+  };
+
+  const updateProduct = async (productId: string) => {
+    try {
+      const result = await update('products', productId, {
+        price: 89.99
+      });
+      console.log('Producto actualizado:', result);
+    } catch (error) {
+      console.error('Error actualizando producto:', error);
+    }
+  };
+
+  const deleteProduct = async (productId: string) => {
+    try {
+      await remove('products', productId);
+      console.log('Producto eliminado');
+    } catch (error) {
+      console.error('Error eliminando producto:', error);
+    }
+  };
+
+  if (!isInitialized) return <div>Inicializando...</div>;
+
+  return (
+    <div>
+      <button onClick={createProduct}>Crear Producto</button>
+      <button onClick={getProducts}>Obtener Productos</button>
+      <button onClick={() => updateProduct('123')}>Actualizar</button>
+      <button onClick={() => deleteProduct('123')}>Eliminar</button>
+    </div>
+  );
+}
+```
+
+**Características del useData:**
+- ✅ Operaciones CRUD type-safe
+- ✅ Verificación automática de inicialización
+- ✅ Soporte para transacciones
+- ✅ Manejo de errores integrado
+
+### useSession - Sesión de Bajo Nivel
+
+Hook de bajo nivel para control directo de sesiones:
+
+```tsx
+import { useSession } from '@nocios/crudify-ui';
+
+function SessionManager() {
+  const {
+    isAuthenticated,
+    isLoading,
+    tokens,
+    error,
+    login,
+    logout,
+    refreshTokens,
+    isExpiringSoon,
+    expiresIn
+  } = useSession({
+    onSessionExpired: () => console.log('Sesión expirada'),
+    onSessionRestored: (tokens) => console.log('Sesión restaurada', tokens),
+    onTokensRefreshed: (tokens) => console.log('Tokens renovados', tokens)
+  });
+
+  return (
+    <div>
+      <h3>Estado de Sesión</h3>
+      <p>Autenticado: {isAuthenticated ? 'Sí' : 'No'}</p>
+      <p>Cargando: {isLoading ? 'Sí' : 'No'}</p>
+      <p>Expira en: {Math.floor(expiresIn / 60)} minutos</p>
+      <p>Expira pronto: {isExpiringSoon ? 'Sí' : 'No'}</p>
+
+      {isExpiringSoon && (
+        <button onClick={() => refreshTokens()}>
+          Renovar Tokens
+        </button>
+      )}
+
+      {tokens && (
+        <div>
+          <p>Access Token: {tokens.accessToken.substring(0, 20)}...</p>
+          <p>Refresh Token: {tokens.refreshToken?.substring(0, 20)}...</p>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### useSessionContext - Contexto de Sesión
+
+Hook para acceder al contexto global de sesión:
+
+```tsx
+import { useSessionContext } from '@nocios/crudify-ui';
+
+function NavigationBar() {
+  const {
+    isAuthenticated,
+    sessionData,
+    logout,
+    getTokenInfo
+  } = useSessionContext();
+
+  if (!isAuthenticated) return null;
+
+  return (
+    <nav>
+      <span>Bienvenido, {sessionData?.email}</span>
+      <button onClick={() => logout()}>Cerrar Sesión</button>
+      <button onClick={() => console.log(getTokenInfo())}>
+        Ver Token Info
+      </button>
+    </nav>
+  );
+}
+```
+
+## 🎨 Componentes UI
+
+### CrudifyLogin - Componente de Login Completo
+
+Componente completo de autenticación con múltiples pantallas:
+
+```tsx
+import { CrudifyLogin } from '@nocios/crudify-ui';
+import type { CrudifyLoginConfig } from '@nocios/crudify-ui';
+
+function AuthPage() {
+  const config: CrudifyLoginConfig = {
+    appName: "Mi Aplicación",
+    logo: "/logo.png",
+    colors: {
+      primaryColor: "#1066BA",
+      bgColor: "#f5f5f5"
+    }
+  };
+
+  const handleLoginSuccess = (userData, redirectUrl) => {
+    console.log('Login exitoso:', userData);
+    // Redireccionar o actualizar estado
+  };
+
+  const handleError = (error: string) => {
+    console.error('Error de autenticación:', error);
+  };
+
+  return (
+    <CrudifyLogin
+      config={config}
+      onLoginSuccess={handleLoginSuccess}
+      onError={handleError}
+      initialScreen="login" // "login" | "forgotPassword" | "resetPassword"
+      language="es" // "en" | "es"
+      redirectUrl="/dashboard"
+      autoReadFromCookies={true}
+    />
+  );
+}
+```
+
+**Pantallas incluidas en CrudifyLogin:**
+- 🔐 **Login**: Formulario principal de autenticación
+- 🔑 **Forgot Password**: Solicitar recuperación de contraseña
+- 📧 **Check Code**: Verificar código de recuperación
+- 🔄 **Reset Password**: Establecer nueva contraseña
+
+**Configuración disponible:**
+- ✅ Logo y nombre de aplicación personalizable
+- ✅ Colores y temas personalizables
+- ✅ Traducciones completas (ES/EN)
+- ✅ URLs de traducción externas
+- ✅ Callbacks para todos los eventos
+
+### UserProfileDisplay - Perfil de Usuario
+
+Componente para mostrar información del perfil del usuario:
+
+```tsx
+import { UserProfileDisplay } from '@nocios/crudify-ui';
+
+function ProfilePage() {
+  return (
+    <div>
+      <h1>Mi Perfil</h1>
+      <UserProfileDisplay />
+    </div>
+  );
+}
+```
+
+### ProtectedRoute - Protección de Rutas
+
+Componente para proteger rutas que requieren autenticación:
+
+```tsx
+import { ProtectedRoute } from '@nocios/crudify-ui';
+
+function App() {
+  return (
+    <Router>
+      <Routes>
+        <Route path="/login" element={<LoginPage />} />
+        <Route
+          path="/dashboard"
+          element={
+            <ProtectedRoute fallback={<LoginPage />}>
+              <Dashboard />
+            </ProtectedRoute>
+          }
+        />
+      </Routes>
+    </Router>
+  );
+}
+```
+
+### SessionDebugInfo - Debug de Sesión
+
+Componente útil para desarrollo y debug:
+
+```tsx
+import { SessionDebugInfo } from '@nocios/crudify-ui';
+
+function DevPage() {
+  return (
+    <div>
+      <h2>Información de Sesión (Dev)</h2>
+      <SessionDebugInfo />
+    </div>
+  );
+}
+```
+
+## 🛠️ Utilidades
+
+### JWT Utils
+
+Utilidades para trabajar con tokens JWT:
+
+```tsx
+import {
+  decodeJwtSafely,
+  getCurrentUserEmail,
+  isTokenExpired
+} from '@nocios/crudify-ui';
+
+// Decodificar JWT de forma segura
+const payload = decodeJwtSafely(token);
+console.log('Usuario ID:', payload?.sub);
+
+// Obtener email del usuario actual
+const email = getCurrentUserEmail();
+console.log('Email:', email);
+
+// Verificar si un token está expirado
+const expired = isTokenExpired(token);
+console.log('Token expirado:', expired);
+```
+
+### Token Storage
+
+Sistema de almacenamiento seguro para tokens:
+
+```tsx
+import { TokenStorage } from '@nocios/crudify-ui';
+import type { TokenData, StorageType } from '@nocios/crudify-ui';
+
+// Crear instancia de storage
+const storage = new TokenStorage({
+  type: 'localStorage', // 'localStorage' | 'sessionStorage'
+  encryptionKey: 'mi-clave-secreta'
+});
+
+// Guardar tokens
+const tokens: TokenData = {
+  accessToken: 'access_token_here',
+  refreshToken: 'refresh_token_here',
+  expiresIn: 3600,
+  refreshExpiresIn: 86400
+};
+
+await storage.setTokens(tokens);
+
+// Obtener tokens
+const storedTokens = await storage.getTokens();
+console.log('Tokens almacenados:', storedTokens);
+
+// Limpiar tokens
+await storage.clearTokens();
+
+// Verificar validez
+const isValid = await storage.isValid();
+console.log('Tokens válidos:', isValid);
+```
+
+### Error Handler
+
+Sistema completo de manejo de errores:
+
+```tsx
+import {
+  handleCrudifyError,
+  parseApiError,
+  parseTransactionError,
+  getErrorMessage,
+  ERROR_CODES
+} from '@nocios/crudify-ui';
+import type { ParsedError, ErrorCode } from '@nocios/crudify-ui';
+
+// Manejo universal de errores
+try {
+  // operación que puede fallar
+} catch (error) {
+  const parsedError: ParsedError = handleCrudifyError(error);
+
+  console.log('Tipo:', parsedError.type);
+  console.log('Código:', parsedError.code);
+  console.log('Mensaje:', parsedError.message);
+  console.log('Severidad:', parsedError.severity);
+
+  // Mostrar mensaje apropiado al usuario
+  const userMessage = getErrorMessage(parsedError.code as ErrorCode);
+  alert(userMessage);
+}
+
+// Parser específico para errores de API
+const apiError = parseApiError(response);
+
+// Parser específico para errores de transacción
+const transactionError = parseTransactionError(response);
+
+// Códigos de error disponibles
+console.log('Códigos disponibles:', ERROR_CODES);
+```
+
+## 🔄 API de Crudify Browser
+
+Esta librería re-exporta completamente `@nocios/crudify-browser`, proporcionando una API unificada:
+
+```tsx
+import { crudify } from '@nocios/crudify-ui';
+// Equivale a: import crudify from '@nocios/crudify-browser';
+
+// Todas las funcionalidades de crudify-browser están disponibles
+const result = await crudify.create('users', userData);
+const users = await crudify.read('users');
+```
+
+Esto significa que puedes:
+- ✅ Importar solo desde `@nocios/crudify-ui`
+- ✅ Usar todas las funcionalidades de crudify-browser
+- ✅ Tener una API unificada
+- ✅ Simplificar las dependencias
+
+## 📱 TypeScript Support
+
+La librería incluye tipos completos para TypeScript:
+
+```tsx
+import type {
+  // Tipos de API
+  CrudifyApiResponse,
+  CrudifyTransactionResponse,
+  UserProfile,
+  LoginResponse,
+  LoginRequest,
+
+  // Tipos de componentes
+  CrudifyLoginProps,
+  CrudifyLoginConfig,
+
+  // Tipos de hooks
+  UseAuthReturn,
+  UseUserDataReturn,
+  UseDataReturn,
+  SessionState,
+
+  // Tipos de utilidades
+  TokenData,
+  ParsedError,
+  ErrorCode
+} from '@nocios/crudify-ui';
+
+// Ejemplo con tipos
+const handleLogin = async (
+  credentials: LoginRequest
+): Promise<CrudifyApiResponse<LoginResponse>> => {
+  // implementación con tipos seguros
+};
+```
+
+## 🌐 Internacionalización
+
+### Configuración básica
+
+```tsx
+import { CrudifyLogin } from '@nocios/crudify-ui';
+
+// Usando traducciones incluidas
+<CrudifyLogin language="es" /> // "en" | "es"
+
+// Usando traducciones personalizadas
+<CrudifyLogin
+  language="es"
+  translations={{
+    login: {
+      title: "Iniciar Sesión",
+      email: "Correo Electrónico",
+      password: "Contraseña",
+      submit: "Entrar"
+    }
+  }}
+/>
+
+// Usando URL externa para traducciones
+<CrudifyLogin
+  language="es"
+  translationsUrl="/api/translations/es.json"
+/>
+```
+
+### Estructura de traducciones
+
+```json
+{
+  "login": {
+    "title": "Iniciar Sesión",
+    "email": "Correo Electrónico",
+    "password": "Contraseña",
+    "submit": "Entrar",
+    "forgotPassword": "¿Olvidaste tu contraseña?",
+    "logoAlt": "Logo de la aplicación"
+  },
+  "forgotPassword": {
+    "title": "Recuperar Contraseña",
+    "email": "Correo Electrónico",
+    "submit": "Enviar Código",
+    "backToLogin": "Volver al Login"
+  },
+  "resetPassword": {
+    "title": "Nueva Contraseña",
+    "password": "Nueva Contraseña",
+    "confirmPassword": "Confirmar Contraseña",
+    "submit": "Cambiar Contraseña"
+  }
+}
+```
+
+## 🔧 Configuración Avanzada
+
+### SessionProvider con opciones completas
+
+```tsx
+import { SessionProvider } from '@nocios/crudify-ui';
+import type { UseSessionOptions } from '@nocios/crudify-ui';
+
+const sessionOptions: UseSessionOptions = {
+  // Tipo de almacenamiento
+  storageType: 'localStorage', // 'localStorage' | 'sessionStorage'
+
+  // Callbacks del ciclo de vida
+  onSessionExpired: () => {
+    console.log('Sesión expirada - redirigir a login');
+    window.location.href = '/login';
+  },
+
+  onSessionRestored: (tokens) => {
+    console.log('Sesión restaurada exitosamente', tokens);
+  },
+
+  onTokensRefreshed: (tokens) => {
+    console.log('Tokens renovados', tokens);
+  },
+
+  onLogout: () => {
+    console.log('Usuario cerró sesión');
+  },
+
+  onError: (error) => {
+    console.error('Error de sesión:', error);
+  }
+};
+
+function App() {
+  return (
+    <SessionProvider options={sessionOptions}>
+      <Router>
+        <Routes>
+          {/* tus rutas */}
+        </Routes>
+      </Router>
+    </SessionProvider>
+  );
+}
+```
+
+### Configuración manual de Crudify
+
+Si necesitas configuración manual en lugar de variables de entorno:
+
+```tsx
+import { crudify } from '@nocios/crudify-ui';
+
+// Configurar manualmente antes de usar
+crudify.configure({
+  publicApiKey: 'tu-api-key',
+  environment: 'production', // 'dev' | 'stg' | 'api' | 'prod'
+  baseUrl: 'https://api.tudominio.com' // opcional
+});
+```
+
+## 🚀 Ejemplos de Uso Completos
+
+### Aplicación básica con autenticación
+
+```tsx
+import React from 'react';
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
+import {
+  SessionProvider,
+  ProtectedRoute,
+  CrudifyLogin,
+  useSessionContext
+} from '@nocios/crudify-ui';
+
+// Componente Dashboard
+function Dashboard() {
+  const { sessionData, logout } = useSessionContext();
+
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <p>Bienvenido, {sessionData?.email}</p>
+      <button onClick={() => logout()}>Cerrar Sesión</button>
+    </div>
+  );
+}
+
+// Componente Login
+function LoginPage() {
+  return (
+    <div style={{ maxWidth: '400px', margin: '0 auto', padding: '2rem' }}>
+      <CrudifyLogin
+        config={{
+          appName: "Mi App",
+          colors: { primaryColor: "#1976d2" }
+        }}
+        onLoginSuccess={(userData) => {
+          console.log('Login exitoso:', userData);
+          // La navegación se maneja automáticamente
+        }}
+      />
+    </div>
+  );
+}
+
+// Aplicación principal
+function App() {
+  return (
+    <SessionProvider>
+      <BrowserRouter>
+        <Routes>
+          <Route path="/login" element={<LoginPage />} />
+          <Route
+            path="/dashboard"
+            element={
+              <ProtectedRoute fallback={<Navigate to="/login" />}>
+                <Dashboard />
+              </ProtectedRoute>
+            }
+          />
+          <Route path="/" element={<Navigate to="/dashboard" />} />
+        </Routes>
+      </BrowserRouter>
+    </SessionProvider>
+  );
+}
+
+export default App;
+```
+
+### Aplicación con operaciones CRUD
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { useData, useUserData } from '@nocios/crudify-ui';
+
+function ProductManager() {
+  const [products, setProducts] = useState([]);
+  const [loading, setLoading] = useState(false);
+
+  const { create, read, update, remove } = useData();
+  const { userData } = useUserData();
+
+  // Cargar productos al montar
+  useEffect(() => {
+    loadProducts();
+  }, []);
+
+  const loadProducts = async () => {
+    setLoading(true);
+    try {
+      const result = await read('products', {
+        filters: { userId: userData?.id },
+        limit: 20
+      });
+      setProducts(result.data || []);
+    } catch (error) {
+      console.error('Error cargando productos:', error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const createProduct = async (productData) => {
+    try {
+      await create('products', {
+        ...productData,
+        userId: userData?.id
+      });
+      await loadProducts(); // Recargar lista
+    } catch (error) {
+      console.error('Error creando producto:', error);
+    }
+  };
+
+  const updateProduct = async (productId, updates) => {
+    try {
+      await update('products', productId, updates);
+      await loadProducts(); // Recargar lista
+    } catch (error) {
+      console.error('Error actualizando producto:', error);
+    }
+  };
+
+  const deleteProduct = async (productId) => {
+    try {
+      await remove('products', productId);
+      await loadProducts(); // Recargar lista
+    } catch (error) {
+      console.error('Error eliminando producto:', error);
+    }
+  };
+
+  if (loading) return <div>Cargando productos...</div>;
+
+  return (
+    <div>
+      <h2>Mis Productos</h2>
+
+      <button onClick={() => createProduct({
+        name: 'Nuevo Producto',
+        price: 99.99
+      })}>
+        Crear Producto
+      </button>
+
+      <ul>
+        {products.map(product => (
+          <li key={product.id}>
+            <span>{product.name} - ${product.price}</span>
+            <button onClick={() => updateProduct(product.id, {
+              price: product.price * 1.1
+            })}>
+              Aumentar Precio 10%
+            </button>
+            <button onClick={() => deleteProduct(product.id)}>
+              Eliminar
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## 🔒 Seguridad
+
+### Características de Seguridad
+
+- ✅ **Encriptación de tokens**: Los tokens se almacenan encriptados
+- ✅ **Refresh Token Pattern**: Tokens de acceso de corta duración
+- ✅ **Validación automática**: Verificación de expiración y renovación
+- ✅ **Almacenamiento seguro**: Soporte para localStorage y sessionStorage
+- ✅ **Limpieza automática**: Tokens expirados se limpian automáticamente
+
+### Mejores Prácticas
+
+```tsx
+// 1. Usar SessionProvider en el nivel más alto
+function App() {
+  return (
+    <SessionProvider options={{
+      storageType: 'localStorage', // Más persistente
+      onSessionExpired: handleSessionExpired
+    }}>
+      <YourApp />
+    </SessionProvider>
+  );
+}
+
+// 2. Proteger rutas sensibles
+<ProtectedRoute fallback={<LoginRedirect />}>
+  <SensitiveComponent />
+</ProtectedRoute>
+
+// 3. Manejar errores de autenticación
+const { error, clearError } = useAuth();
+useEffect(() => {
+  if (error) {
+    console.error('Error de auth:', error);
+    // Mostrar notificación al usuario
+    clearError();
+  }
+}, [error]);
+
+// 4. Limpiar sesión al salir
+useEffect(() => {
+  const handleBeforeUnload = () => {
+    // Opcional: limpiar datos sensibles
+  };
+
+  window.addEventListener('beforeunload', handleBeforeUnload);
+  return () => window.removeEventListener('beforeunload', handleBeforeUnload);
+}, []);
+```
+
+## 🐛 Troubleshooting
+
+### Problemas Comunes
+
+**1. Token expirado constantemente**
+```tsx
+// Verificar configuración de refresh tokens
+const { isExpiringSoon, refreshTokens } = useSession();
+
+useEffect(() => {
+  if (isExpiringSoon) {
+    refreshTokens();
+  }
+}, [isExpiringSoon]);
+```
+
+**2. Sesión no se restaura al recargar**
+```tsx
+// Asegurar que SessionProvider esté en el nivel correcto
+// y verificar storageType
+<SessionProvider options={{ storageType: 'localStorage' }}>
+```
+
+**3. Errores de CORS**
+```tsx
+// Verificar configuración de environment
+crudify.configure({
+  environment: 'dev', // Asegurar environment correcto
+  publicApiKey: process.env.REACT_APP_CRUDIFY_PUBLIC_API_KEY
+});
+```
+
+### Debug
+
+```tsx
+// Usar SessionDebugInfo para desarrollo
+import { SessionDebugInfo } from '@nocios/crudify-ui';
+
+function DevPanel() {
+  return process.env.NODE_ENV === 'development' ? (
+    <div style={{ position: 'fixed', bottom: 0, right: 0, background: 'white', padding: '1rem' }}>
+      <SessionDebugInfo />
+    </div>
+  ) : null;
+}
+```
+
+## 📚 Referencias de API
+
+### Hooks API Reference
+
+| Hook | Propósito | Returns |
+|------|-----------|---------|
+| `useAuth` | Autenticación principal | `{ login, logout, isAuthenticated, isLoading, error }` |
+| `useUserData` | Datos del usuario | `{ userData, sessionData, isLoading, error, refetch }` |
+| `useData` | Operaciones CRUD | `{ create, read, update, remove, isInitialized }` |
+| `useSession` | Control de sesión | `{ tokens, isAuthenticated, refreshTokens, expiresIn }` |
+| `useSessionContext` | Contexto global | `{ sessionData, isAuthenticated, logout, getTokenInfo }` |
+
+### Componentes API Reference
+
+| Componente | Props Principales | Propósito |
+|------------|-------------------|-----------|
+| `SessionProvider` | `options: UseSessionOptions` | Provider global de sesión |
+| `CrudifyLogin` | `config, onLoginSuccess, language` | Componente de login completo |
+| `ProtectedRoute` | `fallback, children` | Protección de rutas |
+| `UserProfileDisplay` | `showAvatar, showDetails` | Display de perfil |
+
+### Utilidades API Reference
+
+| Utilidad | Funciones | Propósito |
+|----------|-----------|-----------|
+| `JWT Utils` | `decodeJwtSafely, getCurrentUserEmail, isTokenExpired` | Manejo de JWT |
+| `Token Storage` | `setTokens, getTokens, clearTokens, isValid` | Almacenamiento seguro |
+| `Error Handler` | `handleCrudifyError, parseApiError, getErrorMessage` | Manejo de errores |
+
+## 🔄 Changelog
+
+### v1.3.1
+- ✅ Sistema completo de Refresh Token Pattern
+- ✅ Hooks modernos (useAuth, useUserData, useData)
+- ✅ SessionProvider con contexto global
+- ✅ Componentes ProtectedRoute y SessionDebugInfo
+- ✅ Almacenamiento encriptado de tokens
+- ✅ Sistema completo de manejo de errores
+- ✅ Re-exportación completa de @nocios/crudify-browser
+
+## 📄 Licencia
+
+MIT © [Nocios](https://github.com/nocios)
+
+## 🤝 Contribuir
+
+Si encuentras bugs o tienes sugerencias, por favor crea un issue en el repositorio oficial.
+
+---
+
+**¿Necesitas ayuda?** Consulta la documentación completa o contacta al equipo de desarrollo.