webs-sdk 0.19.62 → 0.19.64

package/README.md

@@ -1,451 +1,490 @@
-# webs-sdk
-
-SDK interno npm para portales Nexum. Encapsula toda la lógica común: autenticación, sesiones, comunicación con la API, tracking, internacionalización y componentes React reutilizables.
-
-**Versión actual:** 0.18.9
-
-## Instalación
-
-```bash
-npm install webs-sdk
-```
-
-## Uso básico
-
-```typescript
-import WebsSDK from 'webs-sdk';
-
-// Inicializar sesión
-await WebsSDK.Session.init();
-
-// Petición HTTP
-const data = await WebsSDK.Networking.request('/api/endpoint', { param: 'value' });
-
-// Almacenamiento local
-WebsSDK.Storage.set('key', 'value');
-const value = WebsSDK.Storage.get('key');
-```
-
-## Librerías disponibles
-
-### Networking
-
-```typescript
-// Petición HTTP (inyecta sessionData automáticamente)
-await WebsSDK.Networking.request(url, data);
-
-// Eventos de tracking
-await WebsSDK.Networking.sendEvent('action', 'button_click', { button_id: 'submit' });
-
-// Suscripciones
-await WebsSDK.Networking.createSubscription(subscriptionData);
-const { success, subscription_active } = await WebsSDK.Networking.checkSubscription();
-```
-
-### Storage
-
-```typescript
-WebsSDK.Storage.set('key', 'value');
-const value = WebsSDK.Storage.get('key');
-
-// Compresión de imágenes (0.8 ratio, 1024px max)
-const compressed = await WebsSDK.Storage.compressImage(imageFile, 2); // 2MB max
-
-// Creaciones (imágenes generadas por el usuario)
-await WebsSDK.Storage.handleDownloadImageToCreations(base64, 'id', metadata);
-const creations = await WebsSDK.Storage.getCreations();
-await WebsSDK.Storage.deleteCreation('id');
-```
-
-### Session
-
-```typescript
-await WebsSDK.Session.init();
-
-const sessionData = WebsSDK.Session.getSessionData();
-const userId = WebsSDK.Session.getUserID();
-const lang = WebsSDK.Session.getDeviceLanguage();
-const isSubscribed = WebsSDK.Session.getIsSubscribed();
-```
-
-### Utils
-
-```typescript
-const id = WebsSDK.Utils.generateId();
-const isValidEmail = WebsSDK.Utils.isValidEmail('user@example.com');
-const isMobile = WebsSDK.Utils.isMobile();
-const deviceInfo = WebsSDK.Utils.getDeviceInfo();
-const truncated = WebsSDK.Utils.truncateText('Long text...', 10);
-```
-
-### MixPanel
-
-```typescript
-await WebsSDK.MixPanel.initialize(token, false, false, false);
-await WebsSDK.MixPanel.trackEvent('page_view', { page: 'home' });
-await WebsSDK.MixPanel.identifyUser('user_123');
-await WebsSDK.MixPanel.setUserProperties({ plan: 'premium' });
-```
-
-### AuthManager
-
-```typescript
-// Login estándar
-await WebsSDK.AuthManager.authUser({ login, password, website_id });
-
-// Login sin password (MSISDN)
-await WebsSDK.AuthManager.authOnlyUser({ login, website_id });
-
-// Login con OTP
-await WebsSDK.AuthManager.authOnlyUserOTP({ login, website_id, pincode });
-
-// Registro
-await WebsSDK.AuthManager.createUser({ login, password, website_id });
-
-// Auto-login post-pago (usado en el proxy de next_template)
-await WebsSDK.AuthManager.auto_login(cfg_sessionid, websiteData, requestUrl);
-
-// Baja/cancelación
-await WebsSDK.AuthManager.unsubscribeUser({ user_id, callback_url?, org? });
-
-// Gestión de perfil
-await WebsSDK.AuthManager.setUserMetadata(params);
-await WebsSDK.AuthManager.uploadProfilePhoto(params); // JPG/PNG/WEBP, max 5MB
-await WebsSDK.AuthManager.changePassword(params);
-```
-
-### Andromeda — Portales
-
-```typescript
-// Metadata del portal (optimizado con cookie websiteDataFlag)
-await WebsSDK.Andromeda.getWebsiteMetadatabyHostname('portal.com');
-
-// Configuración del producto (langs, login_type, logo, favicon, theme)
-await WebsSDK.Andromeda.getWebsiteConfig('portal-corp-web');
-```
-
-### ContentManager
-
-```typescript
-// Contenido por preset
-await WebsSDK.ContentManager.getContentByPreset('homepage', { lang: 'es' });
-
-// Colección filtrada por tags
-await WebsSDK.ContentManager.getCollection(['tag1', 'tag2'], 'es', false);
-```
-
-### User
-
-```typescript
-await WebsSDK.User.checkSession(token);            // Valida token (usado en middleware)
-await WebsSDK.User.getUserData(user_id, website_id);
-await WebsSDK.User.getCredits(user_id, website_id);
-```
-
-### CorporateAuthManager
-
-```typescript
-// Server-side (middleware Next.js)
-const result = await WebsSDK.CorporateAuthManager.validateCorporateAuthServerSide(request);
-if (!result.authenticated) return result.redirectResponse;
-
-// Client-side
-await WebsSDK.CorporateAuthManager.checkCorporateLogin();
-await WebsSDK.CorporateAuthManager.validateUser(autoRedirect?);
-await WebsSDK.CorporateAuthManager.login(returnTo?);
-await WebsSDK.CorporateAuthManager.logout(redirectTo?);
-await WebsSDK.CorporateAuthManager.isAdmin(userData?);
-```
-
-### Legal
-
-```typescript
-await WebsSDK.Legal.getLegalText('tos' | 'privacy' | 'faq', web_id, lang);
-```
-
-### Namespace `pre` — Pre-producción
-
-```typescript
-// Lazy-loaded, apunta a bc1742-pre.gways.org
-await WebsSDK.pre.AuthManager.authUser(params);
-await WebsSDK.pre.Andromeda.getWebsiteMetadatabyHostname(hostname);
-```
-
----
-
-## Componentes React
-
-### CookieConsent — Banner GDPR
-
-```typescript
-import { CookieConsent, getCookieConsentTexts } from 'webs-sdk';
-import type { CookieConsentProps, CookieConsentTheme, CookieConsentPreferences } from 'webs-sdk';
-
-<CookieConsent
-  locale="es"                        // en | es | fr | nl | ar | de | fi | ro | tr
-  privacyPolicyUrl="/privacy"
-  theme={{
-    backgroundColor: '#1a1a2e',
-    accentColor: '#6c63ff',           // aplica a botón Accept, borde Reject, links y glow
-    acceptButtonBg: 'linear-gradient(90deg, #6c63ff, #a855f7)', // soporta gradients CSS
-    textColor: '#ffffff',
-  }}
-  onAccept={() => updateGAConsent('granted')}
-  onReject={() => updateGAConsent('denied')}
-  onSaveSettings={(prefs: CookieConsentPreferences) => handlePrefs(prefs)}
-/>
-```
-
-**Storage:**
-- Cookie `cookieConsent`: `accepted | rejected | custom` (1 año)
-- `localStorage.TRACKING_PERMISSION`: `granted | denied`
-- `localStorage.FUNCTIONAL_PERMISSION`: `granted | denied`
-
-### Google Analytics — GA4
-
-```typescript
-import { initGoogleAnalytics, updateGAConsent, trackGAEvent, trackGAPageView, isGALoaded } from 'webs-sdk';
-
-// Registra el GA ID. Carga el script SOLO si hay consentimiento previo.
-await initGoogleAnalytics('G-XXXXXXXXXX', { sendPageView: true, debug: false });
-
-// Llamar tras decisión del usuario en CookieConsent
-updateGAConsent('granted');  // carga GA si había pendingTrackingId
-updateGAConsent('denied');   // GA nunca se carga
-
-// Tracking
-trackGAEvent('purchase', { value: 9.99, currency: 'EUR' });
-trackGAPageView('/home', 'Inicio');
-isGALoaded(); // boolean
-```
-
-> **GDPR estricto:** GA no usa Consent Mode v2. Si no hay consentimiento, el script `gtag.js` nunca se inyecta en el DOM.
-
-### CDN Proxy
-
-```typescript
-import { handleCDNRequest } from 'webs-sdk';
-import type { CDNOptions } from 'webs-sdk';
-
-// Usar en un route handler de Next.js (compatible con Edge Runtime)
-async function handleCDNRequest(
-  pathname: string,        // '/cdn/apariencias/33702/image.png'
-  options?: {
-    cdnBaseUrl?: string;   // Default: 'https://dy822md8ge77v.cloudfront.net'
-    cacheSeconds?: number; // Default: 300 (5 min)
-  }
-): Promise<Response | null>  // null si pathname no empieza por /cdn/
-```
-
-### Componentes "For You" — Creación de contenido AI
-
-```typescript
-import {
-  AvatarAI, AvatarAIPage, AvatarAIForYouCard,
-  CreativeFaceSwap, CreativeFaceSwapPage, CreativeFaceSwapForYouCard,
-  MemeGenerator, MemeGeneratorPage, MemeGeneratorForYouCard,
-  WallpapersName, WallpapersNamePage, WallpapersNameForYouCard,
-  Wallpapers,
-  Ringtone,
-} from 'webs-sdk';
-```
-
-Todos aceptan `websiteId?: string` para tracking multi-portal.
-
-### ARFilters — Filtros AR con DeepAR
-
-```typescript
-import { ARFilters, ARFiltersForYouCard } from 'webs-sdk';
-import type { DeepARProps, DeepARFilter, DeepARTexts } from 'webs-sdk';
-
-<ARFilters
-  licenseKey="deepar-license-key"
-  websiteId="portal-web-id"
-  apiBaseUrl="https://api.fluver-ai.com"
-  downloadProxyUrl="/cdn"            // Proxy CORS para descarga de efectos
-  filterTag="ar-filters-tag"         // Obtiene filtros del CMS por tag
-  // O bien: filters={[{ file: 'beauty', thumbUrl: '/thumb.jpg' }]}
-  locale="es"
-  texts={getARFiltersTexts('es')}    // requerido
-  onPhotoTaken={(url) => share(url)}
-  onVideoRecorded={(url) => share(url)}
-/>
-```
-
-Soporta fullscreen en mobile (vendor-prefixed API para iOS Safari).
-
-### SpinningWheel — Ruleta
-
-```typescript
-import { SpinningWheel, wheelThemes } from 'webs-sdk';
-
-// Temas: vodacom | totalgym | womantoday | afristream | efc
-<SpinningWheel
-  userId={userId}
-  websiteId={websiteId}
-  theme="vodacom"
-  onResult={(segment) => handleWin(segment)}
-  canSpin={true}
-  alreadySpunToday={false}
-/>
-```
-
-### Quiz y Stickers
-
-```typescript
-import { Quiz, Stickers } from 'webs-sdk';
-```
-
-### Esports — Noticias, Vídeos y Partidas en Directo
-
-```typescript
-import { EsportsNews, EsportsVideos, EsportsLive } from 'webs-sdk';
-```
-
-#### EsportsNews
-
-```typescript
-<EsportsNews
-  config={{
-    key: 'api-key',
-    contents: [{ preset: 'esports_news', apiProviderId: 'id', category: [], tags: [], limit: 10 }]
-  }}
-  language="es"
-  onNewsClick={(item) => router.push(`/news/${item.id}`)}
-  theme={theme}                    // CSS classes para container, cards, badges, etc.
-  categoryStyles={{ gaming: { badge: 'bg-blue-500', badgeText: 'text-white' } }}
-  // Modo detalle (renderiza EsportsNewsDetail):
-  newsId="article-id"
-  newsData={item}                  // opcional si ya tienes los datos
-  onBack={() => router.back()}
-/>
-```
-
-#### EsportsVideos
-
-```typescript
-<EsportsVideos
-  config={{ key: 'api-key', contents: [...] }}
-  language="es"
-  onVideoClick={(item) => openPlayer(item.video_url)}
-  theme={theme}                    // incluye clases para duration overlay
-/>
-```
-
-#### EsportsLive
-
-```typescript
-<EsportsLive
-  language="es"
-  timezone="Europe/Madrid"
-  onLiveClick={(item) => openStream(item.streamUrl)}
-  onMatchClick={(match) => openMatchDetail(match)}
-  onGameClick={(gameId) => filterByGame(gameId)}
-  website_id="portal-web-id"
-  theme={theme}
-  // Modo detalle de partida:
-  matchId="serie-id"
-  matchData={calendarMatch}
-  onBack={() => setMatchId(null)}
-/>
-```
-
----
-
-## Utilidades de validación de vídeo
-
-```typescript
-import { validateVideoUrl, validateVideoBatch, clearValidationCache } from 'webs-sdk';
-import { useValidateVideoOnMount, useLazyVideoValidation } from 'webs-sdk';
-
-// Función pura (sin React)
-const state = await validateVideoUrl('https://stream.example.com/live.m3u8');
-// 'valid' | 'invalid' | 'unknown'
-
-// Batch con concurrencia 3
-const results = await validateVideoBatch([url1, url2, url3]);
-
-// React: validar al montar (evita renderizar streams rotos)
-const { isValid, isInvalid, isValidating } = useValidateVideoOnMount(videoUrl);
-
-// React: validación manual
-const { validate, isValid, isInvalid } = useLazyVideoValidation();
-await validate(videoUrl);
-```
-
-Soporta HLS, DASH, MP4. Cache en memoria con TTL de 5 minutos.
-
----
-
-## Estructura del proyecto
-
-```
-src/
-├── config.ts              # Configuración central (URLs, endpoints, constantes)
-├── index.ts               # Barrel export principal
-├── libraries/
-│   ├── networking.ts      # HTTP + events
-│   ├── auth.ts            # Autenticación, login, baja
-│   ├── session.ts         # Sesiones y dispositivo
-│   ├── storage.ts         # LocalStorage + compresión de imágenes
-│   ├── utils.ts           # Utilidades generales
-│   ├── andromeda.ts       # Metadata y config de portales
-│   ├── corp_auth.ts       # Auth corporativa (JWT)
-│   ├── user.ts            # Datos de usuario
-│   ├── mixpanel.ts        # Analytics
-│   ├── audio.ts           # Text-to-speech
-│   ├── calypso.ts         # Event tracking interno
-│   ├── legal.ts           # Textos legales
-│   ├── content.ts         # Contenido dinámico + colecciones por tags
-│   ├── cdn.ts             # CDN Proxy (Edge Runtime compatible)
-│   └── googleAnalytics.ts # GA4 con carga diferida por consentimiento
-├── utils/
-│   ├── videoValidation.ts  # Validación de URLs de streaming
-│   ├── useVideoValidation.ts # React hooks para validación
-│   └── timeUtils.ts        # getTimeAgo — tiempo relativo i18n
-└── components/
-    ├── AvatarAI.tsx
-    ├── CreativeFaceSwap.tsx
-    ├── Wallpapers.tsx
-    ├── WallpapersName.tsx
-    ├── Ringtone.tsx
-    ├── MemeGenerator.tsx
-    ├── Quiz.tsx
-    ├── Stickers.tsx
-    ├── VideoPlayer.tsx
-    ├── ARFilters/
-    ├── SpinningWheel/
-    ├── CookieConsent/
-    └── esports/
-        ├── news/
-        ├── videos/
-        └── live/
-```
-
-## Desarrollo
-
-```bash
-npm install
-npm run build          # tsc → dist/
-npm run build:watch    # watch mode
-npm run lint
-```
-
-## Publicación
-
-```bash
-# Incluir [ROAD-361723] en el commit para auto-publish en CI
-git commit -m "feat: descripción [ROAD-361723]"
-git push
-```
-
-Tras publicar, actualizar en los portales:
-```bash
-npm install webs-sdk@<nueva-version>
-```
-
-**Nota importante — `index.js` raíz:** es el barrel CommonJS mantenido manualmente. Cada export nuevo en `src/index.ts` debe añadirse también en `index.js`:
-```js
-const { nuevaFuncion } = require('./dist/index.js');
-module.exports.nuevaFuncion = nuevaFuncion;
-```
+# webs-sdk
+
+SDK interno npm para portales Nexum. Encapsula toda la lógica común: autenticación, sesiones, comunicación con la API, tracking, internacionalización y componentes React reutilizables.
+
+**Versión actual:** 0.18.9
+
+## Instalación
+
+```bash
+npm install webs-sdk
+```
+
+## Uso básico
+
+```typescript
+import WebsSDK from 'webs-sdk';
+
+// Inicializar sesión
+await WebsSDK.Session.init();
+
+// Petición HTTP
+const data = await WebsSDK.Networking.request('/api/endpoint', { param: 'value' });
+
+// Almacenamiento local
+WebsSDK.Storage.set('key', 'value');
+const value = WebsSDK.Storage.get('key');
+```
+
+## Librerías disponibles
+
+### Networking
+
+```typescript
+// Petición HTTP (inyecta sessionData automáticamente)
+await WebsSDK.Networking.request(url, data);
+
+// Eventos de tracking
+await WebsSDK.Networking.sendEvent('action', 'button_click', { button_id: 'submit' });
+
+// Suscripciones
+await WebsSDK.Networking.createSubscription(subscriptionData);
+const { success, subscription_active } = await WebsSDK.Networking.checkSubscription();
+```
+
+### Storage
+
+```typescript
+WebsSDK.Storage.set('key', 'value');
+const value = WebsSDK.Storage.get('key');
+
+// Compresión de imágenes (0.8 ratio, 1024px max)
+const compressed = await WebsSDK.Storage.compressImage(imageFile, 2); // 2MB max
+
+// Creaciones (imágenes generadas por el usuario)
+await WebsSDK.Storage.handleDownloadImageToCreations(base64, 'id', metadata);
+const creations = await WebsSDK.Storage.getCreations();
+await WebsSDK.Storage.deleteCreation('id');
+```
+
+### Session
+
+```typescript
+await WebsSDK.Session.init();
+
+const sessionData = WebsSDK.Session.getSessionData();
+const userId = WebsSDK.Session.getUserID();
+const lang = WebsSDK.Session.getDeviceLanguage();
+const isSubscribed = WebsSDK.Session.getIsSubscribed();
+```
+
+### Utils
+
+```typescript
+const id = WebsSDK.Utils.generateId();
+const isValidEmail = WebsSDK.Utils.isValidEmail('user@example.com');
+const isMobile = WebsSDK.Utils.isMobile();
+const deviceInfo = WebsSDK.Utils.getDeviceInfo();
+const truncated = WebsSDK.Utils.truncateText('Long text...', 10);
+```
+
+### MixPanel
+
+```typescript
+await WebsSDK.MixPanel.initialize(token, false, false, false);
+await WebsSDK.MixPanel.trackEvent('page_view', { page: 'home' });
+await WebsSDK.MixPanel.identifyUser('user_123');
+await WebsSDK.MixPanel.setUserProperties({ plan: 'premium' });
+```
+
+### Clarity — Microsoft Clarity
+
+Heatmaps y session recordings. El `projectId` de cada portal viaja en su `/config`
+(`product_config.tracking_id`). Cómo se entrega a Clarity depende del entorno:
+
+- **App móvil**: arranca solo. `Session.init()` → `Networking.executeInit()` lee
+  `product_config.tracking_id` e inicializa Clarity, identificando con `getUserID()`.
+- **Portal web**: `executeInit()` no corre (el config llega por el proxy /
+  `WebsiteProvider` del portal). El portal debe inicializar Clarity con un
+  `ClarityInitializer` (espejo del `MixpanelInitializer`) que tome el `tracking_id`
+  del `WebsiteProvider` y llame a `initialize()`.
+
+```typescript
+// Init con opciones
+await WebsSDK.Clarity.initialize(projectId, {
+  devMode: false,        // true → omite la carga (desarrollo)
+  requireConsent: true,  // true → espera TRACKING_PERMISSION==='granted' (con banner)
+                         // false → arranca sin esperar consentimiento (sin banner)
+});
+
+// Consentimiento de cookies (desde el banner)
+await WebsSDK.Clarity.updateConsent(true);          // false para rechazar
+
+// Identify: automático en Session.init() con getUserID(); manual opcional
+WebsSDK.Clarity.identify(userId);
+WebsSDK.Clarity.setTag('plan', 'premium');
+WebsSDK.Clarity.trackEvent('checkout_started');
+```
+
+- **Consentimiento:** con `requireConsent: true` respeta `TRACKING_PERMISSION`
+  (igual que GA4): si no está `'granted'`, no carga; queda pendiente y arranca al
+  llamar `updateConsent(true)`. Con `requireConsent: false` (tenants sin banner)
+  arranca directo.
+- **Identify diferido:** no importa el orden de init vs `Session.init()` ni cuándo
+  llegue el consentimiento — el `identify(getUserID())` se aplica en cuanto Clarity
+  está listo.
+- **Dev mode:** con `devMode: true` no carga (no ensucia Clarity con sesiones de
+  desarrollo). El auto-init móvil usa `DEBUG_MODE` para esto.
+
+### AuthManager
+
+```typescript
+// Login estándar
+await WebsSDK.AuthManager.authUser({ login, password, website_id });
+
+// Login sin password (MSISDN)
+await WebsSDK.AuthManager.authOnlyUser({ login, website_id });
+
+// Login con OTP
+await WebsSDK.AuthManager.authOnlyUserOTP({ login, website_id, pincode });
+
+// Registro
+await WebsSDK.AuthManager.createUser({ login, password, website_id });
+
+// Auto-login post-pago (usado en el proxy de next_template)
+await WebsSDK.AuthManager.auto_login(cfg_sessionid, websiteData, requestUrl);
+
+// Baja/cancelación
+await WebsSDK.AuthManager.unsubscribeUser({ user_id, callback_url?, org? });
+
+// Gestión de perfil
+await WebsSDK.AuthManager.setUserMetadata(params);
+await WebsSDK.AuthManager.uploadProfilePhoto(params); // JPG/PNG/WEBP, max 5MB
+await WebsSDK.AuthManager.changePassword(params);
+```
+
+### Andromeda — Portales
+
+```typescript
+// Metadata del portal (optimizado con cookie websiteDataFlag)
+await WebsSDK.Andromeda.getWebsiteMetadatabyHostname('portal.com');
+
+// Configuración del producto (langs, login_type, logo, favicon, theme)
+await WebsSDK.Andromeda.getWebsiteConfig('portal-corp-web');
+```
+
+### ContentManager
+
+```typescript
+// Contenido por preset
+await WebsSDK.ContentManager.getContentByPreset('homepage', { lang: 'es' });
+
+// Colección filtrada por tags
+await WebsSDK.ContentManager.getCollection(['tag1', 'tag2'], 'es', false);
+```
+
+### User
+
+```typescript
+await WebsSDK.User.checkSession(token);            // Valida token (usado en middleware)
+await WebsSDK.User.getUserData(user_id, website_id);
+await WebsSDK.User.getCredits(user_id, website_id);
+```
+
+### CorporateAuthManager
+
+```typescript
+// Server-side (middleware Next.js)
+const result = await WebsSDK.CorporateAuthManager.validateCorporateAuthServerSide(request);
+if (!result.authenticated) return result.redirectResponse;
+
+// Client-side
+await WebsSDK.CorporateAuthManager.checkCorporateLogin();
+await WebsSDK.CorporateAuthManager.validateUser(autoRedirect?);
+await WebsSDK.CorporateAuthManager.login(returnTo?);
+await WebsSDK.CorporateAuthManager.logout(redirectTo?);
+await WebsSDK.CorporateAuthManager.isAdmin(userData?);
+```
+
+### Legal
+
+```typescript
+await WebsSDK.Legal.getLegalText('tos' | 'privacy' | 'faq', web_id, lang);
+```
+
+### Namespace `pre` — Pre-producción
+
+```typescript
+// Lazy-loaded, apunta a bc1742-pre.gways.org
+await WebsSDK.pre.AuthManager.authUser(params);
+await WebsSDK.pre.Andromeda.getWebsiteMetadatabyHostname(hostname);
+```
+
+---
+
+## Componentes React
+
+### CookieConsent — Banner GDPR
+
+```typescript
+import { CookieConsent, getCookieConsentTexts } from 'webs-sdk';
+import type { CookieConsentProps, CookieConsentTheme, CookieConsentPreferences } from 'webs-sdk';
+
+<CookieConsent
+  locale="es"                        // en | es | fr | nl | ar | de | fi | ro | tr
+  privacyPolicyUrl="/privacy"
+  theme={{
+    backgroundColor: '#1a1a2e',
+    accentColor: '#6c63ff',           // aplica a botón Accept, borde Reject, links y glow
+    acceptButtonBg: 'linear-gradient(90deg, #6c63ff, #a855f7)', // soporta gradients CSS
+    textColor: '#ffffff',
+  }}
+  onAccept={() => updateGAConsent('granted')}
+  onReject={() => updateGAConsent('denied')}
+  onSaveSettings={(prefs: CookieConsentPreferences) => handlePrefs(prefs)}
+/>
+```
+
+**Storage:**
+- Cookie `cookieConsent`: `accepted | rejected | custom` (1 año)
+- `localStorage.TRACKING_PERMISSION`: `granted | denied`
+- `localStorage.FUNCTIONAL_PERMISSION`: `granted | denied`
+
+### Google Analytics — GA4
+
+```typescript
+import { initGoogleAnalytics, updateGAConsent, trackGAEvent, trackGAPageView, isGALoaded } from 'webs-sdk';
+
+// Registra el GA ID. Carga el script SOLO si hay consentimiento previo.
+await initGoogleAnalytics('G-XXXXXXXXXX', { sendPageView: true, debug: false });
+
+// Llamar tras decisión del usuario en CookieConsent
+updateGAConsent('granted');  // carga GA si había pendingTrackingId
+updateGAConsent('denied');   // GA nunca se carga
+
+// Tracking
+trackGAEvent('purchase', { value: 9.99, currency: 'EUR' });
+trackGAPageView('/home', 'Inicio');
+isGALoaded(); // boolean
+```
+
+> **GDPR estricto:** GA no usa Consent Mode v2. Si no hay consentimiento, el script `gtag.js` nunca se inyecta en el DOM.
+
+### CDN Proxy
+
+```typescript
+import { handleCDNRequest } from 'webs-sdk';
+import type { CDNOptions } from 'webs-sdk';
+
+// Usar en un route handler de Next.js (compatible con Edge Runtime)
+async function handleCDNRequest(
+  pathname: string,        // '/cdn/apariencias/33702/image.png'
+  options?: {
+    cdnBaseUrl?: string;   // Default: 'https://dy822md8ge77v.cloudfront.net'
+    cacheSeconds?: number; // Default: 300 (5 min)
+  }
+): Promise<Response | null>  // null si pathname no empieza por /cdn/
+```
+
+### Componentes "For You" — Creación de contenido AI
+
+```typescript
+import {
+  AvatarAI, AvatarAIPage, AvatarAIForYouCard,
+  CreativeFaceSwap, CreativeFaceSwapPage, CreativeFaceSwapForYouCard,
+  MemeGenerator, MemeGeneratorPage, MemeGeneratorForYouCard,
+  WallpapersName, WallpapersNamePage, WallpapersNameForYouCard,
+  Wallpapers,
+  Ringtone,
+} from 'webs-sdk';
+```
+
+Todos aceptan `websiteId?: string` para tracking multi-portal.
+
+### ARFilters — Filtros AR con DeepAR
+
+```typescript
+import { ARFilters, ARFiltersForYouCard } from 'webs-sdk';
+import type { DeepARProps, DeepARFilter, DeepARTexts } from 'webs-sdk';
+
+<ARFilters
+  licenseKey="deepar-license-key"
+  websiteId="portal-web-id"
+  apiBaseUrl="https://api.fluver-ai.com"
+  downloadProxyUrl="/cdn"            // Proxy CORS para descarga de efectos
+  filterTag="ar-filters-tag"         // Obtiene filtros del CMS por tag
+  // O bien: filters={[{ file: 'beauty', thumbUrl: '/thumb.jpg' }]}
+  locale="es"
+  texts={getARFiltersTexts('es')}    // requerido
+  onPhotoTaken={(url) => share(url)}
+  onVideoRecorded={(url) => share(url)}
+/>
+```
+
+Soporta fullscreen en mobile (vendor-prefixed API para iOS Safari).
+
+### SpinningWheel — Ruleta
+
+```typescript
+import { SpinningWheel, wheelThemes } from 'webs-sdk';
+
+// Temas: vodacom | totalgym | womantoday | afristream | efc
+<SpinningWheel
+  userId={userId}
+  websiteId={websiteId}
+  theme="vodacom"
+  onResult={(segment) => handleWin(segment)}
+  canSpin={true}
+  alreadySpunToday={false}
+/>
+```
+
+### Quiz y Stickers
+
+```typescript
+import { Quiz, Stickers } from 'webs-sdk';
+```
+
+### Esports — Noticias, Vídeos y Partidas en Directo
+
+```typescript
+import { EsportsNews, EsportsVideos, EsportsLive } from 'webs-sdk';
+```
+
+#### EsportsNews
+
+```typescript
+<EsportsNews
+  config={{
+    key: 'api-key',
+    contents: [{ preset: 'esports_news', apiProviderId: 'id', category: [], tags: [], limit: 10 }]
+  }}
+  language="es"
+  onNewsClick={(item) => router.push(`/news/${item.id}`)}
+  theme={theme}                    // CSS classes para container, cards, badges, etc.
+  categoryStyles={{ gaming: { badge: 'bg-blue-500', badgeText: 'text-white' } }}
+  // Modo detalle (renderiza EsportsNewsDetail):
+  newsId="article-id"
+  newsData={item}                  // opcional si ya tienes los datos
+  onBack={() => router.back()}
+/>
+```
+
+#### EsportsVideos
+
+```typescript
+<EsportsVideos
+  config={{ key: 'api-key', contents: [...] }}
+  language="es"
+  onVideoClick={(item) => openPlayer(item.video_url)}
+  theme={theme}                    // incluye clases para duration overlay
+/>
+```
+
+#### EsportsLive
+
+```typescript
+<EsportsLive
+  language="es"
+  timezone="Europe/Madrid"
+  onLiveClick={(item) => openStream(item.streamUrl)}
+  onMatchClick={(match) => openMatchDetail(match)}
+  onGameClick={(gameId) => filterByGame(gameId)}
+  website_id="portal-web-id"
+  theme={theme}
+  // Modo detalle de partida:
+  matchId="serie-id"
+  matchData={calendarMatch}
+  onBack={() => setMatchId(null)}
+/>
+```
+
+---
+
+## Utilidades de validación de vídeo
+
+```typescript
+import { validateVideoUrl, validateVideoBatch, clearValidationCache } from 'webs-sdk';
+import { useValidateVideoOnMount, useLazyVideoValidation } from 'webs-sdk';
+
+// Función pura (sin React)
+const state = await validateVideoUrl('https://stream.example.com/live.m3u8');
+// 'valid' | 'invalid' | 'unknown'
+
+// Batch con concurrencia 3
+const results = await validateVideoBatch([url1, url2, url3]);
+
+// React: validar al montar (evita renderizar streams rotos)
+const { isValid, isInvalid, isValidating } = useValidateVideoOnMount(videoUrl);
+
+// React: validación manual
+const { validate, isValid, isInvalid } = useLazyVideoValidation();
+await validate(videoUrl);
+```
+
+Soporta HLS, DASH, MP4. Cache en memoria con TTL de 5 minutos.
+
+---
+
+## Estructura del proyecto
+
+```
+src/
+├── config.ts              # Configuración central (URLs, endpoints, constantes)
+├── index.ts               # Barrel export principal
+├── libraries/
+│   ├── networking.ts      # HTTP + events
+│   ├── auth.ts            # Autenticación, login, baja
+│   ├── session.ts         # Sesiones y dispositivo
+│   ├── storage.ts         # LocalStorage + compresión de imágenes
+│   ├── utils.ts           # Utilidades generales
+│   ├── andromeda.ts       # Metadata y config de portales
+│   ├── corp_auth.ts       # Auth corporativa (JWT)
+│   ├── user.ts            # Datos de usuario
+│   ├── mixpanel.ts        # Analytics
+│   ├── audio.ts           # Text-to-speech
+│   ├── calypso.ts         # Event tracking interno
+│   ├── legal.ts           # Textos legales
+│   ├── content.ts         # Contenido dinámico + colecciones por tags
+│   ├── cdn.ts             # CDN Proxy (Edge Runtime compatible)
+│   └── googleAnalytics.ts # GA4 con carga diferida por consentimiento
+├── utils/
+│   ├── videoValidation.ts  # Validación de URLs de streaming
+│   ├── useVideoValidation.ts # React hooks para validación
+│   └── timeUtils.ts        # getTimeAgo — tiempo relativo i18n
+└── components/
+    ├── AvatarAI.tsx
+    ├── CreativeFaceSwap.tsx
+    ├── Wallpapers.tsx
+    ├── WallpapersName.tsx
+    ├── Ringtone.tsx
+    ├── MemeGenerator.tsx
+    ├── Quiz.tsx
+    ├── Stickers.tsx
+    ├── VideoPlayer.tsx
+    ├── ARFilters/
+    ├── SpinningWheel/
+    ├── CookieConsent/
+    └── esports/
+        ├── news/
+        ├── videos/
+        └── live/
+```
+
+## Desarrollo
+
+```bash
+npm install
+npm run build          # tsc → dist/
+npm run build:watch    # watch mode
+npm run lint
+```
+
+## Publicación
+
+```bash
+# Incluir [ROAD-361723] en el commit para auto-publish en CI
+git commit -m "feat: descripción [ROAD-361723]"
+git push
+```
+
+Tras publicar, actualizar en los portales:
+```bash
+npm install webs-sdk@<nueva-version>
+```
+
+**Nota importante — `index.js` raíz:** es el barrel CommonJS mantenido manualmente. Cada export nuevo en `src/index.ts` debe añadirse también en `index.js`:
+```js
+const { nuevaFuncion } = require('./dist/index.js');
+module.exports.nuevaFuncion = nuevaFuncion;
+```