@tgtone/auth-sdk 1.4.3 → 1.4.4

package/docs/LOVABLE_QUICK_START.md

@@ -1,316 +0,0 @@
-# 🔐 TGT Auth SDK - Guía para Lovable/React
-
-> Integración rápida de autenticación en proyectos React/Lovable
-
----
-
-## 📦 Instalación
-
-```bash
-npm install @tgtone/auth-sdk
-```
-
-**Versión actual:** 1.2.3
-
----
-
-## ⚡ Setup en 3 Pasos
-
-### **1. Crear AuthContext**
-
-```typescript
-// src/contexts/AuthContext.tsx
-import { createContext, useContext, useEffect, useState, ReactNode } from 'react';
-import { TGTAuthClient, TGTUser } from '@tgtone/auth-sdk';
-
-// Extender TGTSession para incluir roles (están en user.roles)
-interface TGTSession {
-  user: TGTUser;
-  tenantId: string;
-  tenantName: string;
-  expiresAt: Date;
-}
-
-interface AuthContextType {
-  session: TGTSession | null;
-  user: TGTUser | null;              // Acceso directo al usuario
-  tenantId: string | null;           // Acceso directo
-  loading: boolean;
-  logout: () => Promise<void>;
-  hasRole: (app: string, role: string) => boolean;
-  hasAccessToApp: (appName: string) => boolean;
-  getRoles: (appName: string) => string[];
-  getToken: () => string | null;     // Para API calls
-  isAuthenticated: boolean;          // Shorthand
-}
-
-const AuthContext = createContext<AuthContextType | null>(null);
-
-// ✅ Singleton FUERA del componente (evita re-crear en cada render)
-let authClient: TGTAuthClient | null = null;
-
-const getAuthClient = (): TGTAuthClient => {
-  if (!authClient) {
-    authClient = new TGTAuthClient({
-      identityUrl: import.meta.env.VITE_IDENTITY_URL || 'https://identity.tgtone.cl',
-      appDomain: window.location.host, // Usa .host (incluye puerto) para dev
-      debug: import.meta.env.DEV
-    });
-  }
-  return authClient;
-};
-
-export function AuthProvider({ children }: { children: ReactNode }) {
-  const [session, setSession] = useState<TGTSession | null>(null);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    const initAuth = async () => {
-      try {
-        const auth = getAuthClient();
-        const currentSession = await auth.checkSession();
-        setSession(currentSession as TGTSession);
-      } catch (error) {
-        console.error('Error checking session:', error);
-        setSession(null);
-      } finally {
-        setLoading(false);
-      }
-    };
-    initAuth();
-  }, []);
-
-  const logout = async () => {
-    const auth = getAuthClient();
-    await auth.logout();
-    setSession(null);
-  };
-
-  const hasRole = (app: string, role: string) => {
-    return getAuthClient().hasRole(app, role);
-  };
-
-  const hasAccessToApp = (appName: string) => {
-    return getAuthClient().hasAccessToApp(appName);
-  };
-
-  const getRoles = (appName: string) => {
-    return getAuthClient().getRoles(appName);
-  };
-
-  const getToken = () => {
-    return getAuthClient().getToken();
-  };
-
-  return (
-    <AuthContext.Provider value={{ 
-      session, 
-      user: session?.user || null,
-      tenantId: session?.tenantId || null,
-      loading, 
-      logout, 
-      hasRole,
-      hasAccessToApp,
-      getRoles,
-      getToken,
-      isAuthenticated: !!session
-    }}>
-      {/* ⚠️ CRÍTICO: No renderizar hijos mientras carga para evitar que el Router 
-          limpie los parámetros de la URL (?token=...) antes de que el SDK los procese */}
-      {loading ? (
-        <div className="flex items-center justify-center min-h-screen">
-          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary"></div>
-        </div>
-      ) : (
-        children
-      )}
-    </AuthContext.Provider>
-  );
-}
-
-export const useAuth = () => {
-  const context = useContext(AuthContext);
-  if (!context) throw new Error('useAuth must be used within AuthProvider');
-  return context;
-};
-```
-
-### **2. Envolver App**
-
-```tsx
-// src/App.tsx
-import { AuthProvider } from './contexts/AuthContext';
-
-function App() {
-  return (
-    <AuthProvider>
-      {/* Tu app */}
-    </AuthProvider>
-  );
-}
-```
-
-### **3. Usar en Componentes**
-
-```tsx
-import { useAuth } from './contexts/AuthContext';
-
-function Dashboard() {
-  const { user, tenantId, loading, logout, hasRole, isAuthenticated } = useAuth();
-
-  if (loading) return <div>Cargando...</div>;
-  
-  if (!isAuthenticated) return null; // Ya está redirigiendo a login
-
-  return (
-    <div>
-      <h1>Bienvenido {user?.name}</h1>
-      <p>Tenant: {tenantId}</p>
-      
-      {hasRole('console', 'admin') && (
-        <button>Panel Admin</button>
-      )}
-      
-      <button onClick={logout}>Cerrar Sesión</button>
-    </div>
-  );
-}
-```
-
----
-
-## 🎯 Propiedades de Sesión
-
-```typescript
-// Datos del usuario
-session.user.email       // "user@empresa.cl"
-session.user.name        // "Juan Pérez"
-session.user.sub         // "uuid-user-123" (ID del usuario)
-
-// Datos del tenant
-session.tenantId         // "uuid-tenant-123"
-session.tenantName       // "Mi Empresa"
-
-// ⚠️ IMPORTANTE: Los roles están en USER, no en session
-session.user.roles       // { console: ['owner'], crm: ['admin'] }
-
-// Expiración
-session.expiresAt        // Date object
-```
-
-> **Nota:** Los roles se acceden via `session.user.roles`, NO `session.roles`
-
----
-
-## 🔐 Verificar Roles
-
-```typescript
-// Usando el hook useAuth (recomendado)
-const { hasRole, hasAccessToApp, getRoles } = useAuth();
-
-// ¿Es admin de Console?
-if (hasRole('console', 'admin')) {
-  // Mostrar funciones de admin
-}
-
-// ¿Tiene acceso a CRM?
-if (hasAccessToApp('crm')) {
-  // Mostrar enlace a CRM
-}
-
-// Obtener todos los roles en una app
-const roles = getRoles('console'); // ['owner', 'admin']
-
-// Verificar múltiples roles
-const isAdmin = hasRole('myapp', 'admin') || hasRole('myapp', 'owner');
-```
-
----
-
-## 🆕 Verificación Silenciosa (v1.2.0)
-
-Para páginas que no requieren autenticación obligatoria:
-
-```typescript
-// Landing page o página pública
-useEffect(() => {
-  const checkAuth = async () => {
-    const session = await authClient.checkSessionSilent();
-    
-    if (session) {
-      // Usuario logeado - mostrar contenido personalizado
-      showButton('Ir al Dashboard', '/dashboard');
-    } else {
-      // Usuario no logeado - mostrar botón de login
-      showButton('Iniciar Sesión', () => authClient.redirectToLogin());
-    }
-  };
-  
-  checkAuth();
-}, []);
-```
-
----
-
-## 🔄 Flujo de Autenticación
-
-```
-1. Usuario entra a tu app
-   ↓
-2. checkSession() no encuentra token
-   ↓
-3. SDK redirige a identity.tgtone.cl/login
-   ↓
-4. Usuario hace login (+ MFA si está habilitado)
-   ↓
-5. Identity redirige: tu-app?token=eyJhbGci...
-   ↓
-6. SDK guarda token y valida con backend
-   ↓
-7. ✅ Usuario autenticado
-```
-
----
-
-## 🧪 Testing sin Login
-
-```typescript
-// Guardar token manualmente en localStorage
-localStorage.setItem('tgtone_auth_token', 'eyJhbGci...');
-window.location.reload();
-
-// Obtener token de prueba con curl:
-// curl -X POST https://tgtone-console-backend.run.app/api/v1/auth/login \
-//   -d '{"email": "user@test.cl", "password": "Test123!"}'
-```
-
----
-
-## 📚 API Completa
-
-Ver documentación completa: **[README.md](../README.md)**
-
-Métodos disponibles:
-- `checkSession()` - Verifica sesión (redirige si no hay)
-- `checkSessionSilent()` - Verifica sin redirigir
-- `signup()` - Crear cuenta
-- `login()` - Iniciar sesión
-- `logout()` - Cerrar sesión
-- `verifyMfa()` - Validar código MFA
-- `hasRole()` - Verificar roles
-- `redirectToLogin()` - Redirigir a login
-
----
-
-## 🔧 Variables de Entorno
-
-```env
-# .env.local
-VITE_IDENTITY_URL=https://identity.tgtone.cl
-```
-
-> En desarrollo local, si no defines `VITE_IDENTITY_URL`, usará `https://identity.tgtone.cl` por defecto.
-
----
-
-**Última actualización:** 2025-12-19