@mp-front/common 0.0.1 → 0.0.2-next.0

package/README.md

@@ -1 +1,1006 @@
-# front-utils
+# @mp-front/common - Documentación Técnica
+
+## 📚 Tabla de Contenidos
+
+1. [Arquitectura General](#arquitectura-general)
+2. [Módulos y Componentes](#módulos-y-componentes)
+3. [Guías de Implementación](#guías-de-implementación)
+4. [Configuración](#configuración)
+5. [Casos de Uso Avanzados](#casos-de-uso-avanzados)
+
+---
+
+## 🏗️ Arquitectura General
+
+La biblioteca `@mp-front/common` está diseñada con una arquitectura modular que permite importar solo los componentes necesarios, optimizando el tamaño del bundle final.
+
+### Estructura de Directorios
+
+```
+src/
+├── adapters/          # Adaptadores NextAuth (Redis)
+├── auth/              # Servicios de autenticación
+├── cache/             # Gestión de caché
+│   ├── session-handler/    # Manejo de sesiones
+│   └── terminal-handler/   # Manejo de terminales
+├── cache-providers/   # Proveedores de caché
+│   └── redis/             # Implementación Redis
+├── engine/            # Motor de autenticación Azure
+├── errors/            # Sistema de errores
+├── helpers/           # Utilidades generales
+├── http/              # Cliente HTTP
+├── middleware/        # Middlewares API
+└── rxjs/              # Utilidades RxJS
+```
+
+### Principios de Diseño
+
+- **Modularidad**: Cada módulo es independiente y puede importarse por separado
+- **Programación Reactiva**: Uso extensivo de RxJS para operaciones asíncronas
+- **Type Safety**: TypeScript completo con tipos estrictos
+- **Singleton Pattern**: Para gestores globales (ErrorHandler, LoadingHandler)
+- **Encriptación**: Seguridad en datos sensibles con node-jose
+
+---
+
+## 📦 Módulos y Componentes
+
+### 1. Auth Module (`@mp-front/common/auth`)
+
+#### AuthorizationService
+
+Servicio para obtener tokens de autenticación desde un backend.
+
+**Características:**
+
+- Autenticación mediante credenciales
+- Retorna Observable con el token
+- Logging integrado de requests/responses
+
+**Implementación:**
+
+```typescript
+import { AuthorizationService } from "@mp-front/common/auth"
+
+const authService = new AuthorizationService()
+
+// Obtener token
+authService.get().subscribe({
+  next: token => {
+    console.log("Token obtenido:", token)
+    // Usar token en headers
+  },
+  error: error => {
+    console.error("Error de autenticación:", error)
+  },
+})
+```
+
+**Variables de entorno requeridas:**
+
+```env
+API_AUTH_BACK_URL=https://api.example.com/auth
+API_AUTH_BACK_USERNAME_AUTH=your_username
+API_AUTH_BACK_PASSWORD_AUTH=your_password
+ID_FRONT=frontend-app-id
+```
+
+---
+
+### 2. Engine Module (`@mp-front/common/engine`)
+
+#### AuthEngine
+
+Motor de autenticación para Azure Entra ID (anteriormente Azure AD).
+
+**Características:**
+
+- Verificación de roles de usuario
+- Verificación de grupos de usuario
+- Integración con Microsoft Graph API
+
+**Métodos principales:**
+
+##### `getRoles(email: string, idObjApp: string)`
+
+Obtiene los roles asignados a un usuario en una aplicación.
+
+```typescript
+import { AuthEngine } from "@mp-front/common/engine"
+
+const authEngine = new AuthEngine()
+
+authEngine.getRoles("user@example.com", "app-object-id").subscribe({
+  next: ({ roles }) => {
+    console.log("Roles del usuario:", roles)
+  },
+})
+```
+
+##### `inRole(email: string, idRole: string, idObjApp: string)`
+
+Verifica si un usuario tiene un rol específico.
+
+```typescript
+authEngine.inRole("user@example.com", "role-id", "app-object-id").subscribe({
+  next: hasRole => {
+    if (hasRole) {
+      console.log("Usuario tiene el rol")
+    }
+  },
+})
+```
+
+##### `inGroup(email: string, idGroup: string)`
+
+Verifica si un usuario pertenece a un grupo.
+
+```typescript
+authEngine.inGroup("user@example.com", "group-id").subscribe({
+  next: inGroup => {
+    if (inGroup) {
+      console.log("Usuario pertenece al grupo")
+    }
+  },
+})
+```
+
+**Variables de entorno requeridas:**
+
+```env
+AZURE_AD_GRAPH_GET_APP_ROLES=https://graph.microsoft.com/v1.0/applications/{id-obj}/appRoles
+AZURE_AD_GRAPH_GET_USER_BY_EMAIL=https://graph.microsoft.com/v1.0/users/{user-mail}
+AZURE_AD_GRAPH_GROUPS=https://graph.microsoft.com/v1.0/users/idUser/memberOf
+```
+
+---
+
+### 3. HTTP Module (`@mp-front/common/http`)
+
+#### HttpClient
+
+Cliente HTTP basado en RxJS con características avanzadas.
+
+**Características:**
+
+- Métodos HTTP: GET, POST, PUT, PATCH, DELETE
+- Encoding/Decoding automático de datos
+- Manejo de loading state global
+- Manejo de errores centralizado
+- Logging de requests/responses
+
+**Métodos:**
+
+##### GET Request
+
+```typescript
+import { HttpClient } from "@mp-front/common/http"
+
+const client = new HttpClient()
+
+interface User {
+  id: number
+  name: string
+  email: string
+}
+
+client.get<User>("/api/users/1").subscribe({
+  next: user => {
+    console.log("Usuario:", user)
+  },
+  error: error => {
+    console.error("Error:", error)
+  },
+})
+
+// Con parámetros
+client
+  .get<User[]>("/api/users", {
+    params: { page: 1, limit: 10 },
+  })
+  .subscribe(users => {
+    console.log("Usuarios:", users)
+  })
+```
+
+##### POST Request
+
+```typescript
+client
+  .post<User>("/api/users", {
+    name: "John Doe",
+    email: "john@example.com",
+  })
+  .subscribe(newUser => {
+    console.log("Usuario creado:", newUser)
+  })
+```
+
+##### PUT Request
+
+```typescript
+client
+  .put<User>("/api/users/1", {
+    name: "Jane Doe",
+  })
+  .subscribe(updatedUser => {
+    console.log("Usuario actualizado:", updatedUser)
+  })
+```
+
+##### DELETE Request
+
+```typescript
+client.delete("/api/users/1").subscribe(() => {
+  console.log("Usuario eliminado")
+})
+```
+
+##### Deshabilitar Loading Global
+
+```typescript
+const client = new HttpClient()
+client.setIsLoadingEnabled(false)
+
+// Este request no activará el loading global
+client.get("/api/data").subscribe(data => {
+  console.log(data)
+})
+```
+
+---
+
+### 4. Cache Module (`@mp-front/common/cache`)
+
+#### SessionCache
+
+Gestión de sesiones de usuario con Redis.
+
+**Características:**
+
+- Almacenamiento de sesión en Redis
+- Renovación automática de timeout
+- Integración con NextAuth
+- Datos de usuario y tienda
+
+**Métodos:**
+
+##### `getBasicSession()`
+
+Obtiene la sesión básica del usuario.
+
+```typescript
+import { SessionCache } from "@mp-front/common/cache"
+
+const sessionCache = new SessionCache("user-id-123")
+
+const session = await sessionCache.getBasicSession()
+
+console.log("Usuario:", session.user)
+// {
+//   name: 'John Doe',
+//   email: 'john@example.com',
+//   image: 'https://...',
+//   cveUsuario: '12345',
+//   rol: 'admin',
+//   appGroups: ['group1', 'group2']
+// }
+```
+
+##### `getUserAndShoppingStore()`
+
+Obtiene sesión completa con datos de tienda.
+
+```typescript
+const fullSession = await sessionCache.getUserAndShoppingStore()
+
+console.log("Sesión completa:", fullSession)
+```
+
+#### TerminalCache
+
+Gestión de datos de terminal con Redis.
+
+**Características:**
+
+- Almacenamiento por clave de vendedor
+- Generación de UUID único por vendedor
+- Timeout configurable
+
+**Métodos:**
+
+##### `set(sellerKey: string, terminal: TerminalValue)`
+
+Guarda datos de terminal.
+
+```typescript
+import { TerminalCache } from "@mp-front/common/cache"
+
+const terminalCache = new TerminalCache()
+
+await terminalCache.set("SELLER001", {
+  terminalId: "TERM123",
+  location: "Store A",
+  status: "active",
+})
+```
+
+##### `get(sellerKey: string)`
+
+Obtiene datos de terminal.
+
+```typescript
+const terminal = await terminalCache.get("SELLER001")
+
+if (terminal) {
+  console.log("Terminal:", terminal)
+}
+```
+
+##### `delete(sellerKey: string)`
+
+Elimina datos de terminal.
+
+```typescript
+await terminalCache.delete("SELLER001")
+```
+
+---
+
+### 5. Cache Providers Module (`@mp-front/common/cache-providers`)
+
+#### RedisCache
+
+Proveedor genérico de caché con Redis.
+
+**Características:**
+
+- Operaciones CRUD completas
+- Encriptación opcional
+- TTL (Time To Live) configurable
+- Soporte para tipos genéricos
+
+**Métodos:**
+
+##### `set(params: ISetStateParams<T>)`
+
+Guarda datos en Redis.
+
+```typescript
+import { RedisCache } from "@mp-front/common/cache-providers"
+
+interface UserData {
+  name: string
+  email: string
+}
+
+const redis = new RedisCache<UserData>()
+
+await redis.set({
+  prefix: "user:123",
+  idData: "profile",
+  body: {
+    name: "John Doe",
+    email: "john@example.com",
+  },
+  expire: 3600, // 1 hora en segundos
+  encrypted: true, // Opcional: encriptar datos
+})
+```
+
+##### `get<T>(prefix: string, idData: string)`
+
+Obtiene datos de Redis.
+
+```typescript
+const { data, sha } = await redis.get<UserData>("user:123", "profile")
+
+console.log("Datos:", data)
+console.log("SHA key:", sha)
+```
+
+##### `delete(prefix: string, idData: string)`
+
+Elimina datos de Redis.
+
+```typescript
+await redis.delete("user:123", "profile")
+```
+
+##### Operaciones simples
+
+```typescript
+// GET simple
+const value = await redis.simpleGet("key")
+
+// HGET (hash get)
+const fieldValue = await redis.simpleHGet("hash-key", "field")
+
+// HSET (hash set)
+await redis.simpleHSet("hash-key", "field", "value")
+
+// HGETALL (obtener todo el hash)
+const allFields = await redis.simpleHGetAll("hash-key")
+```
+
+**Variables de entorno:**
+
+```env
+REDIS_URL=redis://localhost:6379
+TIMEOUT_SESSION_MINUTES=60
+SECRET_SIGNATURE=your-secret-key-for-encryption
+```
+
+---
+
+### 6. Helpers Module (`@mp-front/common/helpers`)
+
+#### Logger
+
+Sistema de logging con niveles y colores.
+
+**Niveles de log:**
+
+- `error`: Errores críticos
+- `warn`: Advertencias
+- `info`: Información general
+- `http`: Logs HTTP
+- `verbose`: Información detallada
+- `debug`: Debugging
+- `silly`: Todo
+
+**Uso:**
+
+```typescript
+import { Logger } from "@mp-front/common/helpers"
+
+const logger = new Logger()
+
+logger.logError("Error crítico", JSON.stringify(error))
+logger.logWarn("Advertencia: API deprecated")
+logger.logInfo("Usuario autenticado correctamente")
+logger.logDebug("Datos de request:", JSON.stringify(data))
+```
+
+**Configuración:**
+
+```env
+NEXT_PUBLIC_APP_LOGS_NAME=MyApp
+NEXT_PUBLIC_LOGS_LEVEL=debug
+NEXT_PUBLIC_SILENT_LOGS=false
+```
+
+#### Encoder
+
+Codificación/decodificación de datos en Base64.
+
+```typescript
+import { Encoder } from "@mp-front/common/helpers"
+
+const encoder = new Encoder()
+
+// Codificar
+const encoded = encoder.encode({ name: "John" }, "request-id-123")
+// Resultado: { info: "base64...", requestID: "request-id-123" }
+
+// Decodificar
+const decoded = encoder.decode(encoded)
+// Resultado: { name: 'John' }
+```
+
+#### Encrypter
+
+Encriptación/desencriptación con node-jose (JWE).
+
+```typescript
+import { Encrypter } from "@mp-front/common/helpers"
+
+const encrypter = new Encrypter()
+
+// Encriptar
+const encrypted = await encrypter.encrypt({
+  password: "secret123",
+  apiKey: "key-xyz",
+})
+
+// Desencriptar
+const decrypted = await encrypter.decrypt(encrypted)
+
+// Verificar si está encriptado
+const isEncrypted = await encrypter.isEncrypted(someString)
+
+// Generar SHA256
+const sha = encrypter.generateSHA({ userId: "123" })
+```
+
+---
+
+### 7. Errors Module (`@mp-front/common/errors`)
+
+#### ErrorHandler
+
+Gestor global de errores con patrón Singleton.
+
+```typescript
+import { ErrorHandler } from "@mp-front/common/errors"
+
+// Suscribirse a errores globales
+ErrorHandler.getInstance()
+  .getSubject()
+  .subscribe(error => {
+    console.error("Error global:", error)
+
+    // Mostrar notificación
+    showNotification({
+      type: "error",
+      message: error.message,
+      code: error.code,
+    })
+  })
+```
+
+#### RuntimeError
+
+Clase de error personalizada.
+
+```typescript
+import { RuntimeError, RuntimeErrorCode } from "@mp-front/common/errors"
+
+// Lanzar error
+throw new RuntimeError(RuntimeErrorCode.VALIDATION_ERROR, "request-id-123")
+
+// En un catch
+try {
+  // código
+} catch (error) {
+  throw new RuntimeError("CUSTOM_ERROR", requestId)
+}
+```
+
+---
+
+### 8. RxJS Module (`@mp-front/common/rxjs`)
+
+#### LoadingHandler
+
+Gestor global de estado de carga.
+
+```typescript
+import { LoadingHandler } from "@mp-front/common/rxjs"
+
+// Suscribirse al estado de loading
+LoadingHandler.getInstance()
+  .getSubject()
+  .subscribe(isLoading => {
+    if (isLoading) {
+      showSpinner()
+    } else {
+      hideSpinner()
+    }
+  })
+
+// Activar loading manualmente
+LoadingHandler.getInstance().setSubject(true)
+
+// Desactivar loading
+LoadingHandler.getInstance().setSubject(false)
+```
+
+**Integración con React:**
+
+```typescript
+import { useEffect, useState } from 'react'
+import { LoadingHandler } from '@mp-front/common/rxjs'
+
+function App() {
+  const [isLoading, setIsLoading] = useState(false)
+
+  useEffect(() => {
+    const subscription = LoadingHandler.getInstance()
+      .getSubject()
+      .subscribe(setIsLoading)
+
+    return () => subscription.unsubscribe()
+  }, [])
+
+  return (
+    <>
+      {isLoading && <Spinner />}
+      {/* resto de la app */}
+    </>
+  )
+}
+```
+
+---
+
+### 9. Middleware Module (`@mp-front/common/middleware`)
+
+#### ApiMiddleware
+
+Middleware para APIs de Next.js con manejo de sesión.
+
+**Características:**
+
+- Encoding/Decoding automático
+- Manejo de errores
+- Logging de requests
+- Soporte para archivos
+
+**Uso básico:**
+
+```typescript
+import { ApiMiddleware } from "@mp-front/common/middleware"
+
+class MyApiMiddleware extends ApiMiddleware {
+  constructor() {
+    super()
+  }
+}
+
+const middleware = new MyApiMiddleware()
+
+// Configurar sesión
+middleware.setSession(session)
+
+// Handler para GET/POST
+export const POST = middleware.get<RequestType, ResponseType>(
+  (params, { requestID, headers }) => {
+    // Lógica de negocio
+    return of({
+      success: true,
+      data: processedData,
+    })
+  }
+)
+```
+
+**Handler para archivos:**
+
+```typescript
+export const POST = middleware.getFile<ResponseType>(file => {
+  // Procesar archivo
+  return of({
+    filename: file.name,
+    size: file.size,
+  })
+})
+```
+
+---
+
+### 10. Adapters Module (`@mp-front/common/adapters`)
+
+#### IORedisAdapter
+
+Adaptador de Redis para NextAuth.
+
+```typescript
+import { IORedisAdapter } from "@mp-front/common/adapters"
+
+export const authOptions = {
+  adapter: IORedisAdapter({
+    expire: 3600, // segundos
+  }),
+  // ... otras opciones
+}
+```
+
+---
+
+## ⚙️ Configuración Completa
+
+### Variables de Entorno
+
+```env
+# Logging
+NEXT_PUBLIC_APP_LOGS_NAME=MyApp
+NEXT_PUBLIC_LOGS_LEVEL=debug
+NEXT_PUBLIC_SILENT_LOGS=false
+
+# Authentication Backend
+API_AUTH_BACK_URL=https://api.example.com/auth
+API_AUTH_BACK_USERNAME_AUTH=username
+API_AUTH_BACK_PASSWORD_AUTH=password
+ID_FRONT=frontend-app-id
+
+# Azure Entra ID
+AZURE_AD_GRAPH_GET_APP_ROLES=https://graph.microsoft.com/v1.0/applications/{id-obj}/appRoles
+AZURE_AD_GRAPH_GET_USER_BY_EMAIL=https://graph.microsoft.com/v1.0/users/{user-mail}
+AZURE_AD_GRAPH_GROUPS=https://graph.microsoft.com/v1.0/users/idUser/memberOf
+
+# Redis
+REDIS_URL=redis://localhost:6379
+TIMEOUT_SESSION_MINUTES=60
+PREFIX_LOGIN=app
+
+# Encryption
+SECRET_SIGNATURE=your-secret-key-min-32-chars
+```
+
+---
+
+## 🚀 Casos de Uso Avanzados
+
+### 1. Sistema de Autenticación Completo
+
+```typescript
+import { AuthorizationService } from "@mp-front/common/auth"
+import { HttpClient } from "@mp-front/common/http"
+import { SessionCache } from "@mp-front/common/cache"
+
+class AuthSystem {
+  private authService = new AuthorizationService()
+  private httpClient = new HttpClient()
+  private sessionCache: SessionCache
+
+  async login(userId: string) {
+    // Obtener token
+    const token = await firstValueFrom(this.authService.get())
+
+    // Configurar sesión
+    this.sessionCache = new SessionCache(userId)
+    const session = await this.sessionCache.getBasicSession()
+
+    // Hacer request autenticado
+    this.httpClient
+      .get("/api/protected", {
+        headers: {
+          Authorization: `Bearer ${token}`,
+        },
+      })
+      .subscribe(data => {
+        console.log("Datos protegidos:", data)
+      })
+  }
+}
+```
+
+### 2. Sistema de Caché Multinivel
+
+```typescript
+import { RedisCache } from "@mp-front/common/cache-providers"
+import { Encrypter } from "@mp-front/common/helpers"
+
+class CacheSystem<T> {
+  private redis = new RedisCache<T>()
+  private encrypter = new Encrypter()
+  private memoryCache = new Map<string, T>()
+
+  async get(key: string): Promise<T | null> {
+    // Nivel 1: Memoria
+    if (this.memoryCache.has(key)) {
+      return this.memoryCache.get(key)!
+    }
+
+    // Nivel 2: Redis
+    try {
+      const { data } = await this.redis.get<T>(key, "data")
+      this.memoryCache.set(key, data)
+      return data
+    } catch {
+      return null
+    }
+  }
+
+  async set(key: string, value: T, ttl: number = 3600) {
+    // Guardar en memoria
+    this.memoryCache.set(key, value)
+
+    // Guardar en Redis
+    await this.redis.set({
+      prefix: key,
+      idData: "data",
+      body: value,
+      expire: ttl,
+      encrypted: true,
+    })
+  }
+}
+```
+
+### 3. Sistema de Manejo de Errores Global
+
+```typescript
+import { ErrorHandler, RuntimeError } from "@mp-front/common/errors"
+import { LoadingHandler } from "@mp-front/common/rxjs"
+
+class GlobalErrorSystem {
+  constructor() {
+    this.setupErrorHandling()
+    this.setupLoadingHandling()
+  }
+
+  private setupErrorHandling() {
+    ErrorHandler.getInstance()
+      .getSubject()
+      .subscribe(error => {
+        // Ocultar loading
+        LoadingHandler.getInstance().setSubject(false)
+
+        // Log error
+        console.error("Error:", error)
+
+        // Mostrar notificación
+        this.showErrorNotification(error)
+
+        // Enviar a servicio de tracking
+        this.trackError(error)
+      })
+  }
+
+  private setupLoadingHandling() {
+    LoadingHandler.getInstance()
+      .getSubject()
+      .subscribe(isLoading => {
+        document.body.classList.toggle("loading", isLoading)
+      })
+  }
+
+  private showErrorNotification(error: RuntimeError) {
+    // Implementación de notificación
+  }
+
+  private trackError(error: RuntimeError) {
+    // Enviar a Sentry, DataDog, etc.
+  }
+}
+```
+
+### 4. API Middleware con Validación
+
+```typescript
+import { ApiMiddleware } from "@mp-front/common/middleware"
+import { RuntimeError } from "@mp-front/common/errors"
+import { of, throwError } from "rxjs"
+
+interface CreateUserRequest {
+  name: string
+  email: string
+}
+
+interface CreateUserResponse {
+  id: string
+  name: string
+  email: string
+}
+
+class UserApiMiddleware extends ApiMiddleware {
+  createUser = this.get<CreateUserRequest, CreateUserResponse>(
+    (params, { requestID }) => {
+      // Validación
+      if (!params.name || !params.email) {
+        throw new RuntimeError("VALIDATION_ERROR", requestID)
+      }
+
+      // Obtener sesión
+      const session = this.getSession()
+
+      // Lógica de negocio
+      const newUser = {
+        id: generateId(),
+        name: params.name,
+        email: params.email,
+      }
+
+      return of(newUser)
+    }
+  )
+}
+
+export const POST = new UserApiMiddleware().createUser
+```
+
+---
+
+## 📝 Mejores Prácticas
+
+### 1. Manejo de Suscripciones RxJS
+
+```typescript
+import { Component, OnDestroy } from "@angular/core"
+import { Subject, takeUntil } from "rxjs"
+
+class MyComponent implements OnDestroy {
+  private destroy$ = new Subject<void>()
+
+  ngOnInit() {
+    this.httpClient
+      .get("/api/data")
+      .pipe(takeUntil(this.destroy$))
+      .subscribe(data => {
+        // Procesar datos
+      })
+  }
+
+  ngOnDestroy() {
+    this.destroy$.next()
+    this.destroy$.complete()
+  }
+}
+```
+
+### 2. Tipado Estricto
+
+```typescript
+// Definir interfaces
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+// Usar tipos genéricos
+const redis = new RedisCache<User>()
+const client = new HttpClient()
+
+client.get<User>("/api/user/1").subscribe(user => {
+  // TypeScript sabe que user es de tipo User
+  console.log(user.name)
+})
+```
+
+### 3. Manejo de Errores
+
+```typescript
+import { catchError, of } from "rxjs"
+
+client
+  .get<Data>("/api/data")
+  .pipe(
+    catchError(error => {
+      console.error("Error:", error)
+      return of(null) // Valor por defecto
+    })
+  )
+  .subscribe(data => {
+    if (data) {
+      // Procesar datos
+    }
+  })
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Problema: Redis no conecta
+
+**Solución:**
+
+```typescript
+import { RedisCache } from "@mp-front/common/cache-providers"
+
+const redis = new RedisCache()
+
+redis
+  .statusHost()
+  .then(() => {
+    console.log("Redis conectado")
+  })
+  .catch(error => {
+    console.error("Error de conexión:", error)
+  })
+```
+
+### Problema: Logs no aparecen
+
+**Verificar:**
+
+1. `NEXT_PUBLIC_SILENT_LOGS=false`
+2. `NEXT_PUBLIC_LOGS_LEVEL` está configurado correctamente
+3. El nivel del log es mayor o igual al configurado
+
+### Problema: Encriptación falla
+
+**Verificar:**
+
+1. `SECRET_SIGNATURE` está definido en `.env`
+2. La clave tiene al menos 32 caracteres
+3. La clave es la misma para encriptar y desencriptar
+
+---
+
+## 📄 Licencia
+
+Privada - Uso interno únicamente