@nocios/crudify-components 1.0.0

package/README_DEPTH.md

@@ -0,0 +1,1230 @@
+# @nocios/crudify-components - 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-components** 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-sdk
+- **🌍 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-components
+
+# 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-components";
+
+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-components";
+
+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-components";
+
+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-components";
+
+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-components";
+
+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-components";
+
+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-components";
+import type { CrudifyLoginConfig } from "@nocios/crudify-components";
+
+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-components";
+
+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-components";
+
+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-components";
+
+function DevPage() {
+  return (
+    <div>
+      <h2>Información de Sesión (Dev)</h2>
+      <SessionDebugInfo />
+    </div>
+  );
+}
+```
+
+### Policies - Gestión de Políticas Públicas
+
+Componente completo para configurar políticas de acceso a datos públicos:
+
+```tsx
+import { Policies, POLICY_ACTIONS, PREFERRED_POLICY_ORDER, PolicyAction } from "@nocios/crudify-components";
+import { useState } from "react";
+
+function ModuleConfiguration() {
+  const [policies, setPolicies] = useState([
+    {
+      id: "1",
+      action: "read",
+      fields: {
+        allow: ["name", "email"],
+        owner_allow: ["phone"],
+        deny: ["password", "internal_notes"],
+      },
+    },
+    {
+      id: "2",
+      action: "create",
+      fields: {
+        allow: ["name", "email"],
+        owner_allow: [],
+        deny: ["status", "verified"],
+      },
+    },
+  ]);
+
+  const availableFields = ["name", "email", "phone", "address", "status", "verified", "password", "internal_notes"];
+
+  const handlePolicyChange = (newPolicies) => {
+    setPolicies(newPolicies);
+    // Guardar en base de datos o estado global
+  };
+
+  return (
+    <div>
+      <h2>Configuración de Políticas Públicas</h2>
+
+      <Policies
+        policies={policies}
+        onChange={handlePolicyChange}
+        availableFields={availableFields}
+        errors={null} // O errores de validación del servidor
+        isSubmitting={false}
+      />
+
+      {/* Mostrar acciones disponibles */}
+      <div style={{ marginTop: "20px" }}>
+        <h3>Acciones Disponibles:</h3>
+        <ul>
+          {POLICY_ACTIONS.map((action) => (
+            <li key={action}>{action}</li>
+          ))}
+        </ul>
+      </div>
+    </div>
+  );
+}
+```
+
+#### Propiedades del Componente Policies
+
+| Prop              | Tipo                           | Requerido | Descripción                             |
+| ----------------- | ------------------------------ | --------- | --------------------------------------- |
+| `policies`        | `Policy[]`                     | ✅        | Array de políticas configuradas         |
+| `onChange`        | `(policies: Policy[]) => void` | ✅        | Callback cuando cambian las políticas   |
+| `availableFields` | `string[]`                     | ✅        | Campos disponibles para configurar      |
+| `errors`          | `string \| object`             | ❌        | Errores de validación                   |
+| `isSubmitting`    | `boolean`                      | ❌        | Estado de envío (deshabilita controles) |
+
+#### Estructura de una Policy
+
+```tsx
+type Policy = {
+  id: string; // ID único de la política
+  action: PolicyAction; // 'create' | 'read' | 'update' | 'delete'
+
+  // Para acciones create, read, update:
+  fields?: {
+    allow: string[]; // Campos permitidos para todos
+    owner_allow: string[]; // Campos adicionales para el propietario
+    deny: string[]; // Campos explícitamente denegados
+  };
+
+  // Para acción delete:
+  permission?: string; // '*' | 'deny' | 'owner'
+};
+```
+
+#### Constantes Disponibles
+
+```tsx
+// Acciones de política disponibles
+export const POLICY_ACTIONS = ["create", "read", "update", "delete"] as const;
+export type PolicyAction = (typeof POLICY_ACTIONS)[number];
+
+// Orden preferido para mostrar las políticas
+export const PREFERRED_POLICY_ORDER: PolicyAction[] = ["create", "read", "update", "delete"];
+```
+
+#### Casos de Uso Comunes
+
+**1. Configuración de API Pública**
+
+```tsx
+// Permitir lectura pública de ciertos campos
+const publicReadPolicy = {
+  id: "public-read",
+  action: "read",
+  fields: {
+    allow: ["name", "description", "published_at"],
+    owner_allow: ["views", "stats"],
+    deny: ["internal_notes", "admin_flags"],
+  },
+};
+```
+
+**2. Restricciones de Creación**
+
+```tsx
+// Permitir creación pero restringir ciertos campos
+const createPolicy = {
+  id: "public-create",
+  action: "create",
+  fields: {
+    allow: ["title", "content", "category"],
+    owner_allow: [],
+    deny: ["status", "featured", "admin_verified"],
+  },
+};
+```
+
+**3. Permisos de Eliminación**
+
+```tsx
+// Solo el propietario puede eliminar
+const deletePolicy = {
+  id: "owner-delete",
+  action: "delete",
+  permission: "owner", // '*' = todos, 'deny' = nadie, 'owner' = solo propietario
+};
+```
+
+#### Manejo de Errores
+
+```tsx
+function PolicyManager() {
+  const [errors, setErrors] = useState(null);
+
+  const handleSubmit = async (policies) => {
+    try {
+      await saveModulePolicies(moduleId, policies);
+      setErrors(null);
+    } catch (error) {
+      // Error de campo específico
+      if (error.fieldErrors) {
+        setErrors({
+          _error: "Hay errores en la configuración",
+          ...error.fieldErrors,
+        });
+      } else {
+        // Error general
+        setErrors("Error al guardar las políticas");
+      }
+    }
+  };
+
+  return (
+    <Policies
+      policies={policies}
+      onChange={setPolicies}
+      availableFields={fields}
+      errors={errors} // Se mostrará como Alert en el componente
+      isSubmitting={isLoading}
+    />
+  );
+}
+```
+
+#### Integración con i18next
+
+El componente usa react-i18next para internacionalización. Las claves de traducción incluidas:
+
+```json
+{
+  "modules": {
+    "form": {
+      "publicPolicies": {
+        "title": "Políticas Públicas",
+        "description": "Configura qué datos pueden acceder los usuarios públicos",
+        "noPolicies": "No hay políticas configuradas. Agrega una política para comenzar.",
+        "addPolicy": "Agregar Política",
+        "actions": {
+          "create": "Crear",
+          "read": "Leer",
+          "update": "Actualizar",
+          "delete": "Eliminar"
+        }
+      }
+    }
+  }
+}
+```
+
+#### Características del Componente
+
+- ✅ **Interfaz Intuitiva**: UI clara para gestionar permisos complejos
+- ✅ **Validación en Tiempo Real**: Errores mostrados inmediatamente
+- ✅ **Scroll Automático**: Nuevo ítem automáticamente visible
+- ✅ **Prevención de Duplicados**: No permite acciones duplicadas
+- ✅ **Orden Lógico**: Políticas ordenadas según PREFERRED_POLICY_ORDER
+- ✅ **Responsive**: Adaptable a diferentes tamaños de pantalla
+- ✅ **Internacionalización**: Soporte completo para múltiples idiomas
+
+## 🛠️ Utilidades
+
+### JWT Utils
+
+Utilidades para trabajar con tokens JWT:
+
+```tsx
+import { decodeJwtSafely, getCurrentUserEmail, isTokenExpired } from "@nocios/crudify-components";
+
+// 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-components";
+import type { TokenData, StorageType } from "@nocios/crudify-components";
+
+// 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-components";
+import type { ParsedError, ErrorCode } from "@nocios/crudify-components";
+
+// 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-sdk`, proporcionando una API unificada:
+
+```tsx
+import { crudify } from "@nocios/crudify-components";
+// Equivale a: import crudify from '@nocios/crudify-sdk';
+
+// 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-components`
+- ✅ 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-components";
+
+// 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-components';
+
+// 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-components";
+import type { UseSessionOptions } from "@nocios/crudify-components";
+
+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-components";
+
+// 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-components";
+
+// 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-components";
+
+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-components";
+
+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-sdk
+
+## 📄 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.