@nocios/crudify-ui 1.3.1 → 1.3.2

package/TECHNICAL_SPECIFICATION.md

@@ -1,344 +0,0 @@
-# ESPECIFICACIÓN TÉCNICA: CrudifyDataProvider
-
-## 🎯 OBJETIVO
-
-Crear un provider unificado que encapsule toda la funcionalidad de autenticación, gestión de tokens y operaciones CRUD, eliminando la duplicación de código entre crudia-ui y crudify-ui, mientras mantiene **100% de compatibilidad** con el sistema de producción.
-
-## 🔍 ANÁLISIS DEL SISTEMA ACTUAL
-
-### CRUDIA-UI (Sistema de Producción que FUNCIONA)
-
-**Arquitectura de Providers:**
-```
-GlobalNotificationProvider
-├── AppProvider (configuración desde ENV/cookies)
-├── DataProvider (inicialización de crudify + JWT)
-    ├── UIProvider
-    ├── DashboardProvider
-    └── Components
-```
-
-**Flujo de Inicialización Crítico:**
-1. `AppProvider` lee configuración de ENV vars + cookies
-2. `DataProvider` inicializa crudify globalmente con `publicApiKey` y `env`
-3. `DataProvider` maneja JWT tokens con `secureSessionStorage`
-4. `DataProvider` configura interceptores para manejo de errores
-5. Componentes usan `crudify` directamente o via `useCrudifyWithNotifications`
-
-**Puntos de Integración Críticos:**
-- `secureSessionStorage` con key `"authToken"`
-- `crudify.config(env)` + `crudify.init(publicApiKey, "none")`
-- `crudify.setToken(token)` sincronizado con storage
-- Interceptores para manejo de tokens expirados
-- Sistema de notificaciones integrado
-
-### CRUDIFY-UI (Sistema que Falla)
-
-**Problemas Identificados:**
-1. **Doble Inicialización**: `DataProvider` + `CrudifyProvider`
-2. **Storage Incompatible**: No usa `secureSessionStorage`
-3. **Falta Provider Global**: Solo `JWTSessionProvider` local
-4. **Error**: "Crudify: Not initialized" por conflictos
-
-## 🏗️ DISEÑO DEL NUEVO SISTEMA
-
-### PRINCIPIOS DE DISEÑO
-
-1. **Compatibilidad Total**: No romper crudia-ui (producción)
-2. **Encapsulación**: Todo en npm-crudify-ui, sin duplicación
-3. **Configuración Flexible**: ENV vars, cookies, o parámetros
-4. **Error Handling Robusto**: Fallas graduales, no cascada
-5. **API Simple**: Hooks fáciles de usar
-
-### ARQUITECTURA PROPUESTA
-
-```
-CrudifyDataProvider (NUEVO)
-├── ConfigurationManager (lee ENV + cookies)
-├── CrudifyInitializer (inicializa crudify UNA SOLA VEZ)
-├── TokenManager (JWT + secureSessionStorage)
-├── ErrorInterceptor (manejo de errores automático)
-├── NotificationSystem (opcional)
-└── Hooks Exportados:
-    ├── useCrudifyAuth (estado de autenticación)
-    ├── useCrudifyUser (datos del usuario + perfil)
-    ├── useCrudifyData (operaciones CRUD)
-    └── useCrudifyConfig (configuración actual)
-```
-
-## 📋 ESPECIFICACIÓN DETALLADA
-
-### 1. CONFIGURACIÓN
-
-**Prioridad de Configuración:**
-```typescript
-interface CrudifyConfig {
-  env?: "dev" | "stg" | "prod"
-  publicApiKey?: string
-  loginActions?: string[]
-  appName?: string
-  logo?: string
-  colors?: Record<string, string>
-}
-
-// Orden de prioridad:
-// 1. Props explícitas al Provider
-// 2. Variables de entorno (VITE_TEST_*)
-// 3. Cookies (para multi-tenant)
-// 4. Error si falta publicApiKey
-```
-
-**Variables de Entorno Soportadas:**
-- `VITE_TEST_ENV`
-- `VITE_TEST_PUBLIC_API_KEY`
-- `VITE_TEST_LOGIN_ACTIONS`
-
-**Cookies Multi-tenant:**
-- `publicApiKey`
-- `environment`
-- `appName`
-- `loginActions`
-- `logo`
-- `colors`
-
-### 2. GESTIÓN DE TOKENS
-
-**Storage Strategy:**
-```typescript
-// COMPATIBILIDAD TOTAL con crudia-ui
-class SecureSessionStorage {
-  private readonly TOKEN_KEY = "authToken"
-
-  setToken(token: string): void
-  getToken(): string | null
-  removeItem(key: string): void
-  migrateFromLocalStorage(key: string): void
-  clear(): void
-}
-```
-
-**JWT Management:**
-```typescript
-interface TokenManager {
-  // Sincronización automática: storage <-> crudify
-  setToken(token: string | null): void
-  getToken(): string | null
-  parseToken(): JWTPayload | null
-  isTokenValid(): boolean
-  getTokenExpiration(): Date | null
-
-  // Auto-cleanup en caso de expiración
-  setupExpirationCheck(): void
-}
-```
-
-### 3. INICIALIZACIÓN DE CRUDIFY
-
-**Inicialización Única y Robusta:**
-```typescript
-class CrudifyInitializer {
-  private static isInitialized = false
-  private static initializationPromise: Promise<void> | null = null
-
-  static async initialize(config: CrudifyConfig): Promise<void> {
-    // Prevenir doble inicialización
-    if (this.isInitialized) return
-    if (this.initializationPromise) return this.initializationPromise
-
-    this.initializationPromise = this.performInitialization(config)
-    await this.initializationPromise
-    this.isInitialized = true
-  }
-
-  private static async performInitialization(config: CrudifyConfig): Promise<void> {
-    await crudify.config(config.env || 'prod')
-    await crudify.init(config.publicApiKey!, 'none')
-
-    // Verificar que los métodos estén disponibles
-    if (typeof crudify.readItems !== 'function') {
-      throw new Error('Crudify not properly initialized')
-    }
-  }
-}
-```
-
-### 4. HOOKS PÚBLICOS
-
-**useCrudifyAuth - Estado de Autenticación:**
-```typescript
-interface UseCrudifyAuthReturn {
-  // Estado básico
-  isAuthenticated: boolean
-  loading: boolean
-  error: string | null
-
-  // Datos del token
-  token: string | null
-  user: JWTPayload | null  // Datos del JWT
-  tokenExpiration: Date | null
-
-  // Acciones
-  setToken: (token: string | null) => void
-  logout: () => void
-  refreshToken?: () => Promise<void>  // Futuro
-}
-```
-
-**useCrudifyUser - Datos del Usuario:**
-```typescript
-interface UseCrudifyUserReturn {
-  // Datos básicos del JWT
-  userEmail: string | null
-  userId: string | null
-  userIdentifier: string | null
-
-  // Perfil completo desde BD
-  userProfile: UserProfile | null
-  profileLoading: boolean
-  profileError: string | null
-
-  // Datos extendidos formateados
-  extendedData: {
-    fullProfile: UserProfile | null
-    totalFields: number
-    displayData: Record<string, any>
-  }
-
-  // Acciones
-  refreshProfile: () => Promise<void>
-  clearProfile: () => void
-}
-```
-
-**useCrudifyData - Operaciones CRUD:**
-```typescript
-interface UseCrudifyDataReturn {
-  // Operaciones básicas
-  readItems: (moduleKey: string, filter?: object, options?: any) => Promise<CrudifyResponse>
-  readItem: (moduleKey: string, filter: object, options?: any) => Promise<CrudifyResponse>
-  createItem: (moduleKey: string, data: object, options?: any) => Promise<CrudifyResponse>
-  updateItem: (moduleKey: string, data: object, options?: any) => Promise<CrudifyResponse>
-  deleteItem: (moduleKey: string, id: string, options?: any) => Promise<CrudifyResponse>
-
-  // Operaciones avanzadas
-  transaction: (operations: any[], options?: any) => Promise<CrudifyResponse>
-  login: (email: string, password: string) => Promise<CrudifyResponse>
-
-  // Estado
-  isInitialized: boolean
-  initializationError: string | null
-}
-```
-
-**useCrudifyConfig - Configuración:**
-```typescript
-interface UseCrudifyConfigReturn {
-  config: CrudifyConfig
-  isConfigured: boolean
-  configError: string | null
-
-  // Para debugging
-  configSource: 'props' | 'env' | 'cookies'
-  rawConfig: Record<string, any>
-}
-```
-
-## 🔄 ESTRATEGIA DE MIGRACIÓN
-
-### FASE 1: Implementación (No Rompe Nada)
-
-1. **Crear CrudifyDataProvider** manteniendo APIs existentes
-2. **Mantener CrudifyProvider** para compatibilidad
-3. **Agregar hooks nuevos** sin afectar los existentes
-4. **Testing exhaustivo** en ambos sistemas
-
-### FASE 2: Migración Gradual
-
-1. **Actualizar crudify-ui** para usar CrudifyDataProvider
-2. **Mantener crudia-ui** sin cambios (producción)
-3. **Documentar migración** opcional para crudia-ui
-
-### FASE 3: Consolidación (Futuro)
-
-1. **Deprecar APIs antiguas** con warnings
-2. **Migrar crudia-ui** opcionalmente
-3. **Limpiar código** redundante
-
-## 🛡️ GARANTÍAS DE COMPATIBILIDAD
-
-### CRUDIA-UI (Producción)
-- ✅ **API actual intacta**: Todos los imports/exports existentes
-- ✅ **DataProvider compatible**: Mismo comportamiento exacto
-- ✅ **Storage compatible**: Misma key `"authToken"`
-- ✅ **Interceptores**: Mismo manejo de errores
-- ✅ **Notificaciones**: Sistema existente sin cambios
-
-### CRUDIFY-UI (Desarrollo)
-- ✅ **Migración simple**: Un solo Provider reemplaza todo
-- ✅ **Hooks simples**: APIs más fáciles de usar
-- ✅ **Configuración flexible**: ENV + cookies + props
-- ✅ **Error handling**: Más robusto que el actual
-
-## 🧪 PLAN DE TESTING
-
-### Tests de Compatibilidad
-1. **crudia-ui**: Login, operaciones CRUD, manejo de errores
-2. **npm-crudify-ui**: APIs existentes sin cambios
-3. **crudify-ui**: Nueva implementación funcional
-
-### Tests de Integración
-1. **Doble inicialización**: Sin conflictos
-2. **Storage**: Compatibilidad entre sistemas
-3. **Tokens**: Manejo correcto de JWT
-4. **Errores**: Graceful degradation
-
-### Tests de Regresión
-1. **Multi-tenant**: Cookies funcionando
-2. **ENV vars**: Configuración correcta
-3. **Login flow**: End-to-end completo
-4. **User profile**: Datos cargados correctamente
-
-## 📚 DOCUMENTACIÓN
-
-### Para Desarrolladores
-1. **Guía de migración** desde sistema actual
-2. **API reference** completa
-3. **Ejemplos de uso** para cada hook
-4. **Troubleshooting** común
-
-### Para Producción
-1. **No-breaking changes** garantizados
-2. **Rollback plan** si es necesario
-3. **Monitoring** de errores
-4. **Performance** sin degradación
-
-## 🚀 CRONOGRAMA
-
-### Semana 1: Implementación Core
-- [ ] ConfigurationManager
-- [ ] CrudifyInitializer
-- [ ] TokenManager
-- [ ] Tests unitarios
-
-### Semana 2: Hooks y Provider
-- [ ] CrudifyDataProvider
-- [ ] useCrudifyAuth
-- [ ] useCrudifyUser
-- [ ] useCrudifyData
-
-### Semana 3: Integración y Testing
-- [ ] Migración crudify-ui
-- [ ] Tests de compatibilidad crudia-ui
-- [ ] Tests end-to-end
-- [ ] Documentación
-
-### Semana 4: Validación y Deploy
-- [ ] Testing exhaustivo
-- [ ] Code review
-- [ ] Deploy y monitoring
-- [ ] Documentación final
-
----
-
-**RIESGO: MÍNIMO** - El diseño mantiene 100% compatibilidad hacia atrás
-**BENEFICIO: MÁXIMO** - Elimina duplicación y simplifica enormemente el desarrollo futuro

package/example-app.tsx

@@ -1,197 +0,0 @@
-// =============================
-// EXAMPLE APP - REFRESH TOKEN PATTERN
-// =============================
-
-/**
- * Ejemplo completo de aplicación usando el Refresh Token Pattern
- * Demuestra todas las características nuevas de crudify-ui v1.2+
- */
-
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { ThemeProvider, createTheme } from '@mui/material/styles';
-import { CssBaseline, Container, AppBar, Toolbar, Typography, Box } from '@mui/material';
-import {
-  SessionProvider,
-  LoginComponent,
-  SessionStatus,
-  SessionDebugInfo,
-  useSessionContext,
-  ProtectedRoute
-} from '@nocios/crudify-ui';
-
-const theme = createTheme();
-
-// Componente de aplicación principal
-function App() {
-  return (
-    <ThemeProvider theme={theme}>
-      <CssBaseline />
-
-      {/* Envolver toda la app con SessionProvider */}
-      <SessionProvider
-        options={{
-          autoRestore: true,          // Restaurar sesión automáticamente
-          enableLogging: true,        // Logs para debug
-          onSessionExpired: () => {   // Callback cuando expira la sesión
-            console.log('Session expired - redirecting to login');
-            // Aquí podrías hacer redirect, mostrar modal, etc.
-          },
-          onSessionRestored: (tokens) => {
-            console.log('Session restored successfully:', tokens);
-          }
-        }}
-      >
-        <AppContent />
-      </SessionProvider>
-    </ThemeProvider>
-  );
-}
-
-// Contenido principal de la aplicación
-function AppContent() {
-  return (
-    <>
-      {/* App Bar */}
-      <AppBar position="static">
-        <Toolbar>
-          <Typography variant="h6" component="div" sx={{ flexGrow: 1 }}>
-            Crudify Refresh Token Demo
-          </Typography>
-          <SessionStatus />
-        </Toolbar>
-      </AppBar>
-
-      {/* Contenido principal */}
-      <Container maxWidth="lg" sx={{ mt: 4, mb: 4 }}>
-        <LoginComponent />
-
-        {/* Área protegida - solo visible si está autenticado */}
-        <ProtectedRoute fallback={null}>
-          <ProtectedArea />
-        </ProtectedRoute>
-
-        {/* Debug info (solo en desarrollo) */}
-        {process.env.NODE_ENV === 'development' && (
-          <SessionDebugInfo />
-        )}
-      </Container>
-    </>
-  );
-}
-
-// Área protegida de la aplicación
-function ProtectedArea() {
-  const { refreshTokens, isExpiringSoon } = useSessionContext();
-
-  return (
-    <Box sx={{ mt: 4, p: 3, bgcolor: 'background.paper', borderRadius: 1 }}>
-      <Typography variant="h5" gutterBottom>
-        Protected Area 🔒
-      </Typography>
-
-      <Typography variant="body1" paragraph>
-        This content is only visible to authenticated users. The session is managed
-        automatically with the Refresh Token Pattern.
-      </Typography>
-
-      {isExpiringSoon && (
-        <Box sx={{ mb: 2, p: 2, bgcolor: 'warning.light', borderRadius: 1 }}>
-          <Typography variant="body2">
-            ⚠️ Your token is expiring soon, but don't worry - it will be refreshed automatically!
-          </Typography>
-        </Box>
-      )}
-
-      {/* Ejemplo de uso de CRUD operations */}
-      <CrudOperationsExample />
-    </Box>
-  );
-}
-
-// Ejemplo de operaciones CRUD con auto-refresh
-function CrudOperationsExample() {
-  const [data, setData] = React.useState(null);
-  const [loading, setLoading] = React.useState(false);
-  const [error, setError] = React.useState(null);
-
-  // Importar crudify
-  const crudify = React.useMemo(() => {
-    // En una app real, ya estaría inicializado
-    import('@nocios/crudify-browser').then(module => module.default);
-  }, []);
-
-  const fetchData = async () => {
-    setLoading(true);
-    setError(null);
-
-    try {
-      // Esta operación usará automáticamente el auto-refresh si es necesario
-      const result = await crudify.getPermissions();
-
-      if (result.success) {
-        setData(result.data);
-      } else {
-        setError('Failed to fetch data: ' + JSON.stringify(result.errors));
-      }
-    } catch (err) {
-      setError('Network error: ' + err.message);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <Box sx={{ mt: 3 }}>
-      <Typography variant="h6" gutterBottom>
-        CRUD Operations with Auto-Refresh
-      </Typography>
-
-      <button onClick={fetchData} disabled={loading}>
-        {loading ? 'Loading...' : 'Fetch Permissions (Test Auto-Refresh)'}
-      </button>
-
-      {error && (
-        <Box sx={{ mt: 2, p: 2, bgcolor: 'error.light', borderRadius: 1 }}>
-          <Typography variant="body2" color="error">
-            {error}
-          </Typography>
-        </Box>
-      )}
-
-      {data && (
-        <Box sx={{ mt: 2, p: 2, bgcolor: 'success.light', borderRadius: 1 }}>
-          <Typography variant="body2">
-            ✅ Data fetched successfully! Auto-refresh is working.
-          </Typography>
-          <pre style={{ fontSize: '12px', marginTop: '8px' }}>
-            {JSON.stringify(data, null, 2)}
-          </pre>
-        </Box>
-      )}
-    </Box>
-  );
-}
-
-// =============================
-// BOOTSTRAP DE LA APLICACIÓN
-// =============================
-
-// Para usar este ejemplo:
-// 1. npm install @nocios/crudify-ui@^1.2.0
-// 2. Configurar crudify con tu API key antes de renderizar
-// 3. Renderizar la aplicación
-
-export default App;
-
-// Ejemplo de inicialización
-/*
-import { crudify } from '@nocios/crudify-ui';
-
-// Configurar crudify antes de renderizar la app
-await crudify.init('your-api-key', 'debug');
-
-// Renderizar la aplicación
-const root = ReactDOM.createRoot(document.getElementById('root')!);
-root.render(<App />);
-*/