webs-sdk 0.19.64 → 0.19.65

package/docs/EXTERNAL_SDK_GUIDE.md

@@ -0,0 +1,1340 @@
+# webs-sdk — External Developer Guide
+
+> **Version:** 0.18.35  
+> **Companion document:** [next_template External Guide](../../next_template/docs/EXTERNAL_TEMPLATE_GUIDE.md)
+
+---
+
+## Table of Contents
+
+1. [Introduction](#1-introduction)
+2. [Installation & Requirements](#2-installation--requirements)
+3. [SDK Architecture](#3-sdk-architecture)
+4. [Core Libraries](#4-core-libraries)
+   - 4.1 [AuthManager](#41-authmanager)
+   - 4.2 [Andromeda — Portal Metadata](#42-andromeda--portal-metadata)
+   - 4.3 [User](#43-user)
+   - 4.4 [Networking](#44-networking)
+   - 4.5 [Calypso — Event Tracking](#45-calypso--event-tracking)
+   - 4.6 [Legal](#46-legal)
+   - 4.7 [Session](#47-session)
+   - 4.8 [Storage](#48-storage)
+   - 4.9 [Other Libraries](#49-other-libraries)
+5. [Google Analytics](#5-google-analytics)
+6. [CookieConsent Component](#6-cookieconsent-component)
+7. [CDN Proxy](#7-cdn-proxy)
+8. [React Content Components](#8-react-content-components)
+9. [Esports Components](#9-esports-components)
+10. [UI Component Library](#10-ui-component-library)
+11. [Video Validation Utilities](#11-video-validation-utilities)
+12. [TypeScript Types Reference](#12-typescript-types-reference)
+13. [Production vs Pre-production](#13-production-vs-pre-production)
+14. [Error Patterns & Security](#14-error-patterns--security)
+
+---
+
+## 1. Introduction
+
+`webs-sdk` is an internal npm package that centralises all shared functionality across Nexum content portals. It provides:
+
+- **Authentication** — login, registration, auto-login from payment callbacks, subscription cancellation
+- **Portal configuration** — per-hostname metadata resolution via the Andromeda backend
+- **Analytics** — GDPR-compliant Google Analytics 4 integration, internal Calypso tracking, Mixpanel
+- **React components** — GDPR consent banner, AI content generation widgets, esports modules, gamification
+- **Utilities** — CDN proxy, video validation, localStorage wrapper, image compression
+
+**How it fits with next_template:**  
+The SDK runs exclusively on the **server side** (Next.js middleware and API routes) via the BFF (Backend For Frontend) pattern. Client-side React components in `next_template` access SDK functionality through Zustand stores and internal API routes — they never import `WebsSDK` directly. See the [next_template guide](../../next_template/docs/EXTERNAL_TEMPLATE_GUIDE.md) for the full integration pattern.
+
+---
+
+## 2. Installation & Requirements
+
+```bash
+npm install webs-sdk
+```
+
+> This is a private npm package. You need access to the company npm registry to install it.
+
+**Peer dependencies:**
+
+| Package | Version |
+|---|---|
+| `react` | `^18.0.0 \|\| ^19.0.0` |
+| `react-dom` | `^18.0.0 \|\| ^19.0.0` |
+| `lucide-react` | `>=1.14.0` |
+
+**Import pattern:**
+
+```typescript
+// Default import — the main SDK singleton object
+import WebsSDK from 'webs-sdk';
+
+// Named imports — individual components and utilities
+import { CookieConsent, initGoogleAnalytics, handleCDNRequest } from 'webs-sdk';
+
+// UI sub-package
+import { Button, Input, Dialog } from 'webs-sdk/ui';
+```
+
+> **Warning:** Do **not** import `WebsSDK` (the default export) inside `'use client'` components. It is designed for server-side use (API routes, middleware). Access SDK data on the client through Zustand stores and fetch calls to your own API routes.
+
+---
+
+## 3. SDK Architecture
+
+```
+WebsSDK (singleton object)
+├── Networking          — HTTP layer, /config init, event queue
+├── AuthManager         — Authentication, auto-login, unsubscribe
+├── Andromeda           — Portal metadata by hostname
+├── User                — Session validation, subscription check
+├── Calypso             — Internal event tracking
+├── Legal               — Legal document retrieval
+├── Session             — Session lifecycle
+├── Storage             — localStorage wrapper
+├── ContentManager      — Content fetching by preset / tag collection
+├── MixPanel            — External analytics
+├── Audio               — Text-to-speech
+├── I18nManager         — Internationalisation (placeholder)
+├── Utils               — General utilities
+├── Config              — Mutable configuration object
+└── .pre (lazy)         — Pre-production instances of the above
+    ├── AuthManager     → bc1742-pre.gways.org
+    ├── User
+    ├── Andromeda
+    └── Calypso
+
+Standalone exports (not on the WebsSDK object):
+├── CookieConsent       — React component
+├── initGoogleAnalytics — GA4 with consent gate
+├── handleCDNRequest    — CloudFront proxy (Edge-compatible)
+└── validateVideoUrl    — Video URL validation
+```
+
+**Singleton pattern:** All library classes are instantiated once at module load. Do not instantiate them yourself — always use `WebsSDK.<Library>`.
+
+**Mutable config:** `WebsSDK.Config` starts with static defaults. `Networking.executeInit()` fetches `/config` from the backend and overwrites endpoint URLs, events, and feature flags at runtime. If you call SDK methods before `executeInit()` runs, they will use the static defaults.
+
+**Pre-production namespace:** `WebsSDK.pre` is lazy-loaded on first access. In `next_template`, all API routes use `WebsSDK.pre.*` to target the pre-production backend (`bc1742-pre.gways.org`).
+
+---
+
+## 4. Core Libraries
+
+### 4.1 AuthManager
+
+**File:** `src/libraries/auth.ts`  
+**Accessed as:** `WebsSDK.AuthManager` (production) or `WebsSDK.pre.AuthManager` (pre-production)
+
+#### `authUser(params)` — Standard login
+
+```typescript
+const result = await WebsSDK.pre.AuthManager.authUser({
+  login: 'user@example.com',
+  password: 'secret123',
+  website_id: 'myportal-web',
+});
+```
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `login` | `string` | Yes | Email or username |
+| `password` | `string` | Yes | Plain text password |
+| `website_id` | `string` | Yes | Portal identifier from Andromeda |
+
+**Returns:** `AuthResult`
+
+```typescript
+// Success
+{ status: 'success', data: { success: 1, us_id, us_login, session_id, metadata, subscription_data, ... } }
+
+// Error
+{ status: 'error', errorKey: 'invalidCredentials', error: 'Authentication error' }
+```
+
+**Error keys:**
+
+| `errorKey` | Meaning |
+|---|---|
+| `userNotFound` | No user with that login |
+| `invalidCredentials` | Wrong password |
+| `accountDisabled` | Account is disabled |
+| `userNotActive` | Account not yet activated |
+| `authFailed` | Generic authentication failure |
+| `serverError` | Backend unreachable |
+| `invalidData` | Missing required fields |
+
+---
+
+#### `authOnlyUser(params)` — Login without password (MSISDN)
+
+Used when the login type is phone-number-based (no password required).
+
+```typescript
+const result = await WebsSDK.pre.AuthManager.authOnlyUser({
+  login: '+34612345678',
+  website_id: 'myportal-web',
+  login_only_user: 'msisdn',
+});
+```
+
+---
+
+#### `authOnlyUserOTP(params)` — Login with OTP
+
+Validates the one-time PIN sent by SMS.
+
+```typescript
+const result = await WebsSDK.pre.AuthManager.authOnlyUserOTP({
+  login: '+34612345678',
+  website_id: 'myportal-web',
+  pincode: '123456',
+});
+```
+
+---
+
+#### `createUser(params)` — Registration
+
+```typescript
+const result = await WebsSDK.pre.AuthManager.createUser({
+  login: 'user@example.com',
+  password: 'secret123',
+  website_id: 'myportal-web',
+});
+```
+
+**Error keys:** `userAlreadyExists`, `signupFailed`, `serverError`
+
+---
+
+#### `auto_login(cfg_sessionid, websiteData, requestUrl)` — Post-payment auto-login
+
+> **Critical:** This method is called exclusively inside the Next.js middleware (`proxy.ts`) when the user arrives from a payment gateway with `?cfg_sessionid=` in the URL.
+
+```typescript
+const result = await WebsSDK.AuthManager.auto_login(
+  cfg_sessionid,          // String from payment gateway URL param
+  websiteData,            // Object from Andromeda.getWebsiteMetadatabyHostname()
+  url.toString()          // Full request URL (used to strip the param)
+);
+// result.status: 'success' | 'error'
+// result.redirectUrl: URL without cfg_sessionid
+// result.cookies: Array of CookieToSet — apply to the NextResponse
+```
+
+**Flow:**
+1. Calls `getThankyouPageMetadata(cfg_sessionid)` → extracts user credentials from the payment session
+2. Calls `authUser()` with those credentials
+3. Returns `cookies` array containing `autoLoginFlag` (TTL: 10 seconds)
+4. Sets `wip: true` on the user data if the session is recent (< 1 hour) and no active subscription yet
+
+The middleware strips `cfg_sessionid` from the URL and redirects. The client-side `AuthGuard` detects `autoLoginFlag` and hydrates the auth store.
+
+---
+
+#### `unsubscribeUser(params)` — Cancel subscription
+
+```typescript
+const result = await WebsSDK.pre.AuthManager.unsubscribeUser({
+  user_id: '12345',
+  callback_url: 'https://yourportal.com/unsubscribe-callback', // optional
+  org: 'myorg',                                                 // optional
+});
+```
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `user_id` | `string` | Yes | User ID |
+| `callback_url` | `string` | No | Notification URL after cancellation |
+| `org` | `string` | No | Organisation identifier |
+
+**Error keys:** `unsubscribeFailed`, `serverError`, `invalidData`  
+**Note:** Error key `114` means "no active subscriptions found".
+
+---
+
+#### `setUserMetadata(params)` — Update profile metadata
+
+```typescript
+const result = await WebsSDK.pre.AuthManager.setUserMetadata({
+  login: 'user@example.com',
+  password: 'secret123',     // optional
+  website_id: 'myportal-web',
+  display_name: 'John Doe',  // any metadata fields
+});
+```
+
+---
+
+#### `uploadProfilePhoto(params)` — Upload avatar
+
+```typescript
+const result = await WebsSDK.pre.AuthManager.uploadProfilePhoto({
+  login: 'user@example.com',
+  website_id: 'myportal-web',
+  resource: file,  // File object, max 5 MB, JPG/PNG/WEBP only
+});
+// result.profile_photo — URL of the uploaded photo
+```
+
+**Validation:** max 5 MB, accepted types: `image/jpeg`, `image/jpg`, `image/png`, `image/webp`  
+**Error keys:** `invalidFormat`, `fileTooLarge`, `uploadFailed`
+
+---
+
+#### `changePassword(params)`
+
+```typescript
+await WebsSDK.pre.AuthManager.changePassword({
+  login: 'user@example.com',
+  website_id: 'myportal-web',
+  new_pass: 'newSecret123',
+  repeat_new_pass: 'newSecret123',
+});
+```
+
+---
+
+#### `changeCredentials(params)`
+
+Changes both login and password in one call.
+
+```typescript
+await WebsSDK.pre.AuthManager.changeCredentials({
+  login: 'old@example.com',
+  password: 'oldSecret',
+  website_id: 'myportal-web',
+  new_login: 'new@example.com',
+  new_pass: 'newSecret123',
+  repeat_new_pass: 'newSecret123',
+});
+```
+
+---
+
+#### `getThankyouPageMetadata(cfg_sessionid)`
+
+Retrieves user credentials from a payment session token. Called internally by `auto_login`. Can be used directly on the thank-you page.
+
+```typescript
+const result = await WebsSDK.AuthManager.getThankyouPageMetadata(cfg_sessionid);
+// result.data: { user: { login, password }, website: { lang }, channel: { id, mccmnc } }
+```
+
+---
+
+#### `logout()` / `hasActiveSession()`
+
+```typescript
+WebsSDK.AuthManager.logout();             // Clears local session markers
+WebsSDK.AuthManager.hasActiveSession();   // Returns boolean
+```
+
+> In `next_template`, session teardown also requires a `POST /api/auth/logout` call to clear the `userSession` httpOnly cookie.
+
+---
+
+### 4.2 Andromeda — Portal Metadata
+
+**File:** `src/libraries/andromeda.ts`  
+**Accessed as:** `WebsSDK.Andromeda` (production) or `WebsSDK.pre.Andromeda`
+
+This library resolves a domain hostname into portal configuration. It is the entry point for the multi-tenant system.
+
+#### `getWebsiteMetadatabyHostname(hostname, existingCookie?)`
+
+```typescript
+const result = await WebsSDK.Andromeda.getWebsiteMetadatabyHostname('musikgen.com');
+// result.status: 'success' | 'error'
+// result.websiteData: WebsiteData object
+// result.cookies: Array<CookieToSet> — set these on the middleware response
+```
+
+The method checks for a cached `websiteDataFlag` cookie first. If the cookie exists and matches the hostname, it skips the backend fetch. Otherwise it fetches from the backend and returns a `cookies` array with a new `websiteDataFlag` cookie (TTL: 1 hour).
+
+**`WebsiteData` structure:**
+
+```typescript
+interface WebsiteData {
+  web_id: string;                // Unique portal identifier — e.g. 'musikgen-corp-web'
+  web_pais: string;              // Country code
+  web_estado: string;            // Portal status in Argo
+  web_collection: string;        // Andromeda collection
+  web_version: number;           // Portal version
+  web_url: string;               // Canonical URL
+  web_analytics_id: string | null; // GA4 tracking ID (G-XXXXXXXX)
+  hostname?: string;             // Resolved hostname (added by SDK)
+  custom_operators: string | null;
+  web_category: string;
+  web_andro_template: string | null;
+}
+```
+
+---
+
+#### `getWebsiteConfig(web_id, merchantId?)`
+
+Returns the full product and feature configuration for a portal.
+
+```typescript
+const result = await WebsSDK.Andromeda.getWebsiteConfig('musikgen-corp-web');
+// result.data: { product_config, features_config }
+```
+
+**`product_config` structure:**
+
+```typescript
+interface ProductConfig {
+  website_id: string;
+  title: string;               // Portal display name
+  langs: string[];             // Enabled languages — e.g. ['en', 'es', 'fr']
+  default_lang: string;        // Default language — e.g. 'en'
+  login_type: string;          // Login method — 'email', 'msisdn', etc.
+  login_only_user: string | boolean;
+  on_premium_redirect: string; // Redirect path after subscription
+  logo: string;                // Logo URL
+  favicon: string;             // Favicon URL
+  footer: string[];            // Footer link identifiers
+  account: { manage_subscription: boolean };
+  skip_signup: boolean;
+  shortcuts_dropdownmenu: string[];
+  navigation_session?: boolean;// If true, middleware validates session on every request
+  check_thankyou_metadata_default_lang?: boolean;
+  // Cookie banner colours (optional — used by CookieConsentWrapper)
+  cookieBannerBgColor?: string;
+  cookieBannerTextColor?: string;
+  cookieBannerAccentColor?: string;
+  privacyPolicyUrl?: string;
+}
+```
+
+**`features_config` structure:**
+
+```typescript
+interface FeaturesConfig {
+  limits: {
+    credit_period: string;
+    credit_limit: {
+      subscribed_user: any;
+      free_user: any;
+    };
+  };
+  features_disabled: string[];
+  file_sizes: { image: number; pdf: number; video_min: number };
+}
+```
+
+---
+
+### 4.3 User
+
+**File:** `src/libraries/user.ts`  
+**Accessed as:** `WebsSDK.User` (production) or `WebsSDK.pre.User`
+
+#### `checkSession(params)` — Validate session token
+
+Used by the middleware when `product_config.navigation_session === true`.
+
+```typescript
+const result = await WebsSDK.User.checkSession({
+  user_id: '12345',
+  session: 'session-token-from-cookie',
+});
+// result.data.valid: boolean
+```
+
+If `valid === false`, the middleware clears the `userSession` cookie and redirects to `/login`.
+
+---
+
+#### `checkUserSubscription(params)`
+
+```typescript
+const result = await WebsSDK.User.checkUserSubscription({ userId: '12345' });
+```
+
+---
+
+#### `checkUserLinkedStatus(params)`
+
+```typescript
+const result = await WebsSDK.User.checkUserLinkedStatus({ userId: '12345' });
+```
+
+---
+
+#### `getUserCredits(params)`
+
+```typescript
+const result = await WebsSDK.User.getUserCredits({
+  userId: '12345',
+  website_id: 'myportal-web',
+});
+```
+
+---
+
+#### `getAlias(params)`
+
+```typescript
+const result = await WebsSDK.User.getAlias({ userId: '12345' });
+```
+
+---
+
+### 4.4 Networking
+
+**File:** `src/libraries/networking.ts`  
+**Accessed as:** `WebsSDK.Networking`
+
+The HTTP layer used internally by all other libraries. All requests are `POST` with JSON body.
+
+#### `request(url, data)` — Generic HTTP call
+
+```typescript
+const result = await WebsSDK.Networking.request(
+  'https://bc1742.gways.org/user/get',
+  { user_id: '12345' }
+);
+```
+
+**Automatic behaviour:**
+- Injects session data from the `userSession` cookie (via `next/headers` when in request scope)
+- Adds `x-nexum-session-id` header if a session token is found
+- Supports `FormData` (sets `multipart/form-data`)
+- Logs performance timing
+
+---
+
+#### `executeInit()` — Bootstrap SDK config
+
+Fetches `/config` from the backend and mutates `WebsSDK.Config` with live endpoints, event identifiers, paywall data, and image compression settings.
+
+```typescript
+await WebsSDK.Networking.executeInit();
+```
+
+This is called internally by `Session.init()`. You only need to call it manually if you are not using the session init flow.
+
+---
+
+#### `sendEvent(eventType, eventKeyword, eventData?, forceSend?)`
+
+```typescript
+await WebsSDK.Networking.sendEvent(
+  'action',           // eventType: 'other' | 'action' | 'screen'
+  'button_click',     // eventKeyword: must match a key in config.EVENTS
+  { variant: 'cta' }, // optional payload
+  false               // forceSend: bypass special-event dedup logic
+);
+```
+
+Special events (`first_open`, `subscription_purchased`, `paywall_shown`, `tutorial_completed`) are sent only once and stored in localStorage.
+
+---
+
+#### `createSubscription(data)` / `checkSubscription()`
+
+```typescript
+await WebsSDK.Networking.createSubscription({ ... });
+const isActive = await WebsSDK.Networking.checkSubscription(); // returns boolean
+```
+
+---
+
+#### Pending events queue
+
+For offline scenarios:
+
+```typescript
+WebsSDK.Networking.addPendingEvent({ eventType, eventKeyword, eventData });
+await WebsSDK.Networking.sendPendingEvents(); // flush when back online
+WebsSDK.Networking.clearPendingEvents();
+```
+
+---
+
+### 4.5 Calypso — Event Tracking
+
+**File:** `src/libraries/calypso.ts`  
+**Accessed as:** `WebsSDK.Calypso` or `WebsSDK.pre.Calypso`
+
+Calypso is the internal analytics platform. It is separate from Mixpanel (which is a third-party service).
+
+```typescript
+await WebsSDK.Calypso.trackEvent(
+  'page_view',     // event_name
+  'screen',        // event_type: 'screen' | 'action' | 'other'
+  {                // event_data: any payload
+    url: '/home',
+    is_logged: true,
+    user_id: '12345',
+  }
+);
+```
+
+In `next_template`, Calypso is called from `POST /api/calypso/event_track`. The hook `useEventTracker()` builds the payload (user metadata, URL, device info) and calls that endpoint.
+
+---
+
+### 4.6 Legal
+
+**File:** `src/libraries/legal.ts`  
+**Accessed as:** `WebsSDK.Legal`
+
+```typescript
+const result = await WebsSDK.Legal.getLegalText(
+  'myportal-web',  // website_id
+  'tos',           // type: 'tos' | 'privacy' | 'cookies' | 'faq'
+  'en'             // language (optional, defaults to portal default)
+);
+// result.data: HTML string of the legal document
+```
+
+---
+
+### 4.7 Session
+
+**File:** `src/libraries/session.ts`  
+**Accessed as:** `WebsSDK.Session`
+
+Handles the full SDK initialisation lifecycle.
+
+```typescript
+await WebsSDK.Session.init();
+// Sequence:
+// 1. storeSessionStructure() — browser/device info
+// 2. checkUserID()           — fetch or create anonymous user ID
+// 3. Networking.executeInit() — fetch /config and mutate Config
+// 4. checkFirstOpen()        — fire first_open event if new user
+```
+
+Other useful methods:
+
+```typescript
+WebsSDK.Session.getSessionData();     // Returns SessionData: { device, adjust, lang, package }
+WebsSDK.Session.getSessionID();       // Returns string | null
+WebsSDK.Session.getUserID();          // Returns string | null
+WebsSDK.Session.getIsSubscribed();    // Returns boolean
+WebsSDK.Session.getIsFirstOpen();     // Returns boolean
+await WebsSDK.Session.setIsSubscribed(true);
+```
+
+---
+
+### 4.8 Storage
+
+**File:** `src/libraries/storage.ts`  
+**Accessed as:** `WebsSDK.Storage`
+
+A localStorage wrapper that also handles image operations.
+
+```typescript
+// Basic key-value
+WebsSDK.Storage.set('myKey', 'myValue');
+const value = WebsSDK.Storage.get('myKey');     // string | null
+WebsSDK.Storage.remove('myKey');
+WebsSDK.Storage.has('myKey');                   // boolean
+WebsSDK.Storage.clear();
+
+// Async variants (for complex objects)
+await WebsSDK.Storage.storeData('myKey', { foo: 'bar' });
+const data = await WebsSDK.Storage.getData('myKey');
+
+// Image compression
+const base64 = await WebsSDK.Storage.compressImage(imageUri, 5); // max 5 MB
+
+// User-generated creations
+await WebsSDK.Storage.handleDownloadImageToCreations(base64, 'avatar.jpg', metadata);
+const creations = await WebsSDK.Storage.getCreations();
+await WebsSDK.Storage.deleteCreation('dirName');
+await WebsSDK.Storage.deleteAllCreations();
+```
+
+---
+
+### 4.9 Other Libraries
+
+#### Utils
+
+```typescript
+import WebsSDK from 'webs-sdk';
+import { cn } from 'webs-sdk'; // Tailwind class merge helper
+
+WebsSDK.Utils.isMobile()           // boolean
+WebsSDK.Utils.isBase64(str)        // boolean
+WebsSDK.Utils.generateId()         // string (random UUID)
+WebsSDK.Utils.debounce(fn, 300)    // debounced function
+WebsSDK.Utils.isValidEmail(str)    // boolean
+WebsSDK.Utils.buildQueryString({}) // string
+await WebsSDK.Utils.encryptData(str) // { encryptedData, ivBase64 }
+```
+
+#### Audio (Text-to-Speech)
+
+```typescript
+await WebsSDK.Audio.speakText('Hello world', 'en');
+WebsSDK.Audio.stop();
+WebsSDK.Audio.isSupported(); // boolean
+```
+
+#### MixPanel
+
+```typescript
+await WebsSDK.MixPanel.initialize(token, trackAutomaticEvents, devMode);
+await WebsSDK.MixPanel.trackEvent('purchase', { amount: 9.99 });
+await WebsSDK.MixPanel.superProperties({ user_type: 'subscribed' });
+```
+
+#### ContentManager
+
+```typescript
+// Fetch content by CMS preset
+const result = await WebsSDK.ContentManager.getContentByPreset('homepage', { lang: 'en' });
+
+// Fetch a tagged content collection (for carousels, filtered lists)
+const collection = await WebsSDK.ContentManager.getCollection(
+  ['esports', 'featured'],  // tags
+  'en',                     // language
+  false                     // preprod flag
+);
+```
+
+---
+
+## 5. Google Analytics
+
+**File:** `src/libraries/googleAnalytics.ts`
+
+GA4 is **never loaded** until the user explicitly grants consent. There is no Consent Mode v2 fallback — if there is no consent, the script is never injected.
+
+```typescript
+import {
+  initGoogleAnalytics,
+  updateGAConsent,
+  trackGAEvent,
+  trackGAPageView,
+  isGALoaded,
+} from 'webs-sdk';
+import type { GAOptions } from 'webs-sdk';
+```
+
+#### `initGoogleAnalytics(trackingId, options?)`
+
+Register the GA4 tracking ID. Loads the script immediately if consent was already granted; otherwise stores the ID and waits for `updateGAConsent('granted')`.
+
+```typescript
+await initGoogleAnalytics('G-XXXXXXXXXX', {
+  sendPageView: true,   // send page_view on init (default: true)
+  debug: false,         // enable GA4 debug_mode (default: false)
+});
+```
+
+**Load flow:**
+```
+initGoogleAnalytics(gaId)
+  ├── localStorage.TRACKING_PERMISSION === 'granted'
+  │     → inject <script>, call gtag('config', gaId)
+  └── no consent yet
+        → store as _pendingTrackingId (waits)
+
+updateGAConsent('granted')
+  ├── _pendingTrackingId exists → inject script now
+  └── GA already loaded → gtag('consent', 'update', { analytics_storage: 'granted' })
+
+updateGAConsent('denied')
+  └── localStorage.TRACKING_PERMISSION = 'denied'  (GA never loads)
+```
+
+#### `updateGAConsent(status)` — Call from consent callbacks
+
+```typescript
+// On accept all
+updateGAConsent('granted');
+
+// On reject / essential only
+updateGAConsent('denied');
+```
+
+#### `trackGAEvent(eventName, params?)`
+
+```typescript
+trackGAEvent('purchase', { value: 9.99, currency: 'EUR' });
+// No-op if GA is not loaded
+```
+
+#### `trackGAPageView(url?, title?)`
+
+```typescript
+trackGAPageView('/new-page', 'New Page Title');
+```
+
+#### `isGALoaded()` → `boolean`
+
+---
+
+## 6. CookieConsent Component
+
+**Files:** `src/components/CookieConsent/`
+
+GDPR consent banner with a 3-category settings panel. Renders nothing if a previous decision is already stored in the `cookieConsent` cookie.
+
+```typescript
+import { CookieConsent, getCookieConsentTexts } from 'webs-sdk';
+import type {
+  CookieConsentProps,
+  CookieConsentTheme,
+  CookieConsentPreferences,
+  CookieConsentTexts,
+} from 'webs-sdk';
+```
+
+#### Basic usage
+
+```tsx
+<CookieConsent
+  locale="en"
+  privacyPolicyUrl="https://myportal.com/privacy"
+  onAccept={() => updateGAConsent('granted')}
+  onReject={() => updateGAConsent('denied')}
+  onSaveSettings={(prefs) => updateGAConsent(prefs.analytical ? 'granted' : 'denied')}
+/>
+```
+
+#### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `locale` | `string` | `'en'` | Language: `en`, `es`, `fr`, `nl`, `ar`, `de`, `fi`, `ro`, `tr` |
+| `privacyPolicyUrl` | `string` | — | Privacy policy URL. Link is hidden if omitted |
+| `config` | `CookieConsentConfig` | — | Cookie name, TTL, localStorage key overrides |
+| `theme` | `CookieConsentTheme` | — | Visual customisation |
+| `texts` | `Partial<CookieConsentTexts>` | — | Override specific translation strings |
+| `onAccept` | `() => void` | — | Called when user clicks "Accept all" |
+| `onReject` | `() => void` | — | Called when user clicks "Essential only" |
+| `onSaveSettings` | `(prefs: CookieConsentPreferences) => void` | — | Called from the settings panel |
+
+#### Theme
+
+```typescript
+interface CookieConsentTheme {
+  backgroundColor?: string;    // Supports CSS gradients
+  textColor?: string;
+  titleColor?: string;
+  accentColor?: string;        // Shortcut: applies to Accept button, Reject border, links
+  acceptButtonBg?: string;     // Supports CSS gradients (uses CSS 'background', not 'background-color')
+  acceptButtonText?: string;
+  essentialButtonText?: string;
+  essentialButtonBorder?: string;
+  linkColor?: string;
+  borderColor?: string;
+  borderRadius?: string;
+  fontFamily?: string;
+  zIndex?: number;
+}
+```
+
+The banner automatically generates a glow shadow from `accentColor` using 25% opacity (8-digit hex alpha).
+
+#### Storage
+
+| Key | Values | TTL |
+|---|---|---|
+| Cookie `cookieConsent` | `accepted` \| `rejected` \| `custom` | 1 year |
+| `localStorage.TRACKING_PERMISSION` | `granted` \| `denied` | Permanent |
+| `localStorage.FUNCTIONAL_PERMISSION` | `granted` \| `denied` | Permanent |
+
+#### Consent flow
+
+```
+Component mounts
+  ├── Cookie cookieConsent exists → component renders null (invisible)
+  └── No cookie → banner visible
+
+Accept all    → cookieConsent=accepted, TRACKING_PERMISSION=granted → onAccept()
+Reject        → cookieConsent=rejected, TRACKING_PERMISSION=denied  → onReject()
+Manage cookies → Settings panel:
+  - Mandatory  (always on, not editable)
+  - Functional (checkbox → FUNCTIONAL_PERMISSION)
+  - Analytical (checkbox → TRACKING_PERMISSION)
+  → onSaveSettings({ functional, analytical })
+```
+
+#### Getting translated texts manually
+
+```typescript
+const texts = getCookieConsentTexts('es');
+// Returns CookieConsentTexts with all strings in Spanish
+```
+
+---
+
+## 7. CDN Proxy
+
+**File:** `src/libraries/cdn.ts`
+
+Proxies asset requests to CloudFront. Implemented using Web API only (`fetch`, `Response`) — compatible with Next.js Edge Runtime.
+
+```typescript
+import { handleCDNRequest } from 'webs-sdk';
+import type { CDNOptions } from 'webs-sdk';
+
+async function handleCDNRequest(
+  pathname: string,          // e.g. '/cdn/assets/image.png'
+  options?: CDNOptions
+): Promise<Response | null>  // null if pathname does not start with '/cdn/'
+
+interface CDNOptions {
+  cdnBaseUrl?: string;    // Default: 'https://dy822md8ge77v.cloudfront.net'
+  cacheSeconds?: number;  // Default: 300 (5 minutes)
+}
+```
+
+**Response headers (on success):**
+
+```
+Content-Type: <detected MIME type>
+Cache-Control: public, max-age=300, s-maxage=300
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET, POST, OPTIONS, PUT, DELETE
+```
+
+**Usage in HTML:**
+
+```html
+<img src="/cdn/chatconnect/assets/flags/gbr.png" />
+```
+
+> **Note:** In `next_template`, the CDN handler is **inlined** in `src/app/cdn/[...path]/route.ts` rather than imported from the SDK. This is intentional: the Edge Route Handler needs full control over headers and must not pull in Node.js dependencies. The SDK function is available for other contexts (non-Edge environments).
+
+---
+
+## 8. React Content Components
+
+These components are self-contained widgets that call the Fluver AI API directly. They are designed to be dropped into any page in `next_template`.
+
+### Component pattern
+
+Every content component exports three variants:
+
+| Export | Use |
+|---|---|
+| `ComponentName` | Inline embeddable widget |
+| `ComponentNamePage` | Full-page layout |
+| `ComponentNameForYouCard` | Small card for "For You" section |
+
+All components share the same props pattern:
+
+```typescript
+interface ComponentProps {
+  config?: ComponentConfig;     // API keys, endpoints, presets
+  theme?: ThemeConfig;          // CSS class names or colour values
+  texts?: ComponentTexts;       // i18n strings (all optional)
+  websiteId?: string;           // For multi-portal tracking
+  onResult?: (data) => void;    // Success callback
+  onError?: (err) => void;      // Error callback
+}
+```
+
+### Available components
+
+```typescript
+import {
+  AvatarAI, AvatarAIPage, AvatarAIForYouCard,
+  CreativeFaceSwap, CreativeFaceSwapPage, CreativeFaceSwapForYouCard,
+  Wallpapers, WallpapersPage, WallpapersForYouCard,
+  WallpapersName, WallpapersNamePage, WallpapersNameForYouCard, AETemplatesSection,
+  Ringtone, RingtoneForYouCard,
+  MemeGenerator, MemeGeneratorForYouCard,
+  Quiz, QuizForYouCard,
+  Stickers, StickersForYouCard,
+} from 'webs-sdk';
+```
+
+### ARFilters — DeepAR
+
+Fullscreen AR camera experience powered by DeepAR. Requires a license key.
+
+```typescript
+import { ARFilters, ARFiltersForYouCard, getARFiltersTexts } from 'webs-sdk';
+import type { DeepARProps, DeepARFilter, DeepARTexts } from 'webs-sdk';
+
+<ARFilters
+  licenseKey="your-deepar-license-key"
+  websiteId="myportal-web"
+  apiBaseUrl="https://api.fluver-ai.com"
+  downloadProxyUrl="/cdn"           // CORS proxy for downloading filter assets
+  filters={[                         // Explicit filter list (optional)
+    { file: 'beauty', thumbUrl: '/thumb.jpg' }
+  ]}
+  filterTag="ar-filters"             // Alternatively, fetch filters from CMS by tag
+  locale="en"
+  texts={getARFiltersTexts('en')}    // Required
+  onPhotoTaken={(url) => sharePhoto(url)}
+  onVideoRecorded={(url) => shareVideo(url)}
+/>
+```
+
+### SpinningWheel — Gamification
+
+```typescript
+import { SpinningWheel, wheelThemes, SpinningWheelAPI, createSpinningWheelAPI } from 'webs-sdk';
+import type { SpinningWheelProps, WheelSegment, SpinToWinConfig, WheelTheme, ThemeName } from 'webs-sdk';
+
+<SpinningWheel
+  userId="12345"
+  websiteId="myportal-web"
+  theme="vodacom"                // Available: 'vodacom' | 'totalgym' | 'womantoday' | 'afristream' | 'efc'
+  onResult={(segment) => handleWin(segment)}
+  canSpin={true}
+  alreadySpunToday={false}
+/>
+```
+
+Pre-built theme configs: `vodacomConfig`, `totalGymConfig`, `womanTodayConfig`, `afristreamConfig`
+
+---
+
+## 9. Esports Components
+
+Three independent components for esports content portals.
+
+```typescript
+import {
+  EsportsNews,
+  EsportsVideos,
+  EsportsLive,
+} from 'webs-sdk';
+import type {
+  EsportsNewsProps, EsportsNewsConfig, EsportsNewsTheme,
+  EsportsVideosProps, EsportsVideosConfig, EsportsVideosTheme,
+  EsportsLiveProps, EsportsLiveConfig, EsportsLiveTheme,
+  NewsItem, VideoItem, CalendarMatch,
+} from 'webs-sdk';
+```
+
+### EsportsNews
+
+```tsx
+<EsportsNews
+  config={{
+    key: 'api-key',
+    contents: [{
+      preset: 'esports_news',
+      apiProviderId: 'provider-id',
+      category: [],
+      tags: [],
+      limit: 10,
+    }]
+  }}
+  language="en"
+  onNewsClick={(item: NewsItem) => router.push(`/news/${item.id}`)}
+  theme={myNewsTheme}
+  // Detail mode: pass newsId to render EsportsNewsDetail
+  newsId="article-123"
+  newsData={item}   // optional — skip fetch if you already have the data
+  onBack={() => router.back()}
+/>
+```
+
+### EsportsVideos
+
+```tsx
+<EsportsVideos
+  config={{ key: 'api-key', contents: [...] }}
+  language="en"
+  onVideoClick={(item: VideoItem) => openPlayer(item.video_url)}
+  theme={myVideosTheme}
+/>
+```
+
+### EsportsLive
+
+Displays live esports matches with teams, scores, and stream links.
+
+```tsx
+<EsportsLive
+  language="en"
+  timezone="Europe/London"
+  onLiveClick={(item) => openStream(item.streamUrl)}
+  onGameClick={(gameId) => filterByGame(gameId)}
+  onMatchClick={(match: CalendarMatch) => openMatch(match)}
+  theme={myLiveTheme}
+  // Match detail mode:
+  matchId="serie-123"
+  matchData={calendarMatch}  // optional — skip fetch if data is available
+  onBack={() => setMatchId(null)}
+  website_id="myportal-web"
+/>
+```
+
+**Key types:**
+
+```typescript
+interface NewsItem {
+  id: string;
+  title: string;
+  description: string;
+  excerpt: string;
+  category: string;
+  tag: string;
+  thumbnail: string;
+  images: string[];
+  date: string;
+  time: string;
+}
+
+interface VideoItem extends NewsItem {
+  video_url: string;
+  duration: string;
+}
+
+interface CalendarMatch {
+  serie_id: string;
+  serie_name: string;
+  serie_status: string;
+  serie_live: boolean;
+  team_one: Team;
+  team_two: Team;
+  game_name: string;
+  tournament_name: string;
+  stage_name: string;
+}
+
+interface Team {
+  id: string;
+  name: string;
+  image: string;
+  seed: number;
+  score: number;
+  winner: boolean;
+}
+```
+
+---
+
+## 10. UI Component Library
+
+A set of accessible UI primitives based on Radix UI and Tailwind CSS.
+
+```typescript
+import {
+  Button,
+  Input,
+  Dialog,
+  Accordion,
+  Badge,
+  Carousel,
+  Checkbox,
+  DropdownMenu,
+  Label,
+  Select,
+  Separator,
+  Skeleton,
+  Tabs,
+  Tooltip,
+  // ...and more
+} from 'webs-sdk/ui';
+```
+
+> Import from `'webs-sdk/ui'`, not from `'webs-sdk'`.
+
+These components follow the Radix UI composition pattern. Refer to [Radix UI documentation](https://www.radix-ui.com/) for usage — the API surface is the same.
+
+---
+
+## 11. Video Validation Utilities
+
+Validates whether a streaming URL (HLS, DASH, MP4) is actually reachable before attempting playback.
+
+```typescript
+import {
+  validateVideoUrl,
+  validateVideoBatch,
+  getCacheStats,
+  clearValidationCache,
+  cleanExpiredCache,
+} from 'webs-sdk';
+import {
+  useValidateVideoOnMount,
+  useLazyVideoValidation,
+} from 'webs-sdk';
+import type { VideoValidationState, VideoValidationConfig } from 'webs-sdk';
+```
+
+### Pure API (no React)
+
+```typescript
+type VideoValidationState = 'valid' | 'invalid' | 'unknown' | 'validating';
+
+interface VideoValidationConfig {
+  cacheTTL?: number;              // Default: 300000 ms (5 min)
+  headRequestTimeout?: number;    // Default: 8000 ms
+  videoElementTimeout?: number;   // Default: 10000 ms
+  verbose?: boolean;              // Default: false
+}
+
+// Validate a single URL
+const state: VideoValidationState = await validateVideoUrl(url, config?);
+
+// Validate multiple URLs with controlled concurrency
+const results: Map<string, VideoValidationState> = await validateVideoBatch(urls, 3);
+```
+
+**Validation strategy:**
+```
+URL → check cache (TTL: 5 min)
+  └── not cached → HEAD request (8 s timeout)
+        ├── 200-299 → 'valid'
+        ├── network error → fallback: video element test (10 s)
+        │     ├── loadedmetadata → 'valid'
+        │     └── error event → 'invalid'
+        └── 4xx / 5xx → 'invalid'
+```
+
+### React hooks
+
+```typescript
+// Auto-validate on mount — useful to skip rendering broken streams
+const { isValid, isInvalid, isValidating, validationState } =
+  useValidateVideoOnMount(videoUrl, config?);
+
+// Manual / on-demand validation
+const { validate, isValid, isInvalid, isValidating } =
+  useLazyVideoValidation(config?);
+
+await validate(videoUrl);
+```
+
+---
+
+## 12. TypeScript Types Reference
+
+```typescript
+// Authentication
+interface AuthParams {
+  login: string;
+  password: string;
+  website_id: string;
+}
+
+interface AuthResult {
+  status: 'success' | 'error';
+  data?: any;
+  error?: string;
+  errorKey?: string;
+}
+
+interface UnsubscribeParams {
+  user_id: string;
+  callback_url?: string;
+  org?: string;
+}
+
+// Auto-login
+interface AutoLoginResult {
+  status: string;
+  redirectUrl?: string;
+  cookies?: CookieToSet[];
+  error?: string;
+  errorKey?: string;
+}
+
+interface CookieToSet {
+  name: string;
+  value: string;
+  options: {
+    path: string;
+    maxAge: number;
+    sameSite: 'lax' | 'strict' | 'none';
+    secure: boolean;
+    httpOnly: boolean;
+    expires?: Date;
+  };
+}
+
+// Analytics
+interface GAOptions {
+  configParams?: Record<string, unknown>;
+  sendPageView?: boolean;
+  debug?: boolean;
+}
+
+// CDN
+interface CDNOptions {
+  cdnBaseUrl?: string;
+  cacheSeconds?: number;
+}
+
+// Cookie Consent
+interface CookieConsentPreferences {
+  functional: boolean;
+  analytical: boolean;
+}
+```
+
+---
+
+## 13. Production vs Pre-production
+
+| Namespace | Backend URL | Use |
+|---|---|---|
+| `WebsSDK.*` | `https://bc1742.gways.org` | Production data |
+| `WebsSDK.pre.*` | `https://bc1742-pre.gways.org` | Testing, development |
+
+`WebsSDK.pre` is **lazy-loaded** — the pre-production instances are created only on first access, so importing the SDK does not spin up pre-production connections on production servers.
+
+In `next_template`, **all API routes use `WebsSDK.pre.*`** by default. This is intentional: the template is configured for the pre-production environment during development and the CI pipeline handles environment switching on deployment.
+
+```typescript
+// In any next_template API route:
+const WebsSDK = (await import('webs-sdk')).default;
+const result = await WebsSDK.pre.AuthManager.authUser({ login, password, website_id });
+//                             ^^^^ pre-production
+```
+
+---
+
+## 14. Error Patterns & Security
+
+### Consistent error shape
+
+All SDK methods return the same structure:
+
+```typescript
+{
+  status: 'success' | 'error',
+  data?: any,        // Present on success
+  error?: string,    // Human-readable message
+  errorKey?: string  // i18n key for frontend display
+}
+```
+
+### Known error keys
+
+| Key | Source | Meaning |
+|---|---|---|
+| `invalidData` | All methods | Missing required parameters |
+| `userNotFound` | AuthManager | No account with that login |
+| `invalidCredentials` | AuthManager | Wrong password |
+| `accountDisabled` | AuthManager | Account administratively disabled |
+| `userNotActive` | AuthManager | Email not verified or pending activation |
+| `authFailed` | AuthManager | Generic auth failure |
+| `userAlreadyExists` | createUser | Duplicate email/username |
+| `signupFailed` | createUser | Registration rejected by backend |
+| `unsubscribeFailed` | unsubscribeUser | Cancellation failed |
+| `114` | unsubscribeUser | No active subscriptions to cancel |
+| `changePasswordFailed` | changePassword | Password update rejected |
+| `invalidFormat` | uploadProfilePhoto | File type not accepted |
+| `fileTooLarge` | uploadProfilePhoto | File exceeds 5 MB limit |
+| `serverError` | All methods | Backend unreachable or 5xx response |
+
+### Security practices
+
+- **Passwords** are never logged — log statements mask with `'***'`
+- **HttpOnly cookies** — `userSession` is set server-side with `httpOnly: true, secure: true, sameSite: 'lax'`
+- **File uploads** — type and size validated before sending to backend
+- **Session validation** — when `navigation_session: true` in product config, every request validates the token against the backend
+- **Pre-production** — credentials are never sent to production endpoints from the template