@nocios/crudify-ui 1.1.0 → 1.2.2

package/README.md

@@ -1,8 +1,8 @@
-# CrudifyLogin - Integracion Completa
+# @nocios/crudify-ui - Sistema Completo de Autenticación y CRUD
 
-> Componente de autenticacion completo y reutilizable para aplicaciones React, basado en la API de Crudify.
+> Biblioteca completa de componentes React para autenticación y operaciones CRUD, basada en la API de Crudify con sistema de inicialización robusto y gestión unificada de estado.
 
-## 🚀 Instalacion
+## 🚀 Instalación
 
 ```bash
 npm install @nocios/crudify-ui
@@ -10,23 +10,343 @@ npm install @nocios/crudify-ui
 
 ## 📋 Dependencias Requeridas
 
-Asegurate de tener estas dependencias en tu proyecto:
+Asegúrate de tener estas dependencias en tu proyecto:
 
 ```bash
-npm install react react-dom @mui/material @mui/icons-material
+npm install react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled
 ```
 
-## 🎯 Uso Basico
+## ⭐ **NUEVO: Sistema Unificado (Recomendado)**
 
-### Integracion Simple
+### 🏗️ Implementación con CrudifyDataProvider
+
+El nuevo sistema unificado proporciona inicialización robusta, gestión automática de tokens y operaciones CRUD sin configuración compleja:
+
+```tsx
+// App.tsx - Configuración principal
+import React from 'react';
+import { CrudifyDataProvider } from '@nocios/crudify-ui';
+import AppContent from './AppContent';
+
+function App() {
+  return (
+    <CrudifyDataProvider
+      publicApiKey={process.env.REACT_APP_CRUDIFY_API_KEY}
+      env={process.env.NODE_ENV === 'development' ? 'dev' : 'prod'}
+      appName="Mi Aplicación"
+    >
+      <AppContent />
+    </CrudifyDataProvider>
+  );
+}
+
+export default App;
+```
+
+```tsx
+// AppContent.tsx - Lógica de autenticación
+import React from 'react';
+import { useCrudifyAuth, CrudifyLogin } from '@nocios/crudify-ui';
+import Dashboard from './Dashboard';
+
+function AppContent() {
+  const { isAuthenticated, token, setToken, user, loading } = useCrudifyAuth();
+
+  if (loading) {
+    return <div>Cargando...</div>;
+  }
+
+  if (!isAuthenticated) {
+    return (
+      <CrudifyLogin
+        onLoginSuccess={(newToken) => {
+          setToken(newToken); // ✅ Sincronización automática
+          // No necesitas manejar redirección manual
+        }}
+        config={{
+          colors: { primaryColor: "#1066BA" },
+          loginActions: ["forgotPassword"]
+        }}
+      />
+    );
+  }
+
+  return <Dashboard user={user} />;
+}
+```
 
 ```tsx
-import { CrudifyLogin } from "@nocios/crudify-ui";
+// Dashboard.tsx - Uso de operaciones CRUD
+import React, { useEffect, useState } from 'react';
+import { useCrudifyData } from '@nocios/crudify-ui';
+
+function Dashboard({ user }) {
+  const { readItems, createItem, isReady, loading } = useCrudifyData();
+  const [items, setItems] = useState([]);
+
+  useEffect(() => {
+    if (isReady) {
+      loadItems();
+    }
+  }, [isReady]);
+
+  const loadItems = async () => {
+    try {
+      const response = await readItems('products', { active: true });
+      if (response.success) {
+        setItems(response.data);
+      }
+    } catch (error) {
+      console.error('Error loading items:', error);
+    }
+  };
+
+  if (!isReady) {
+    return <div>Inicializando sistema...</div>;
+  }
+
+  return (
+    <div>
+      <h1>Dashboard - {user?.name}</h1>
+      <div>
+        {items.map(item => (
+          <div key={item.id}>{item.name}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## 🔧 **Hooks Disponibles**
+
+### 🎯 **useCrudifyAuth** - Gestión de Autenticación
+
+Hook principal para manejar el estado de autenticación:
+
+```tsx
+import { useCrudifyAuth } from '@nocios/crudify-ui';
+
+function AuthComponent() {
+  const {
+    isAuthenticated,    // boolean - Si el usuario está autenticado
+    token,             // string | null - Token JWT actual
+    setToken,          // (token: string | null) => void - Función para establecer token
+    user,              // object | null - Datos del usuario
+    loading,           // boolean - Estado de carga
+    login,             // (email: string, password: string) => Promise<CrudifyApiResponse>
+    logout,            // () => void - Función para logout
+    refreshUserData    // () => Promise<void> - Actualizar datos del usuario
+  } = useCrudifyAuth();
+
+  return (
+    <div>
+      {isAuthenticated ? (
+        <div>
+          <h1>Bienvenido, {user?.name}</h1>
+          <button onClick={logout}>Cerrar Sesión</button>
+        </div>
+      ) : (
+        <div>No autenticado</div>
+      )}
+    </div>
+  );
+}
+```
+
+### 📊 **useCrudifyData** - Operaciones CRUD
+
+Hook para realizar operaciones CRUD con inicialización automática:
+
+```tsx
+import { useCrudifyData } from '@nocios/crudify-ui';
+
+function DataComponent() {
+  const {
+    readItems,         // (moduleKey: string, filter?: object, options?: any) => Promise<CrudifyApiResponse>
+    readItem,          // (moduleKey: string, filter: object, options?: any) => Promise<CrudifyApiResponse>
+    createItem,        // (moduleKey: string, data: object, options?: any) => Promise<CrudifyApiResponse>
+    updateItem,        // (moduleKey: string, data: object, options?: any) => Promise<CrudifyApiResponse>
+    deleteItem,        // (moduleKey: string, id: string, options?: any) => Promise<CrudifyApiResponse>
+    transaction,       // (operations: any[], options?: any) => Promise<CrudifyApiResponse>
+    getStructure,      // (options?: any) => Promise<CrudifyApiResponse>
+    getStructurePublic,// (options?: any) => Promise<CrudifyApiResponse>
+    isReady,           // boolean - Si el sistema está listo para operaciones
+    loading            // boolean - Estado de carga
+  } = useCrudifyData();
+
+  const handleLoadProducts = async () => {
+    if (!isReady) return;
+
+    try {
+      const response = await readItems('products', { active: true });
+      if (response.success) {
+        console.log('Productos:', response.data);
+      }
+    } catch (error) {
+      console.error('Error:', error);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleLoadProducts} disabled={!isReady}>
+        Cargar Productos
+      </button>
+    </div>
+  );
+}
+```
+
+### 👤 **useCrudifyUser** - Gestión de Usuario
+
+Hook especializado para datos del usuario:
+
+```tsx
+import { useCrudifyUser } from '@nocios/crudify-ui';
+
+function UserProfile() {
+  const {
+    user,              // object | null - Datos del usuario
+    loading,           // boolean - Estado de carga
+    error,             // string | null - Error si existe
+    refreshUserData,   // () => Promise<void> - Actualizar datos
+    updateUserProfile, // (data: object) => Promise<CrudifyApiResponse>
+    isReady           // boolean - Si está listo
+  } = useCrudifyUser();
+
+  if (loading) return <div>Cargando perfil...</div>;
+  if (error) return <div>Error: {error}</div>;
+
+  return (
+    <div>
+      <h2>Perfil de Usuario</h2>
+      <p>Nombre: {user?.name}</p>
+      <p>Email: {user?.email}</p>
+      <button onClick={refreshUserData}>Actualizar Datos</button>
+    </div>
+  );
+}
+```
+
+### ⚙️ **useCrudifyConfig** - Acceso a Configuración
+
+Hook para acceder a la configuración actual:
+
+```tsx
+import { useCrudifyConfig } from '@nocios/crudify-ui';
+
+function ConfigDisplay() {
+  const {
+    config,            // CrudifyConfig - Configuración actual
+    updateConfig,      // (newConfig: Partial<CrudifyConfig>) => void
+    isConfigured,      // boolean - Si está configurado
+    environment        // string - Entorno actual (dev, prod, etc.)
+  } = useCrudifyConfig();
+
+  return (
+    <div>
+      <h3>Configuración Actual</h3>
+      <p>App: {config.appName}</p>
+      <p>Entorno: {environment}</p>
+      <p>Configurado: {isConfigured ? 'Sí' : 'No'}</p>
+    </div>
+  );
+}
+```
+
+## ⚙️ **Configuración del CrudifyDataProvider**
+
+### Props del Provider
+
+```tsx
+interface CrudifyDataProviderProps {
+  children: React.ReactNode;
+
+  // Configuración básica
+  publicApiKey?: string;           // Clave de API de Crudify
+  env?: 'dev' | 'stg' | 'api' | 'prod'; // Entorno
+  appName?: string;                // Nombre de la aplicación
+
+  // Configuración visual
+  logo?: string;                   // URL del logo
+  colors?: {
+    primaryColor?: string;         // Color principal
+    bgColor?: string;             // Color de fondo
+    [key: string]: string | undefined;
+  };
+
+  // Configuración avanzada
+  autoReadFromCookies?: boolean;   // Leer configuración desde cookies (default: true)
+  autoInitialize?: boolean;        // Inicializar automáticamente (default: true)
+  persistToken?: boolean;          // Persistir token entre sesiones (default: true)
+
+  // Configuración de login
+  loginActions?: string[];         // Acciones disponibles: ["forgotPassword", "createUser"]
+
+  // Callbacks opcionales
+  onInitialized?: () => void;      // Callback cuando se inicializa
+  onError?: (error: string) => void; // Callback para errores
+  onTokenChange?: (token: string | null) => void; // Callback cuando cambia el token
+}
+```
+
+### Ejemplo de Configuración Completa
+
+```tsx
+import { CrudifyDataProvider } from '@nocios/crudify-ui';
+
+function App() {
+  return (
+    <CrudifyDataProvider
+      // Configuración básica
+      publicApiKey={process.env.REACT_APP_CRUDIFY_API_KEY}
+      env={process.env.NODE_ENV === 'development' ? 'dev' : 'prod'}
+      appName="Mi Aplicación"
+
+      // Configuración visual
+      logo="/logo.png"
+      colors={{
+        primaryColor: "#1066BA",
+        bgColor: "#f5f5f5"
+      }}
+
+      // Configuración avanzada
+      autoReadFromCookies={true}
+      autoInitialize={true}
+      persistToken={true}
+
+      // Acciones de login disponibles
+      loginActions={["forgotPassword", "createUser"]}
+
+      // Callbacks
+      onInitialized={() => console.log('Sistema inicializado')}
+      onError={(error) => console.error('Error del sistema:', error)}
+      onTokenChange={(token) => console.log('Token actualizado:', !!token)}
+    >
+      <AppContent />
+    </CrudifyDataProvider>
+  );
+}
+```
+
+## 🎨 **Componente CrudifyLogin**
+
+### Uso Standalone (Sistema Legacy)
+
+Para uso directo del componente de login sin el provider unificado:
+
+```tsx
+import { CrudifyLogin } from '@nocios/crudify-ui';
 
 function LoginPage() {
   const handleLoginSuccess = (token: string, redirectUrl?: string) => {
-    // Guardar token y redirigir
+    // ⚠️ Importante: Sincronizar con el sistema global
     sessionStorage.setItem("authToken", token);
+
+    // Si usas CrudifyDataProvider, también sincronizar ahí
+    // setToken(token); // usando useCrudifyAuth
+
     window.location.href = redirectUrl || "/dashboard";
   };
 
@@ -35,60 +355,63 @@ function LoginPage() {
       config={{
         publicApiKey: "tu-api-key",
         env: "prod",
-        appName: "Mi Aplicacion",
+        appName: "Mi Aplicación",
+        logo: "/logo.png",
+        colors: {
+          primaryColor: "#1066BA",
+          bgColor: "#f5f5f5"
+        },
+        loginActions: ["forgotPassword", "createUser"]
       }}
       onLoginSuccess={handleLoginSuccess}
+      onError={(error) => console.error('Login error:', error)}
       redirectUrl="/dashboard"
+      language="es"
     />
   );
 }
 ```
 
-## ⚙️ Configuracion Completa
-
-### Props del Componente
-
-| Prop                  | Tipo                                            | Default   | Descripcion                       |
-| --------------------- | ----------------------------------------------- | --------- | --------------------------------- |
-| `config`              | `CrudifyLoginConfig`                            | `{}`      | Configuracion del componente      |
-| `onLoginSuccess`      | `(token: string, redirectUrl?: string) => void` | -         | Callback cuando login es exitoso  |
-| `onError`             | `(error: string) => void`                       | -         | Callback para manejo de errores   |
-| `onScreenChange`      | `(screen: string, params?: object) => void`     | -         | Callback para cambios de pantalla |
-| `onExternalNavigate`  | `(path: string) => void`                        | -         | Callback para navegacion externa  |
-| `initialScreen`       | `login,forgotPassword,resetPassword,checkCode`  | `"login"` | Pantalla inicial                  |
-| `redirectUrl`         | `string`                                        | `"/"`     | URL de redireccion post-login     |
-| `autoReadFromCookies` | `boolean`                                       | `true`    | Leer configuracion desde cookies  |
-| `language`            | `string`                                        | `"en"`    | Idioma de la interfaz             |
-| `translations`        | `CrudifyLoginTranslations`                      | -         | Traducciones customizadas         |
-| `translationsUrl`     | `string`                                        | -         | URL para cargar traducciones      |
-
-### Configuracion (CrudifyLoginConfig)
+### Props del CrudifyLogin
 
 ```tsx
-interface CrudifyLoginConfig {
-  publicApiKey?: string; // Clave de API de Crudify
-  env?: "dev" | "stg" | "api" | "prod"; // Entorno de la API
-  appName?: string; // Nombre de tu aplicacion
-  logo?: string; // URL del logo
-  colors?: {
-    primaryColor?: string; // Color principal
-    bgColor?: string; // Color de fondo
-    [key: string]: string | undefined;
-  };
-  loginActions?: string[]; // Acciones disponibles: ["forgotPassword", "createUser"]
+interface CrudifyLoginProps {
+  // Configuración
+  config?: CrudifyLoginConfig;
+
+  // Callbacks
+  onLoginSuccess?: (token: string, redirectUrl?: string) => void;
+  onError?: (error: string) => void;
+  onScreenChange?: (screen: string, params?: object) => void;
+  onExternalNavigate?: (path: string) => void;
+
+  // Navegación
+  initialScreen?: 'login' | 'forgotPassword' | 'resetPassword' | 'checkCode';
+  redirectUrl?: string;
+
+  // Personalización
+  language?: string;
+  translations?: CrudifyLoginTranslations;
+  translationsUrl?: string;
+
+  // Opciones
+  autoReadFromCookies?: boolean;
 }
 ```
 
-## 🎨 Personalizacion Visual
-
-### Colores y Branding
+### Personalización Visual
 
 ```tsx
 <CrudifyLogin
   config={{
     appName: "Mi App",
     logo: "/mi-logo.png",
-    colors: { primaryColor: "#1066BA", bgColor: "#f5f5f5" },
+    colors: {
+      primaryColor: "#1066BA",
+      bgColor: "#f5f5f5",
+      textColor: "#333333",
+      buttonTextColor: "#ffffff"
+    },
   }}
 />
 ```
@@ -97,65 +420,63 @@ interface CrudifyLoginConfig {
 
 ```tsx
 const misTraduciones = {
-  "login.title": "Iniciar Sesion",
+  "login.title": "Iniciar Sesión",
   "login.usernameLabel": "Usuario o Email",
-  "login.passwordLabel": "Contrasena",
+  "login.passwordLabel": "Contraseña",
   "login.loginButton": "Entrar",
-  "login.forgotPasswordLink": "¿Olvidaste tu contrasena?",
+  "login.forgotPasswordLink": "¿Olvidaste tu contraseña?",
+  "forgotPassword.title": "Recuperar Contraseña",
+  "forgotPassword.emailLabel": "Email",
+  "forgotPassword.sendButton": "Enviar Código"
 };
 
-<CrudifyLogin translations={misTraduciones} language="es" />;
+<CrudifyLogin
+  translations={misTraduciones}
+  language="es"
+/>;
 ```
 
-## 🔧 Hooks Disponibles
+## 🛠️ **Utilidades y Funciones de Alto Nivel**
 
-### useUserProfile
+### 🔑 **Acceso Directo a la Instancia**
 
-Hook para obtener y manejar el perfil del usuario autenticado:
+Para casos avanzados donde necesitas acceso directo a la instancia de crudify:
 
 ```tsx
-import { useUserProfile } from "@nocios/crudify-ui";
-
-function UserDashboard() {
-  const { userProfile, loading, error, refreshProfile } = useUserProfile();
-
-  if (loading) return <div>Cargando...</div>;
-  if (error) return <div>Error: {error}</div>;
-
-  return (
-    <div>
-      <h1>Bienvenido, {userProfile?.name}</h1>
-      <p>Email: {userProfile?.email}</p>
-      <button onClick={refreshProfile}>Actualizar Perfil</button>
-    </div>
-  );
+import { getCrudifyInstanceAsync, getCrudifyInstanceSync } from '@nocios/crudify-ui';
+
+// Método asíncrono (recomendado) - espera a que se inicialice
+async function loadData() {
+  try {
+    const crudifyInstance = await getCrudifyInstanceAsync();
+    const response = await crudifyInstance.readItems('products', {});
+    return response;
+  } catch (error) {
+    console.error('Error:', error);
+  }
 }
-```
-
-### useCrudifyLogin
-
-Hook interno para configuracion avanzada:
-
-```tsx
-import { useCrudifyLogin } from "@nocios/crudify-ui";
-
-function CustomLogin() {
-  const { config } = useCrudifyLogin({
-    publicApiKey: "mi-api-key",
-    env: "prod",
-  });
 
-  // config contiene la configuracion final combinada con cookies
-  return <div>App: {config.appName}</div>;
+// Método síncrono - lanza error si no está listo
+function quickOperation() {
+  try {
+    const crudifyInstance = await getCrudifyInstanceSync();
+    // Usar solo si estás seguro de que ya está inicializado
+    return crudifyInstance.readItems('products', {});
+  } catch (error) {
+    console.error('Crudify not ready:', error);
+  }
 }
 ```
 
-## 🛠️ Utilidades Disponibles
-
-### JWT Utils
+### 🔐 **Utilidades de Tokens JWT**
 
 ```tsx
-import { getCurrentUserEmail, decodeJwtSafely, isTokenExpired } from "@nocios/crudify-ui";
+import {
+  getCurrentUserEmail,
+  decodeJwtSafely,
+  isTokenExpired,
+  getTokenPayload
+} from '@nocios/crudify-ui';
 
 // Obtener email del usuario actual
 const userEmail = getCurrentUserEmail();
@@ -165,36 +486,125 @@ const payload = decodeJwtSafely(token);
 
 // Verificar si token ha expirado
 const expired = isTokenExpired(token);
+
+// Obtener payload completo con validación
+const tokenData = getTokenPayload(token);
+console.log('Usuario:', tokenData?.email);
+console.log('Expira:', new Date(tokenData?.exp * 1000));
 ```
 
-### Storage Seguro
+### 🔒 **Storage Seguro**
 
 ```tsx
-import { secureSessionStorage, secureLocalStorage } from "@nocios/crudify-ui";
+import {
+  secureSessionStorage,
+  secureLocalStorage,
+  TokenManager
+} from '@nocios/crudify-ui';
 
-// Guardar token de forma segura
+// Uso básico del storage seguro
 secureSessionStorage.setToken(token);
+const currentToken = secureSessionStorage.getToken();
+secureSessionStorage.clear();
 
-// Obtener token
-const token = secureSessionStorage.getToken();
+// Uso avanzado con TokenManager
+const tokenManager = TokenManager.getInstance();
 
-// Limpiar storage
-secureSessionStorage.clear();
+// Establecer token con sincronización automática
+await tokenManager.setToken(token);
+
+// Obtener token válido (verifica expiración)
+const validToken = tokenManager.getValidToken();
+
+// Limpiar todo
+tokenManager.clearToken();
+
+// Verificar si hay token válido
+const hasValidToken = tokenManager.hasValidToken();
 ```
 
-### Manejo de Errores
+### 🚨 **Manejo de Errores**
 
 ```tsx
-import { handleCrudifyError, ERROR_CODES, getErrorMessage } from "@nocios/crudify-ui";
-
+import {
+  handleCrudifyError,
+  ERROR_CODES,
+  getErrorMessage,
+  CrudifyErrorHandler
+} from '@nocios/crudify-ui';
+
+// Manejo básico de errores
 try {
-  // Tu codigo
+  await readItems('products', {});
 } catch (error) {
   const parsedErrors = handleCrudifyError(error);
   parsedErrors.forEach((err) => {
     console.log(`Error ${err.code}: ${err.message} (Severidad: ${err.severity})`);
+
+    // Diferentes acciones según el código de error
+    switch (err.code) {
+      case ERROR_CODES.INVALID_CREDENTIALS:
+        // Redirigir a login
+        break;
+      case ERROR_CODES.NETWORK_ERROR:
+        // Mostrar mensaje de conectividad
+        break;
+      case ERROR_CODES.TOO_MANY_REQUESTS:
+        // Mostrar mensaje de espera
+        break;
+    }
   });
 }
+
+// Manejo avanzado con categorías
+const errorHandler = new CrudifyErrorHandler();
+errorHandler.setErrorCallback('authentication', (error) => {
+  // Manejar errores de autenticación
+  console.log('Auth error:', error);
+});
+
+errorHandler.setErrorCallback('validation', (error) => {
+  // Manejar errores de validación
+  console.log('Validation error:', error);
+});
+```
+
+### 🔍 **Hooks Legacy (Compatibilidad)**
+
+Para migrar desde versiones anteriores:
+
+```tsx
+// ✅ Hooks nuevos (recomendado)
+import { useCrudifyAuth, useCrudifyData, useCrudifyUser } from '@nocios/crudify-ui';
+
+// ⚠️ Hooks legacy (mantienen compatibilidad)
+import { useUserProfile, useCrudifyLogin } from '@nocios/crudify-ui';
+
+function LegacyComponent() {
+  // Hook legacy para perfil de usuario
+  const { userProfile, loading, error, refreshProfile } = useUserProfile();
+
+  if (loading) return <div>Cargando...</div>;
+  if (error) return <div>Error: {error}</div>;
+
+  return (
+    <div>
+      <h1>Bienvenido, {userProfile?.name}</h1>
+      <p>Email: {userProfile?.email}</p>
+      <button onClick={refreshProfile}>Actualizar Perfil</button>
+    </div>
+  );
+}
+
+function LegacyLoginConfig() {
+  // Hook legacy para configuración
+  const { config } = useCrudifyLogin({
+    publicApiKey: "mi-api-key",
+    env: "prod",
+  });
+
+  return <div>App: {config.appName}</div>;
+}
 ```
 
 ## 📱 Flujos de Autenticacion
@@ -673,5 +1083,162 @@ VITE_TEST_ENV=prod
 
 ---
 
-**Version:** 1.0.0+
+## 🚀 **Mejores Prácticas**
+
+### ✅ **DO - Recomendaciones**
+
+```tsx
+// ✅ Usar el sistema unificado
+<CrudifyDataProvider publicApiKey="..." env="prod">
+  <App />
+</CrudifyDataProvider>
+
+// ✅ Verificar estado antes de operaciones
+const { isReady } = useCrudifyData();
+if (isReady) {
+  await readItems('products', {});
+}
+
+// ✅ Manejar errores apropiadamente
+try {
+  const response = await createItem('products', data);
+  if (response.success) {
+    // Manejar éxito
+  }
+} catch (error) {
+  const errors = handleCrudifyError(error);
+  // Mostrar errores al usuario
+}
+
+// ✅ Usar hooks especializados
+const { isAuthenticated } = useCrudifyAuth();
+const { readItems } = useCrudifyData();
+const { user } = useCrudifyUser();
+```
+
+### ❌ **DON'T - Evitar**
+
+```tsx
+// ❌ No inicializar crudify manualmente
+await crudify.init(); // La librería maneja esto
+
+// ❌ No usar múltiples providers
+<CrudifyProvider>
+  <AnotherProvider>
+    <CrudifyDataProvider> // Conflicto
+      <App />
+    </CrudifyDataProvider>
+  </AnotherProvider>
+</CrudifyProvider>
+
+// ❌ No ignorar el estado isReady
+const { readItems } = useCrudifyData();
+await readItems('products', {}); // Puede fallar si no está listo
+
+// ❌ No manejar tokens manualmente cuando usas el provider
+sessionStorage.setItem('token', token); // El provider lo maneja
+```
+
+### 🔄 **Migración desde Versiones Anteriores**
+
+Si tienes código existente, puedes migrar gradualmente:
+
+```tsx
+// Antes (código legacy)
+import { CrudifyLogin, useUserProfile } from '@nocios/crudify-ui';
+
+function OldApp() {
+  const { userProfile } = useUserProfile();
+  return userProfile ? <Dashboard /> : <CrudifyLogin />;
+}
+
+// Después (sistema unificado)
+import { CrudifyDataProvider, useCrudifyAuth, CrudifyLogin } from '@nocios/crudify-ui';
+
+function NewApp() {
+  return (
+    <CrudifyDataProvider publicApiKey="..." env="prod">
+      <AppContent />
+    </CrudifyDataProvider>
+  );
+}
+
+function AppContent() {
+  const { isAuthenticated, user, setToken } = useCrudifyAuth();
+
+  return isAuthenticated ? (
+    <Dashboard user={user} />
+  ) : (
+    <CrudifyLogin onLoginSuccess={setToken} />
+  );
+}
+```
+
+### 🌍 **Variables de Entorno**
+
+Configura estas variables en tu proyecto:
+
+```bash
+# .env.development
+REACT_APP_CRUDIFY_API_KEY=tu-clave-de-desarrollo
+REACT_APP_CRUDIFY_ENV=dev
+
+# .env.production
+REACT_APP_CRUDIFY_API_KEY=tu-clave-de-produccion
+REACT_APP_CRUDIFY_ENV=prod
+```
+
+```tsx
+// Uso en la aplicación
+<CrudifyDataProvider
+  publicApiKey={process.env.REACT_APP_CRUDIFY_API_KEY}
+  env={process.env.REACT_APP_CRUDIFY_ENV || 'prod'}
+  appName="Mi Aplicación"
+>
+  <App />
+</CrudifyDataProvider>
+```
+
+### 📊 **Debugging y Desarrollo**
+
+```tsx
+// Habilitar logs detallados en desarrollo
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+<CrudifyDataProvider
+  publicApiKey="..."
+  onInitialized={() => isDevelopment && console.log('✅ Crudify inicializado')}
+  onError={(error) => isDevelopment && console.error('❌ Error:', error)}
+  onTokenChange={(token) => isDevelopment && console.log('🔑 Token:', !!token)}
+>
+  <App />
+</CrudifyDataProvider>
+```
+
+---
+
+## 📋 **Changelog y Migración**
+
+### Versión 1.2.x (Actual)
+- ✅ **Nuevo**: Sistema unificado `CrudifyDataProvider`
+- ✅ **Nuevo**: Hooks especializados (`useCrudifyAuth`, `useCrudifyData`, `useCrudifyUser`)
+- ✅ **Nuevo**: Inicialización robusta con singleton thread-safe
+- ✅ **Nuevo**: Gestión automática de tokens con sincronización cross-tab
+- ✅ **Nuevo**: Acceso directo a instancia con `getCrudifyInstanceAsync`
+- 🔄 **Mejorado**: Sistema de manejo de errores
+- 🔄 **Mejorado**: TypeScript con tipos más precisos
+- ⚠️ **Legacy**: Hooks anteriores mantienen compatibilidad
+
+### Migración desde 1.1.x
+1. Envolver la aplicación con `CrudifyDataProvider`
+2. Reemplazar hooks individuales con el sistema unificado
+3. Actualizar manejo de tokens para usar `setToken` del hook
+4. (Opcional) Migrar configuración a props del provider
+
+---
+
+**Version:** 1.2.1
 **Mantenido por:** Equipo Crudify
+**Repositorio:** [GitHub](https://github.com/nocios/crudify-ui)
+**Documentación:** [Docs](https://docs.crudify.com)
+**Soporte:** [Issues](https://github.com/nocios/crudify-ui/issues)