@tgtone/auth-sdk 1.4.2 → 1.4.4

package/docs/INTEGRATION_EXAMPLES.md

@@ -1,177 +1,131 @@
-# 🔧 Ejemplos de Integración por Framework
+# Ejemplos de Integración por Framework
 
-Guía paso a paso para integrar TGT One Auth en diferentes frameworks.
+Guía paso a paso para integrar TGT One Auth en diferentes frameworks usando el paquete npm.
 
 ---
 
-## 📘 React (Vite)
+## React (Vite)
 
-### **1. Copiar archivos**
+### 1. Instalar
 
 ```bash
-# En tu proyecto React
-mkdir -p src/lib/auth
-cp tgtone-auth-client.ts src/lib/auth/
-cp react-hook.tsx src/lib/auth/
+npm install @tgtone/auth-sdk
 ```
 
-### **2. Crear contexto de autenticación**
+### 2. Usar el hook `useTGTAuth`
 
 ```tsx
-// src/contexts/AuthContext.tsx
-import { createContext, useContext } from 'react';
-import { useTGTAuth, UseTGTAuthResult } from '@/lib/auth/react-hook';
-
-const AuthContext = createContext<UseTGTAuthResult | null>(null);
+// src/App.tsx
+import { useTGTAuth } from '@tgtone/auth-sdk/react';
 
-export function AuthProvider({ children }: { children: React.ReactNode }) {
-  const auth = useTGTAuth({
-    identityUrl: 'https://identity.tgtone.cl',
-    appDomain: 'zenith.tgtone.cl', // Cambiar según tu app
-    debug: import.meta.env.DEV
+function App() {
+  const { session, loading, logout, hasRole, revokedError } = useTGTAuth({
+    identityUrl: import.meta.env.VITE_IDENTITY_URL || 'https://identity.tgtone.cl',
+    appDomain: window.location.host,
+    appKey: import.meta.env.VITE_APP_KEY, // Requerido en dev
+    enableHeartbeat: true,
+    debug: import.meta.env.DEV,
   });
 
+  if (loading) return <LoadingSpinner />;
+  if (revokedError) return <RevokedPage error={revokedError} />;
+  if (!session) return null;
+
   return (
-    <AuthContext.Provider value={auth}>
-      {children}
-    </AuthContext.Provider>
+    <div>
+      <header>
+        <span>{session.user.name} - {session.tenantName}</span>
+        <button onClick={logout}>Cerrar sesión</button>
+      </header>
+      {hasRole('zenith', 'admin') && <AdminPanel />}
+    </div>
   );
 }
-
-export const useAuth = () => {
-  const context = useContext(AuthContext);
-  if (!context) {
-    throw new Error('useAuth debe usarse dentro de AuthProvider');
-  }
-  return context;
-};
 ```
 
-### **3. Envolver tu app**
+### 3. Interceptor Axios para API calls
 
 ```tsx
-// src/main.tsx
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-import { AuthProvider } from './contexts/AuthContext';
-import App from './App';
-
-createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <AuthProvider>
-      <App />
-    </AuthProvider>
-  </StrictMode>,
-);
-```
-
-### **4. Usar en componentes**
-
-```tsx
-// src/App.tsx
-import { useAuth } from './contexts/AuthContext';
-
-function App() {
-  const { user, loading, logout, hasRole } = useAuth();
-
-  if (loading) {
-    return (
-      <div className="flex items-center justify-center min-h-screen">
-        <div className="animate-spin rounded-full h-32 w-32 border-b-2 border-gray-900"></div>
-      </div>
-    );
-  }
+import { createAxiosInterceptor } from '@tgtone/auth-sdk/interceptor';
+import { useTGTAuth } from '@tgtone/auth-sdk/react';
 
-  if (!user) {
-    // Ya está redirigiendo al login
-    return null;
-  }
+function Dashboard() {
+  const { authClient, session } = useTGTAuth({
+    identityUrl: 'https://identity.tgtone.cl',
+    appDomain: 'zenith.tgtone.cl',
+  });
 
-  return (
-    <div className="container mx-auto p-4">
-      <nav className="flex justify-between items-center mb-8">
-        <h1 className="text-2xl font-bold">Zenith CRM</h1>
-        <div className="flex items-center gap-4">
-          <span>{user.name}</span>
-          <span className="text-sm text-gray-600">{user.tenant_name}</span>
-          <button 
-            onClick={logout}
-            className="px-4 py-2 bg-red-500 text-white rounded"
-          >
-            Cerrar sesión
-          </button>
-        </div>
-      </nav>
+  useEffect(() => {
+    if (!session) return;
 
-      {hasRole('zenith', 'admin') && (
-        <div className="bg-yellow-100 p-4 rounded mb-4">
-          <h2>Panel de Administración</h2>
-        </div>
-      )}
+    const api = axios.create({ baseURL: '/api' });
+    const cleanup = createAxiosInterceptor(api, authClient, {
+      handleRevoked: true,
+      excludeUrls: ['/public/'],
+    });
 
-      <main>
-        {/* Tu contenido aquí */}
-      </main>
-    </div>
-  );
+    return cleanup;
+  }, [session, authClient]);
 }
-
-export default App;
 ```
 
 ---
 
-## 📗 Vue 3 (Vite)
+## Vue 3 (Vite)
 
-### **1. Copiar archivo**
+### 1. Instalar
 
 ```bash
-mkdir -p src/lib/auth
-cp tgtone-auth-client.ts src/lib/auth/
+npm install @tgtone/auth-sdk
 ```
 
-### **2. Crear composable**
+### 2. Crear composable
 
 ```typescript
 // src/composables/useAuth.ts
 import { ref, onMounted } from 'vue';
-import { TGTAuthClient, type TGTUser } from '@/lib/auth/tgtone-auth-client';
+import { TGTAuthClient, type TGTSession } from '@tgtone/auth-sdk';
 
 const authClient = new TGTAuthClient({
-  identityUrl: 'https://identity.tgtone.cl',
-  appDomain: 'baco.tgtone.cl', // Cambiar según tu app
-  debug: import.meta.env.DEV
+  identityUrl: import.meta.env.VITE_IDENTITY_URL || 'https://identity.tgtone.cl',
+  appDomain: window.location.host,
+  appKey: import.meta.env.VITE_APP_KEY, // Requerido en dev
+  heartbeatIntervalMs: 5 * 60 * 1000,
+  debug: import.meta.env.DEV,
 });
 
-const user = ref<TGTUser | null>(null);
+const session = ref<TGTSession | null>(null);
 const loading = ref(true);
 
 export function useAuth() {
   onMounted(async () => {
-    user.value = await authClient.checkSession();
+    session.value = await authClient.checkSession();
     loading.value = false;
+
+    if (session.value) {
+      authClient.startHeartbeat();
+    }
   });
 
   const logout = async () => {
+    authClient.stopHeartbeat();
     await authClient.logout();
-    user.value = null;
+    session.value = null;
   };
 
   const hasRole = (appName: string, roleName: string) => {
     return authClient.hasRole(appName, roleName);
   };
 
-  return {
-    user,
-    loading,
-    logout,
-    hasRole,
-    authClient
+  const hasAccessToApp = (appName: string) => {
+    return authClient.hasAccessToApp(appName);
   };
+
+  return { session, loading, logout, hasRole, hasAccessToApp, authClient };
 }
 ```
 
-### **3. Usar en App.vue**
+### 3. Usar en componente
 
 ```vue
 <!-- src/App.vue -->
@@ -179,162 +133,87 @@ export function useAuth() {
   <div v-if="loading" class="loading">
     <div class="spinner"></div>
   </div>
-  
-  <div v-else-if="user" class="app">
-    <nav class="navbar">
-      <h1>Baco Wine Management</h1>
-      <div class="user-info">
-        <span>{{ user.name }}</span>
-        <span class="tenant">{{ user.tenant_name }}</span>
-        <button @click="logout" class="logout-btn">
-          Cerrar sesión
-        </button>
-      </div>
+
+  <div v-else-if="session" class="app">
+    <nav>
+      <h1>Mi App</h1>
+      <span>{{ session.user.name }} - {{ session.tenantName }}</span>
+      <button @click="logout">Cerrar sesión</button>
     </nav>
 
-    <div v-if="hasRole('baco', 'admin')" class="admin-panel">
+    <div v-if="hasRole('baco', 'admin')">
       Panel de Administración
     </div>
 
-    <main>
-      <!-- Tu contenido aquí -->
-    </main>
+    <router-view />
   </div>
 </template>
 
 <script setup lang="ts">
 import { useAuth } from './composables/useAuth';
-
-const { user, loading, logout, hasRole } = useAuth();
+const { session, loading, logout, hasRole } = useAuth();
 </script>
-
-<style scoped>
-.loading {
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  height: 100vh;
-}
-
-.spinner {
-  border: 4px solid #f3f3f3;
-  border-top: 4px solid #3498db;
-  border-radius: 50%;
-  width: 40px;
-  height: 40px;
-  animation: spin 1s linear infinite;
-}
-
-@keyframes spin {
-  0% { transform: rotate(0deg); }
-  100% { transform: rotate(360deg); }
-}
-</style>
 ```
 
 ---
 
-## 📙 Next.js 14 (App Router)
+## Next.js 14 (App Router)
 
-### **1. Copiar archivo**
+### 1. Instalar
 
 ```bash
-mkdir -p lib/auth
-cp tgtone-auth-client.ts lib/auth/
+npm install @tgtone/auth-sdk
 ```
 
-### **2. Crear Provider**
+### 2. Crear Provider (client component)
 
 ```tsx
 // app/providers/auth-provider.tsx
 'use client';
 
-import { createContext, useContext, useEffect, useState, ReactNode } from 'react';
-import { TGTAuthClient, type TGTUser } from '@/lib/auth/tgtone-auth-client';
-
-interface AuthContextType {
-  user: TGTUser | null;
-  loading: boolean;
-  logout: () => Promise<void>;
-  hasRole: (appName: string, roleName: string) => boolean;
-}
+import { useTGTAuth } from '@tgtone/auth-sdk/react';
+import { createContext, useContext } from 'react';
+import type { UseTGTAuthResult } from '@tgtone/auth-sdk/react';
 
-const AuthContext = createContext<AuthContextType | null>(null);
+const AuthContext = createContext<UseTGTAuthResult | null>(null);
 
-export function AuthProvider({ children }: { children: ReactNode }) {
-  const [user, setUser] = useState<TGTUser | null>(null);
-  const [loading, setLoading] = useState(true);
-  
-  const authClient = new TGTAuthClient({
-    identityUrl: 'https://identity.tgtone.cl',
-    appDomain: 'console.tgtone.cl', // Cambiar según tu app
-    debug: process.env.NODE_ENV === 'development'
+export function AuthProvider({ children }: { children: React.ReactNode }) {
+  const auth = useTGTAuth({
+    identityUrl: process.env.NEXT_PUBLIC_IDENTITY_URL || 'https://identity.tgtone.cl',
+    appDomain: typeof window !== 'undefined' ? window.location.host : '',
+    appKey: process.env.NEXT_PUBLIC_APP_KEY,
+    enableHeartbeat: true,
+    debug: process.env.NODE_ENV === 'development',
   });
 
-  useEffect(() => {
-    async function checkAuth() {
-      const authenticatedUser = await authClient.checkSession();
-      setUser(authenticatedUser);
-      setLoading(false);
-    }
-    checkAuth();
-  }, []);
-
-  const logout = async () => {
-    await authClient.logout();
-    setUser(null);
-  };
-
-  const hasRole = (appName: string, roleName: string) => {
-    return authClient.hasRole(appName, roleName);
-  };
-
-  return (
-    <AuthContext.Provider value={{ user, loading, logout, hasRole }}>
-      {children}
-    </AuthContext.Provider>
-  );
+  return <AuthContext.Provider value={auth}>{children}</AuthContext.Provider>;
 }
 
 export const useAuth = () => {
   const context = useContext(AuthContext);
-  if (!context) {
-    throw new Error('useAuth debe usarse dentro de AuthProvider');
-  }
+  if (!context) throw new Error('useAuth debe usarse dentro de AuthProvider');
   return context;
 };
 ```
 
-### **3. Envolver en layout**
+### 3. Envolver en layout
 
 ```tsx
 // app/layout.tsx
 import { AuthProvider } from './providers/auth-provider';
-import './globals.css';
 
-export const metadata = {
-  title: 'TGT One Console',
-  description: 'Console de administración TGT One',
-};
-
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="es">
       <body>
-        <AuthProvider>
-          {children}
-        </AuthProvider>
+        <AuthProvider>{children}</AuthProvider>
       </body>
     </html>
   );
 }
 ```
 
-### **4. Usar en páginas**
+### 4. Usar en páginas
 
 ```tsx
 // app/page.tsx
@@ -343,45 +222,19 @@ export default function RootLayout({
 import { useAuth } from './providers/auth-provider';
 
 export default function HomePage() {
-  const { user, loading, logout, hasRole } = useAuth();
+  const { session, loading, logout, hasRole, revokedError } = useAuth();
 
-  if (loading) {
-    return <div className="flex h-screen items-center justify-center">
-      <div className="animate-spin rounded-full h-32 w-32 border-b-2 border-gray-900"></div>
-    </div>;
-  }
-
-  if (!user) {
-    return null; // Redirigiendo
-  }
+  if (loading) return <Spinner />;
+  if (revokedError) return <RevokedPage error={revokedError} />;
+  if (!session) return null;
 
   return (
-    <div className="container mx-auto p-8">
-      <nav className="flex justify-between items-center mb-8">
-        <h1 className="text-3xl font-bold">TGT One Console</h1>
-        <div className="flex items-center gap-4">
-          <div className="text-right">
-            <p className="font-medium">{user.name}</p>
-            <p className="text-sm text-gray-600">{user.tenant_name}</p>
-          </div>
-          <button 
-            onClick={logout}
-            className="px-4 py-2 bg-red-500 text-white rounded hover:bg-red-600"
-          >
-            Cerrar sesión
-          </button>
-        </div>
-      </nav>
-
-      {hasRole('console', 'owner') && (
-        <div className="bg-blue-100 p-4 rounded mb-6">
-          <h2 className="font-bold">Configuración de Owner</h2>
-        </div>
-      )}
-
-      <main>
-        {/* Tu contenido */}
-      </main>
+    <div>
+      <header>
+        <span>{session.user.name}</span>
+        <button onClick={logout}>Cerrar sesión</button>
+      </header>
+      {hasRole('console', 'owner') && <OwnerSettings />}
     </div>
   );
 }
@@ -389,39 +242,43 @@ export default function HomePage() {
 
 ---
 
-## 📕 Angular 17+
+## Angular 17+
 
-### **1. Copiar archivo**
+### 1. Instalar
 
 ```bash
-mkdir -p src/app/services/auth
-cp tgtone-auth-client.ts src/app/services/auth/
+npm install @tgtone/auth-sdk
 ```
 
-### **2. Crear servicio**
+### 2. Crear servicio
 
 ```typescript
-// src/app/services/auth/auth.service.ts
+// src/app/services/auth.service.ts
 import { Injectable } from '@angular/core';
-import { BehaviorSubject, Observable } from 'rxjs';
-import { TGTAuthClient, TGTUser } from './tgtone-auth-client';
+import { BehaviorSubject } from 'rxjs';
+import { TGTAuthClient, TGTSession, AuthError } from '@tgtone/auth-sdk';
 
-@Injectable({
-  providedIn: 'root'
-})
+@Injectable({ providedIn: 'root' })
 export class AuthService {
   private authClient: TGTAuthClient;
-  private userSubject = new BehaviorSubject<TGTUser | null>(null);
+  private sessionSubject = new BehaviorSubject<TGTSession | null>(null);
   private loadingSubject = new BehaviorSubject<boolean>(true);
+  private revokedSubject = new BehaviorSubject<AuthError | null>(null);
 
-  public user$: Observable<TGTUser | null> = this.userSubject.asObservable();
-  public loading$: Observable<boolean> = this.loadingSubject.asObservable();
+  session$ = this.sessionSubject.asObservable();
+  loading$ = this.loadingSubject.asObservable();
+  revokedError$ = this.revokedSubject.asObservable();
 
   constructor() {
     this.authClient = new TGTAuthClient({
       identityUrl: 'https://identity.tgtone.cl',
-      appDomain: 'zenith.tgtone.cl', // Cambiar según tu app
-      debug: !environment.production
+      appDomain: window.location.host,
+      appKey: 'console', // Ajustar según la app
+      onSessionRevoked: (error) => {
+        this.revokedSubject.next(error);
+        this.sessionSubject.next(null);
+      },
+      debug: !environment.production,
     });
 
     this.checkSession();
@@ -429,108 +286,110 @@ export class AuthService {
 
   private async checkSession() {
     try {
-      const user = await this.authClient.checkSession();
-      this.userSubject.next(user);
+      const session = await this.authClient.checkSession();
+      this.sessionSubject.next(session);
+
+      if (session) {
+        this.authClient.startHeartbeat();
+      }
     } catch (error) {
       console.error('Error checking session:', error);
-      this.userSubject.next(null);
     } finally {
       this.loadingSubject.next(false);
     }
   }
 
   async logout() {
+    this.authClient.stopHeartbeat();
     await this.authClient.logout();
-    this.userSubject.next(null);
+    this.sessionSubject.next(null);
   }
 
   hasRole(appName: string, roleName: string): boolean {
     return this.authClient.hasRole(appName, roleName);
   }
 
-  get currentUser(): TGTUser | null {
-    return this.userSubject.value;
+  hasAccessToApp(appName: string): boolean {
+    return this.authClient.hasAccessToApp(appName);
   }
 }
 ```
 
-### **3. Usar en componentes**
+### 3. Usar en componente
 
 ```typescript
 // src/app/app.component.ts
 import { Component } from '@angular/core';
-import { AuthService } from './services/auth/auth.service';
+import { AuthService } from './services/auth.service';
 
 @Component({
   selector: 'app-root',
   template: `
-    <div *ngIf="authService.loading$ | async" class="loading">
+    <div *ngIf="auth.loading$ | async" class="loading">
       <div class="spinner"></div>
     </div>
 
-    <div *ngIf="(authService.user$ | async) as user" class="app">
-      <nav class="navbar">
-        <h1>Zenith CRM</h1>
-        <div class="user-info">
-          <span>{{ user.name }}</span>
-          <span class="tenant">{{ user.tenant_name }}</span>
-          <button (click)="logout()" class="logout-btn">
-            Cerrar sesión
-          </button>
-        </div>
-      </nav>
-
-      <div *ngIf="authService.hasRole('zenith', 'admin')" class="admin-panel">
-        Panel de Administración
-      </div>
+    <div *ngIf="auth.revokedError$ | async as error" class="blocked">
+      <h2>Acceso bloqueado</h2>
+      <p>{{ error.message }}</p>
+    </div>
 
-      <router-outlet></router-outlet>
+    <div *ngIf="(auth.session$ | async) as session">
+      <nav>
+        <h1>Mi App</h1>
+        <span>{{ session.user.name }}</span>
+        <button (click)="logout()">Cerrar sesión</button>
+      </nav>
+      <div *ngIf="auth.hasRole('zenith', 'admin')">Admin Panel</div>
+      <router-outlet />
     </div>
   `,
-  styleUrls: ['./app.component.css']
 })
 export class AppComponent {
-  constructor(public authService: AuthService) {}
+  constructor(public auth: AuthService) {}
 
   logout() {
-    this.authService.logout();
+    this.auth.logout();
   }
 }
 ```
 
 ---
 
-## 🔑 Variables de Entorno por App
+## Variables de Entorno por App
 
-### **Zenith (CRM)**
-```env
-VITE_APP_DOMAIN=zenith.tgtone.cl
-VITE_IDENTITY_URL=https://identity.tgtone.cl
-```
+| App | `VITE_APP_KEY` | `VITE_APP_DOMAIN` |
+|-----|---------------|-------------------|
+| Zenith (CRM) | `zenith` | `zenith.tgtone.cl` |
+| Baco (Wine) | `baco` | `baco.tgtone.cl` |
+| Console (Admin) | `console` | `console.tgtone.cl` |
 
-### **Baco (Wine Management)**
 ```env
-VITE_APP_DOMAIN=baco.tgtone.cl
+# .env.local (ejemplo para Baco en dev)
 VITE_IDENTITY_URL=https://identity.tgtone.cl
+VITE_APP_KEY=baco
 ```
 
-### **Console (Admin)**
-```env
-VITE_APP_DOMAIN=console.tgtone.cl
-VITE_IDENTITY_URL=https://identity.tgtone.cl
-```
+> En producción, si el dominio es `baco.tgtone.cl`, el SDK extrae el app key automáticamente y `appKey` no es necesario.
 
 ---
 
-## ✅ Checklist de Integración
-
-- [ ] Copiar `tgtone-auth-client.ts` al proyecto
-- [ ] Configurar variables de entorno
-- [ ] Crear wrapper/provider según framework
-- [ ] Implementar UI de loading
-- [ ] Implementar botón de logout
-- [ ] Probar flujo de login/logout
-- [ ] Probar SSO entre apps
-- [ ] Verificar roles y permisos
-- [ ] Manejar estados de error
-- [ ] Documentar para el equipo
+## Checklist de Integración
+
+- [ ] `npm install @tgtone/auth-sdk`
+- [ ] Configurar variables de entorno (`VITE_IDENTITY_URL`, `VITE_APP_KEY`)
+- [ ] Implementar hook/composable/provider según framework
+- [ ] Manejar estados: `loading`, `session`, `revokedError`
+- [ ] Bloquear renderizado mientras `loading === true` (evita que Router limpie `?token=`)
+- [ ] Configurar interceptor Axios/Fetch para API calls
+- [ ] Probar flujo login/logout
+- [ ] Probar detección de sesión revocada (desactivar usuario en Console)
+- [ ] Verificar roles y permisos por app
+
+---
+
+## Referencia
+
+- **[QUICKSTART_REACT.md](./QUICKSTART_REACT.md)** - Quick Start detallado para React
+- **[API.md](./API.md)** - Referencia completa de API
+- **[CHANGELOG.md](../CHANGELOG.md)** - Historial de cambios