@tgtone/auth-sdk 1.3.0 → 1.3.1

package/docs/MIGRATION_GUIDE.md

@@ -0,0 +1,315 @@
+# Guía de Migración a v1.3.0 - Session Revocation
+
+Esta guía explica cómo migrar tus aplicaciones existentes para usar las nuevas funcionalidades de detección de sesión revocada.
+
+---
+
+## 📋 Resumen de Cambios
+
+| Feature | Descripción |
+|---------|-------------|
+| `onSessionRevoked` | Callback ejecutado cuando usuario/tenant es eliminado |
+| `heartbeatIntervalMs` | Intervalo de validación periódica de sesión |
+| `startHeartbeat()` / `stopHeartbeat()` | Control manual del heartbeat |
+| `getBlockedRedirectUrl()` | Genera URL de redirección para sesión revocada |
+| `createAxiosInterceptor()` | Interceptor para Axios que maneja 401 |
+| `createAuthFetch()` | Wrapper de fetch con manejo de sesión |
+
+---
+
+## 🔄 Migración por Tipo de App
+
+### 1. Apps React con Context (Console, Baco, Zenith)
+
+**Antes (v1.2.x):**
+```tsx
+// src/lib/auth-client.ts
+import { TGTAuthClient } from '@tgtone/auth-sdk';
+
+export const authClient = new TGTAuthClient({
+  identityUrl: 'https://identity.tgtone.cl',
+  appDomain: window.location.host,
+  debug: import.meta.env.DEV,
+  onAuthFailure: (error) => {
+    if (error?.code) {
+      window.location.href = `${identityUrl}/login?error=${error.code.toLowerCase()}`;
+    }
+  },
+});
+```
+
+**Después (v1.3.0):**
+```tsx
+// src/lib/auth-client.ts
+import { TGTAuthClient, AuthError, isRevocationError } from '@tgtone/auth-sdk';
+
+const identityUrl = import.meta.env.VITE_IDENTITY_URL || 'https://identity.tgtone.cl';
+
+export const authClient = new TGTAuthClient({
+  identityUrl,
+  appDomain: window.location.host,
+  debug: import.meta.env.DEV,
+  
+  // 🆕 Validar sesión cada 5 minutos
+  heartbeatIntervalMs: 5 * 60 * 1000,
+  
+  onAuthFailure: (error) => {
+    if (error?.code) {
+      window.location.href = `${identityUrl}/login?error=${error.code.toLowerCase()}`;
+    }
+  },
+  
+  // 🆕 Manejar sesión revocada
+  onSessionRevoked: (error: AuthError) => {
+    console.log('[Auth] Sesión revocada:', error.code, error.message);
+    const blockedUrl = authClient.getBlockedRedirectUrl(error);
+    window.location.href = blockedUrl;
+  },
+});
+```
+
+### 2. Apps con Hook useTGTAuth
+
+**Antes (v1.2.x):**
+```tsx
+import { useTGTAuth } from '@tgtone/auth-sdk';
+
+function App() {
+  const { session, loading, logout } = useTGTAuth({
+    identityUrl: 'https://identity.tgtone.cl',
+    appDomain: 'zenith.tgtone.cl',
+  });
+  
+  // ...
+}
+```
+
+**Después (v1.3.0):**
+```tsx
+import { useTGTAuth } from '@tgtone/auth-sdk';
+
+function App() {
+  const { 
+    session, 
+    loading, 
+    logout,
+    revokedError,     // 🆕 Error de sesión revocada
+    isHeartbeatActive // 🆕 Estado del heartbeat
+  } = useTGTAuth({
+    identityUrl: 'https://identity.tgtone.cl',
+    appDomain: 'zenith.tgtone.cl',
+    enableHeartbeat: true, // 🆕 Default: true
+  });
+  
+  // El heartbeat se inicia automáticamente después del login
+  // ...
+}
+```
+
+### 3. Landing Pages (sin redirección automática)
+
+**Después (v1.3.0):**
+```tsx
+import { useTGTAuth } from '@tgtone/auth-sdk';
+
+function LandingApp() {
+  const { session, loading, revokedError } = useTGTAuth({
+    identityUrl: 'https://identity.tgtone.cl',
+    appDomain: 'tgtone.cl',
+    showRevokedState: true, // 🆕 No redirigir, mostrar estado
+  });
+
+  if (loading) return <Spinner />;
+  
+  // 🆕 Manejar sesión revocada con UI personalizado
+  if (revokedError) {
+    return (
+      <RevokedSessionPage 
+        error={revokedError}
+        onContactSupport={() => window.open('mailto:soporte@tgtone.cl')}
+      />
+    );
+  }
+
+  if (!session) {
+    return <PublicLanding onLogin={() => authClient.redirectToLogin()} />;
+  }
+
+  return <PrivateContent user={session.user} />;
+}
+```
+
+### 4. Apps con Axios
+
+**Después (v1.3.0):**
+```tsx
+import axios from 'axios';
+import { createAxiosInterceptor } from '@tgtone/auth-sdk/interceptor';
+import { authClient } from './lib/auth-client';
+
+const api = axios.create({ 
+  baseURL: '/api',
+  headers: { 'Content-Type': 'application/json' }
+});
+
+// 🆕 Configurar interceptor
+const removeInterceptor = createAxiosInterceptor(api, authClient, {
+  handleRevoked: true,
+  excludeUrls: ['/public/health', '/public/metrics'],
+  onAuthError: (error) => {
+    // Opcional: logging, analytics
+    console.error('Auth error:', error.code);
+  },
+});
+
+export default api;
+```
+
+### 5. Apps con Fetch nativo
+
+**Después (v1.3.0):**
+```tsx
+import { createAuthFetch } from '@tgtone/auth-sdk/interceptor';
+import { authClient } from './lib/auth-client';
+
+// 🆕 Crear fetch con autenticación automática
+const authFetch = createAuthFetch(authClient, {
+  handleRevoked: true,
+  excludeUrls: ['/public/'],
+});
+
+// Uso igual que fetch nativo
+const response = await authFetch('/api/users');
+const data = await response.json();
+```
+
+---
+
+## 🎯 Casos de Uso por Escenario
+
+### Escenario 1: Usuario eliminado mientras trabaja
+
+```
+1. Admin elimina usuario desde Console
+2. Usuario hace request API o heartbeat se ejecuta
+3. Backend retorna 401 + USER_NOT_FOUND
+4. SDK detecta error de revocación
+5. Se ejecuta onSessionRevoked callback
+6. Usuario es redirigido a /blocked?type=user
+```
+
+### Escenario 2: Tenant suspendido
+
+```
+1. Se suspende el tenant (falta de pago, etc.)
+2. Usuario continúa trabajando
+3. Heartbeat detecta TENANT_INACTIVE
+4. Usuario es redirigido a /blocked?type=tenant
+```
+
+### Escenario 3: Usuario desactivado
+
+```
+1. Admin desactiva usuario
+2. Backend retorna USER_INACTIVE
+3. Usuario ve página de blocked con mensaje apropiado
+```
+
+---
+
+## ⚙️ Configuración Avanzada
+
+### Deshabilitar Heartbeat
+
+```tsx
+const authClient = new TGTAuthClient({
+  // ...
+  heartbeatIntervalMs: 0, // Deshabilitado
+});
+```
+
+### Heartbeat más frecuente (1 minuto)
+
+```tsx
+const authClient = new TGTAuthClient({
+  // ...
+  heartbeatIntervalMs: 60 * 1000, // 1 minuto
+});
+```
+
+### Callback personalizado sin redirección
+
+```tsx
+const authClient = new TGTAuthClient({
+  // ...
+  onSessionRevoked: (error) => {
+    // Loguear para analytics
+    analytics.track('session_revoked', { code: error.code });
+    
+    // Mostrar modal en lugar de redirigir
+    showSessionRevokedModal(error);
+  },
+});
+```
+
+---
+
+## 🧪 Testing
+
+### Simular sesión revocada
+
+```typescript
+// En desarrollo, puedes simular el error:
+const testError = {
+  code: 'USER_NOT_FOUND' as AuthErrorCode,
+  message: 'El usuario ha sido eliminado',
+};
+
+authClient.onSessionRevoked?.(testError);
+```
+
+### Verificar heartbeat
+
+```typescript
+// Verificar si está activo
+console.log('Heartbeat activo:', authClient.isHeartbeatActive());
+
+// Iniciar manualmente
+authClient.startHeartbeat();
+
+// Detener
+authClient.stopHeartbeat();
+```
+
+---
+
+## 📦 Checklist de Migración
+
+- [ ] Actualizar `@tgtone/auth-sdk` a `^1.3.0`
+- [ ] Agregar `heartbeatIntervalMs` a la configuración
+- [ ] Agregar `onSessionRevoked` callback
+- [ ] (Opcional) Configurar interceptor Axios
+- [ ] (Opcional) Actualizar hook useTGTAuth
+- [ ] Probar flujo de sesión revocada
+- [ ] Verificar redirección a `/blocked`
+
+---
+
+## ❓ FAQ
+
+**P: ¿El heartbeat afecta el rendimiento?**
+R: No, es un request ligero cada 5 minutos por defecto.
+
+**P: ¿Qué pasa si el backend está offline durante el heartbeat?**
+R: El heartbeat ignora errores de red y reintenta en el próximo intervalo.
+
+**P: ¿Puedo usar mi propia página de blocked?**
+R: Sí, usa `onSessionRevoked` para manejar el error y mostrar tu propia UI.
+
+**P: ¿Necesito configurar el interceptor si uso el heartbeat?**
+R: No es obligatorio, pero recomendado para detectar errores en requests API también.
+
+---
+
+**Versión:** 1.3.0  
+**Última actualización:** 2026-03-26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgtone/auth-sdk",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "SDK de autenticación JWT + Bearer Token para el ecosistema TGT One",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",