cryptique-sdk 1.0.0

package/README.md

@@ -0,0 +1,3580 @@
+# Cryptique Analytics SDK - Function Reference Guide
+
+This document provides a comprehensive reference for all functions in the modular Cryptique SDK. Use this guide to understand the logic, purpose, and when to reuse functions.
+
+---
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [Section 1: Configuration](#section-1-configuration)
+3. [Section 2: Storage Management](#section-2-storage-management)
+4. [Section 3: Session ID Management](#section-3-session-id-management)
+5. [Utility Functions](#utility-functions)
+
+---
+
+## Architecture Overview
+
+The SDK is organized into modular sections, each with a single source of truth. This prevents conflicts, duplicate code, and makes it easy to find and reuse functions.
+
+### Key Principles:
+- **Single Source of Truth**: Only one function handles each responsibility
+- **Modular Design**: Each section is independent and can be understood separately
+- **Clear Data Flow**: Functions have defined inputs/outputs
+- **Error Handling**: Centralized error handling in each section
+
+---
+
+## Section 1: Configuration
+
+### Purpose
+Centralizes all constants, API URLs, storage keys, and configuration values in one place.
+
+### Why It Matters
+- Easy to update URLs/keys without searching through code
+- Prevents typos and inconsistencies
+- Makes it clear what can be configured
+- Single place to change environment (dev/prod)
+
+### Configuration Object: `CONFIG`
+
+```javascript
+CONFIG.API.TRACK              // Main session tracking endpoint
+CONFIG.API.OVERVIEW           // Overview/analytics data endpoint
+CONFIG.API.CUSTOM_EVENTS      // Custom event tracking endpoint
+CONFIG.API.UTM_EVENTS         // UTM campaign tracking endpoint
+
+CONFIG.VERSION                // SDK version string
+
+CONFIG.STORAGE_KEYS.SESSION   // Primary session storage key
+CONFIG.STORAGE_KEYS.USER_ID   // User ID storage key
+CONFIG.STORAGE_KEYS.CONSENT   // Consent flag storage key
+
+CONFIG.SESSION.TIMEOUT_MS     // Session timeout (30 minutes)
+CONFIG.SESSION.BACKUP_VALIDITY_MS  // Backup validity (5 minutes)
+CONFIG.SESSION.BOUNCE_THRESHOLD_SECONDS  // Bounce threshold (30 seconds)
+
+CONFIG.INTERVALS.SESSION_TRACKING_MS  // Session update interval (5 seconds)
+CONFIG.INTERVALS.OVERVIEW_DEBOUNCE_MS  // Overview debounce (10 seconds)
+```
+
+### When to Use
+- **Accessing API URLs**: Use `CONFIG.API.*` instead of hardcoding URLs
+- **Accessing Storage Keys**: Use `CONFIG.STORAGE_KEYS.*` instead of string literals
+- **Session Configuration**: Use `CONFIG.SESSION.*` for timeout and validity checks
+- **Changing Environment**: Update `CONFIG` object to switch between dev/prod
+
+### Reusability
+✅ **Highly Reusable**: Import or reference `CONFIG` anywhere you need configuration values.
+
+---
+
+## Section 2: Storage Management
+
+### Purpose
+Single source of truth for ALL storage operations (localStorage, sessionStorage). Prevents conflicts and ensures consistency.
+
+### Why It Matters
+- Prevents storage conflicts (multiple functions writing different formats)
+- Centralized error handling
+- Easy to debug storage issues
+- Can add features (encryption, compression) in one place
+
+### StorageManager Object
+
+#### `StorageManager.loadSession()`
+**Purpose**: Load session from sessionStorage with localStorage backup fallback.
+
+**Logic Flow**:
+1. Try sessionStorage first (primary source)
+2. If found, update localStorage backup
+3. If not found, try localStorage backup
+4. If backup is recent (< 5 min), restore it
+5. Return session or null
+
+**When to Use**:
+- Loading existing session on page load
+- Checking if session exists
+- Recovering session after tab close
+
+**Returns**: Session object with `{id, userId, lastActivity}` or `null`
+
+**Example**:
+```javascript
+const session = StorageManager.loadSession();
+if (session) {
+  console.log('Session found:', session.id);
+}
+```
+
+---
+
+#### `StorageManager.saveSession(session)`
+**Purpose**: Save session to both sessionStorage and localStorage backup.
+
+**Logic**:
+- Saves to sessionStorage (primary, fast, tab-specific)
+- Also saves to localStorage (backup, survives tab close)
+- Ensures we never lose session data
+
+**When to Use**:
+- After creating new session
+- After updating session data
+- After session activity updates
+
+**Parameters**: `session` - Session object with `{id, userId, lastActivity, ...}`
+
+**Example**:
+```javascript
+const session = {
+  id: 'session-id',
+  userId: 'user-id',
+  lastActivity: Date.now()
+};
+StorageManager.saveSession(session);
+```
+
+---
+
+#### `StorageManager.updateBackup(session)`
+**Purpose**: Update localStorage backup (called automatically by `saveSession`).
+
+**Logic**:
+- Creates lightweight backup with essential data only
+- Stores: sessionId, userId, timestamp
+- Used for session recovery across tabs
+
+**When to Use**:
+- Usually called automatically by `saveSession`
+- Can be called manually if you only want to update backup
+
+**Parameters**: `session` - Session object
+
+---
+
+#### `StorageManager.getUserId()`
+**Purpose**: Get or create persistent user ID.
+
+**Logic**:
+- Checks localStorage for existing user ID
+- If not found, generates new ID: `"usr_" + random string`
+- Stores in localStorage (survives browser restarts)
+
+**When to Use**:
+- Initializing user session
+- Tracking user across sessions
+- User-level analytics
+
+**Returns**: User ID string (e.g., `"usr_abc123xyz"`)
+
+**Example**:
+```javascript
+const userId = StorageManager.getUserId();
+// Always returns same ID for same user
+```
+
+---
+
+#### `StorageManager.getConsent()` / `StorageManager.setConsent(consent)`
+**Purpose**: Get/set user consent status for GDPR/privacy compliance.
+
+**Logic**:
+- Stores consent flag in localStorage
+- Returns `true` if consent given, `false` otherwise
+- Defaults to `false` if storage fails
+
+**When to Use**:
+- Checking if tracking is allowed
+- Storing user consent preference
+- Privacy compliance
+
+**Example**:
+```javascript
+if (StorageManager.getConsent()) {
+  // User has consented, proceed with tracking
+} else {
+  // Show consent banner
+}
+
+// User gives consent
+StorageManager.setConsent(true);
+```
+
+---
+
+#### `StorageManager.getReferrer()` / `StorageManager.saveReferrer(referrer)`
+**Purpose**: Get/set stored referrer (falls back to `document.referrer`).
+
+**Logic**:
+- Stores referrer in localStorage
+- Falls back to `document.referrer` if not stored
+- Falls back to `"direct"` if no referrer
+
+**Why Store**:
+- `document.referrer` can be lost on navigation
+- We want to track original referrer for entire session
+
+**When to Use**:
+- Getting referrer for session tracking
+- Storing referrer on first page visit
+- Traffic source analysis
+
+**Example**:
+```javascript
+const referrer = StorageManager.getReferrer();
+// Returns stored referrer or document.referrer or "direct"
+
+StorageManager.saveReferrer("google.com");
+// Stores referrer for future use
+```
+
+---
+
+#### `StorageManager.acquireLock(name, ttl)`
+**Purpose**: Acquire a lock to prevent race conditions.
+
+**Logic**:
+- Stores timestamp in localStorage with key `"lock_{name}"`
+- If lock exists and is recent (< TTL), return `false` (locked)
+- Otherwise, set lock and return `true` (acquired)
+- Locks expire automatically after TTL
+
+**When to Use**:
+- Preventing multiple functions from creating sessions simultaneously
+- Preventing duplicate API calls
+- Preventing concurrent initialization
+
+**Parameters**:
+- `name`: Lock name (e.g., `'session_creation'`)
+- `ttl`: Time to live in milliseconds (default: 500ms)
+
+**Returns**: `true` if lock acquired, `false` if already locked
+
+**Example**:
+```javascript
+if (StorageManager.acquireLock('session_creation')) {
+  // Only one function can execute this block at a time
+  createSession();
+  StorageManager.releaseLock('session_creation'); // Optional
+}
+```
+
+---
+
+#### `StorageManager.releaseLock(name)`
+**Purpose**: Release a lock (optional - locks expire automatically).
+
+**When to Use**:
+- Explicitly releasing lock before TTL expires
+- Usually not needed (locks expire automatically)
+
+---
+
+#### `StorageManager.saveLastSession(sessionData)` / `StorageManager.getLastSession()`
+**Purpose**: Save/get last session as backup for recovery on next page load.
+
+**Logic**:
+- Saves full session data to localStorage
+- Used as last-resort backup if all other methods fail
+- Can be retrieved on next page load
+
+**When to Use**:
+- Before page unload (as backup)
+- On page load (to recover lost session)
+- Error recovery scenarios
+
+---
+
+#### `StorageManager.clearAll()`
+**Purpose**: Clear all SDK storage (useful for testing/reset).
+
+**Logic**:
+- Removes session, backup, and last session
+- Does NOT clear USER_ID or CONSENT (persistent preferences)
+
+**When to Use**:
+- Testing/debugging
+- User logout
+- Privacy reset
+
+---
+
+#### `StorageManager.updateSessionActivity(session)`
+**Purpose**: Update session activity timestamp.
+
+**Logic**:
+- Updates `sessionData.lastActivity = Date.now()`
+- If session provided, updates that session object and saves it
+- If no session provided, loads current session and updates it
+- Saves updated session to storage
+
+**Parameters**: `session` (optional) - Session object to update. If not provided, loads current session.
+
+**Returns**: Current timestamp (Date.now())
+
+**When to Use**:
+- When tracking user activity (page visits, interactions, etc.)
+- To keep session alive
+- Called automatically by various managers
+
+**Example**:
+```javascript
+StorageManager.updateSessionActivity();
+// Updates lastActivity and saves to storage
+```
+
+---
+
+### Reusability
+✅ **Highly Reusable**: All storage operations should go through `StorageManager`. Never access `localStorage` or `sessionStorage` directly.
+
+---
+
+## Section 3: Session ID Management
+
+### Purpose
+Single source of truth for session ID creation, retrieval, and management. Prevents duplicate sessions and ensures session continuity.
+
+### Why It Matters
+- Prevents duplicate session IDs
+- Ensures session continuity across page navigation
+- Handles edge cases (fast navigation, multiple tabs, storage failures)
+- Single place to fix session ID bugs
+
+### SessionIdManager Object
+
+#### `SessionIdManager.generate()`
+**Purpose**: Generate a new UUID v4 session ID.
+
+**Logic**:
+- Creates UUID v4 format: `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`
+- '4' indicates version 4 (random)
+- 'y' is one of 8, 9, A, or B
+- Guaranteed unique (collision-resistant)
+
+**When to Use**:
+- Creating new session (called internally by `getOrCreate()`)
+- Should NOT be called directly - use `getOrCreate()` instead
+
+**Returns**: UUID v4 string
+
+**Example**:
+```javascript
+// Don't call directly - use getOrCreate() instead
+const sessionId = SessionIdManager.getOrCreate();
+```
+
+---
+
+#### `SessionIdManager.isSessionValid(session)`
+**Purpose**: Check if a session is still valid (not expired).
+
+**Logic**:
+- Session is valid if:
+  - `lastActivity` exists AND is less than 5 minutes ago
+  - OR `lastActivity` doesn't exist (new session format)
+- Uses `CONFIG.SESSION.TIMEOUT_MS` (30 minutes) for timeout check
+
+**When to Use**:
+- Before reusing existing session
+- Checking if session should be expired
+- Validating session before use
+
+**Parameters**: `session` - Session object with `lastActivity` property
+
+**Returns**: `true` if valid, `false` if expired
+
+**Example**:
+```javascript
+const session = StorageManager.loadSession();
+if (SessionIdManager.isSessionValid(session)) {
+  // Session is still active
+} else {
+  // Session expired, create new one
+}
+```
+
+---
+
+#### `SessionIdManager.updateActivity(session)`
+**Purpose**: Update session activity timestamp to keep session alive.
+
+**Logic**:
+- Sets `session.lastActivity` to current timestamp
+- Saves session to storage
+- Called when session is reused
+
+**When to Use**:
+- After reusing existing session
+- After user activity
+- To prevent session expiration
+
+**Parameters**: `session` - Session object
+
+**Returns**: Current timestamp (number)
+
+**Example**:
+```javascript
+const session = StorageManager.loadSession();
+SessionIdManager.updateActivity(session);
+// Session activity updated, session stays alive
+```
+
+---
+
+#### `SessionIdManager.getOrCreate()`
+**Purpose**: Get existing session ID or create new one - THE SINGLE SOURCE OF TRUTH.
+
+**Logic Flow**:
+1. Ensure we have user ID first
+2. Try to load existing session (with retries for fast navigation)
+3. If found, check if it's still valid (< 5 min inactivity)
+4. If valid, reuse it and update activity
+5. If expired or not found, do final checks (with delays)
+6. If still not found, create new session
+7. Verify it was saved correctly
+
+**Key Features**:
+- Retry logic handles fast page navigation (up to 3 attempts)
+- Final checks with delays (up to 5 attempts, 10ms between)
+- Multiple fallbacks: sessionStorage → localStorage → generate new
+- Verification ensures session was saved correctly
+
+**When to Use**:
+- **ONLY function that should create session IDs**
+- On page load to get/create session
+- When you need to ensure session exists
+- Never call `generate()` directly - always use this
+
+**Returns**: Session ID string (UUID v4)
+
+**Example**:
+```javascript
+// This is the ONLY way to get/create session ID
+const sessionId = SessionIdManager.getOrCreate();
+sessionData.sessionId = sessionId;
+```
+
+---
+
+#### `SessionIdManager.syncFromStorage()`
+**Purpose**: Sync session ID from storage if there's a mismatch.
+
+**Logic**:
+- Loads session from storage
+- If storage has different ID than `sessionData.sessionId`, sync it
+- Fixes inconsistencies between memory and storage
+
+**When to Use**:
+- When you suspect session ID mismatch
+- After loading session from storage
+- To fix inconsistencies
+
+**Returns**: `true` if synced, `false` if no sync needed
+
+**Example**:
+```javascript
+if (SessionIdManager.syncFromStorage()) {
+  console.log('Session ID synced from storage');
+}
+```
+
+---
+
+#### `SessionIdManager.initialize()`
+**Purpose**: Initialize session data with session ID.
+
+**Logic**:
+- Calls `getOrCreate()` to get/create session ID
+- Sets `sessionData.sessionId` and `userSession.sessionId`
+- Ensures session ID is never null/undefined
+- Has fallbacks if initialization fails
+
+**When to Use**:
+- On SDK initialization
+- When you need to ensure session is initialized
+- Usually called by `initSessionOnce()`
+
+**Example**:
+```javascript
+SessionIdManager.initialize();
+// sessionData.sessionId is now set
+```
+
+---
+
+### Initialization Guard: `initSessionOnce()`
+
+#### `initSessionOnce()`
+**Purpose**: Initialize session once - prevents race conditions and duplicate initialization.
+
+**Logic**:
+- Uses lock mechanism to ensure only one initialization happens
+- Checks if already initialized
+- If locked, waits and retries
+- Ensures session ID is set before returning
+
+**When to Use**:
+- On SDK startup
+- Should be called before any tracking begins
+- Prevents multiple initializations in multiple tabs
+
+**Example**:
+```javascript
+initSessionOnce();
+// Session is now initialized, safe to start tracking
+```
+
+---
+
+### Utility Functions (Used by Session ID Management)
+
+#### `retryWithDelay(fn, maxAttempts, delayMs)`
+**Purpose**: Retry a function with delays between attempts.
+
+**Logic**:
+- Calls function up to `maxAttempts` times
+- Waits `delayMs` milliseconds between attempts
+- Returns first successful result
+- Returns `null` if all attempts fail
+
+**When to Use**:
+- Handling timing issues during fast page navigation
+- Retrying storage operations
+- Any operation that might fail due to timing
+
+**Parameters**:
+- `fn`: Function to retry (should return truthy value on success)
+- `maxAttempts`: Maximum number of attempts (default: 3)
+- `delayMs`: Delay between attempts in milliseconds (default: 5)
+
+**Returns**: Result from function or `null`
+
+**Example**:
+```javascript
+const session = retryWithDelay(() => {
+  return StorageManager.loadSession();
+}, 3, 5);
+```
+
+---
+
+#### `ensureArray(value, defaultValue)`
+**Purpose**: Ensure value is an array, return default if not.
+
+**When to Use**:
+- Normalizing data that might be array or not
+- Ensuring arrays exist before operations
+
+**Returns**: Array (original or default)
+
+**Example**:
+```javascript
+const visits = ensureArray(sessionData.pageVisits, []);
+// visits is guaranteed to be an array
+```
+
+---
+
+#### `ensureObject(value, defaultValue)`
+**Purpose**: Ensure value is an object, return default if not.
+
+**When to Use**:
+- Normalizing data that might be object or not
+- Ensuring objects exist before operations
+
+**Returns**: Object (original or default)
+
+**Example**:
+```javascript
+const data = ensureObject(rawData, {});
+// data is guaranteed to be an object
+```
+
+---
+
+#### `nowIso()`
+**Purpose**: Get ISO timestamp string.
+
+**Returns**: ISO 8601 timestamp string (e.g., `"2024-01-15T10:30:00.000Z"`)
+
+**When to Use**:
+- Storing timestamps in ISO format
+- Normalizing timestamps
+- API payloads requiring ISO format
+
+**Example**:
+```javascript
+const timestamp = nowIso();
+// "2024-01-15T10:30:00.000Z"
+```
+
+---
+
+#### `getUTMParameters()`
+**Purpose**: Extract UTM parameters from URL.
+
+**Returns**: Object with UTM parameters:
+```javascript
+{
+  source: 'google',
+  medium: 'cpc',
+  campaign: 'summer_sale',
+  term: 'keyword',
+  content: 'ad_variant',
+  utm_id: '12345'
+}
+```
+
+**When to Use**:
+- Tracking campaign sources
+- Session initialization
+- UTM event logging
+
+**Example**:
+```javascript
+const utmData = getUTMParameters();
+if (utmData.source) {
+  console.log('User came from:', utmData.source);
+}
+```
+
+---
+
+#### `getProperReferrer()`
+**Purpose**: Get referrer, prioritizing UTM source over document.referrer.
+
+**Logic**:
+- If UTM source exists, return it
+- Otherwise, return stored referrer or document.referrer or "direct"
+
+**When to Use**:
+- Session initialization
+- Traffic source tracking
+- When you need the best referrer value
+
+**Returns**: Referrer string
+
+**Example**:
+```javascript
+const referrer = getProperReferrer();
+// Returns UTM source if available, otherwise stored/browser referrer
+```
+
+---
+
+### Reusability
+
+✅ **SessionIdManager.getOrCreate()**: **MUST USE** - This is the ONLY function that should create session IDs. Never call `generate()` directly.
+
+✅ **SessionIdManager.isSessionValid()**: Reusable for checking session validity anywhere.
+
+✅ **Utility Functions**: All utility functions are reusable across the SDK.
+
+---
+
+## Data Structures
+
+### `sessionData`
+Minimal structure for Session ID Management:
+```javascript
+{
+  sessionId: null,        // Set by SessionIdManager
+  siteId: string,
+  userId: null,          // Set from StorageManager
+  referrer: "direct",
+  utmData: {},
+  startTime: null,
+  lastActivity: null,
+  isFirstPage: true
+}
+```
+
+### `userSession`
+Synced with sessionData:
+```javascript
+{
+  sessionId: null,        // Synced with sessionData.sessionId
+  userId: null            // Synced with sessionData.userId
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ DO:
+- Use `StorageManager` for all storage operations
+- Use `SessionIdManager.getOrCreate()` to get/create session IDs
+- Use `CONFIG` for all configuration values
+- Use `initSessionOnce()` before starting tracking
+- Check `SessionIdManager.isSessionValid()` before reusing sessions
+
+### ❌ DON'T:
+- Don't access `localStorage` or `sessionStorage` directly
+- Don't call `SessionIdManager.generate()` directly
+- Don't create session IDs in multiple places
+- Don't hardcode storage keys or API URLs
+- Don't skip initialization guard
+
+---
+
+## Quick Reference
+
+### Getting Session ID
+```javascript
+const sessionId = SessionIdManager.getOrCreate();
+```
+
+### Loading Session
+```javascript
+const session = StorageManager.loadSession();
+```
+
+### Saving Session
+```javascript
+StorageManager.saveSession(session);
+```
+
+### Getting User ID
+```javascript
+const userId = StorageManager.getUserId();
+```
+
+### Checking Consent
+```javascript
+if (StorageManager.getConsent()) {
+  // User consented
+}
+```
+
+### Acquiring Lock
+```javascript
+if (StorageManager.acquireLock('operation_name')) {
+  // Do operation
+  StorageManager.releaseLock('operation_name');
+}
+```
+
+---
+
+## Section 4: Session Duration Calculation
+
+### Purpose
+Single source of truth for session duration calculations. Ensures accurate session duration tracking and consistency between page durations and session duration.
+
+### Why It Matters
+- Prevents inaccurate session times
+- Ensures consistency between page and session data
+- Proper bounce detection
+- Single place to fix duration bugs
+
+### DurationManager Object
+
+#### `DurationManager.calculateSeconds(startTime, endTime)`
+**Purpose**: Calculate duration in seconds between two timestamps (rounded).
+
+**Logic**:
+- Converts timestamps to Date objects
+- Calculates difference in milliseconds
+- Converts to seconds
+- Rounds to nearest second
+
+**When to Use**:
+- General duration calculations where rounding is acceptable
+- Session duration from start time
+
+**Parameters**:
+- `startTime`: Start timestamp (Date object or string/number)
+- `endTime`: End timestamp (optional, defaults to current time)
+
+**Returns**: Duration in seconds (rounded)
+
+**Example**:
+```javascript
+const duration = DurationManager.calculateSeconds(sessionData.startTime);
+// Returns rounded duration in seconds
+```
+
+---
+
+#### `DurationManager.calculateSecondsFloor(startTime, endTime)`
+**Purpose**: Calculate duration in seconds between two timestamps (floored).
+
+**Logic**: Same as `calculateSeconds()` but uses `Math.floor()` instead of `Math.round()`
+
+**When to Use**:
+- Page durations (more conservative, prevents over-counting)
+- When you need exact seconds without rounding up
+
+**Returns**: Duration in seconds (floored)
+
+**Example**:
+```javascript
+const pageDuration = DurationManager.calculateSecondsFloor(page.mountTime, page.unmountTime);
+// Returns floored duration in seconds
+```
+
+---
+
+#### `DurationManager.calculateFromPages(pageVisits)`
+**Purpose**: Calculate session duration from page mount/unmount times (PREFERRED METHOD).
+
+**Logic**:
+1. Get first page `mountTime` (session start)
+2. Get last page `unmountTime` or current time (session end)
+3. Calculate: `endTime - startTime`
+
+**When to Use**:
+- When you have page visit data with mount/unmount times
+- Most accurate calculation method
+
+**Parameters**: `pageVisits` - Array of page visit objects with `mountTime` and `unmountTime`
+
+**Returns**: Duration in seconds or `null` if can't calculate
+
+**Example**:
+```javascript
+const duration = DurationManager.calculateFromPages(sessionData.pageVisits);
+if (duration !== null) {
+  // Successfully calculated from page times
+}
+```
+
+---
+
+#### `DurationManager.updateSessionDuration(pageVisits, startTime)`
+**Purpose**: Update `sessionData.duration` - THE SINGLE SOURCE OF TRUTH.
+
+**Logic**:
+1. Try to calculate from page mount/unmount times (preferred)
+2. If that fails, calculate from session start time (fallback)
+3. Update `sessionData.duration`
+4. Return duration
+
+**When to Use**:
+- **ONLY function that should modify sessionData.duration**
+- Whenever you need to update session duration
+- Before sending data to backend
+
+**Parameters**:
+- `pageVisits`: Optional, defaults to `sessionData.pageVisits`
+- `startTime`: Optional, defaults to `sessionData.startTime`
+
+**Returns**: Duration in seconds
+
+**Example**:
+```javascript
+// This is the ONLY way to update session duration
+const duration = DurationManager.updateSessionDuration();
+sessionData.duration = duration; // Already set by function
+```
+
+---
+
+#### `DurationManager.calculateAllPageDurations(pageVisits, currentTime)`
+**Purpose**: Calculate duration for all pages in the session.
+
+**Logic for each page**:
+1. If has `mountTime` and `unmountTime`: use mount→unmount
+2. If has `mountTime` but no `unmountTime`: use mount→current
+3. If no `mountTime`: use timestamp fallback
+4. If no data: use minimum 1 second
+
+**When to Use**:
+- When you need to calculate/update all page durations
+- Before aligning page durations with session duration
+- On page navigation
+
+**Parameters**:
+- `pageVisits`: Array of page visit objects
+- `currentTime`: Optional, defaults to `Date.now()`
+
+**Returns**: Array of page visits with calculated durations
+
+**Example**:
+```javascript
+const updatedPageVisits = DurationManager.calculateAllPageDurations(sessionData.pageVisits);
+sessionData.pageVisits = updatedPageVisits;
+```
+
+---
+
+#### `DurationManager.alignPageDurations(pageVisits, sessionDuration)`
+**Purpose**: Ensure sum of page durations matches session duration exactly.
+
+**Logic**:
+1. Sum all page durations
+2. Compare sum to session duration
+3. If different, adjust last page duration by the difference
+4. Ensure minimum 1 second
+
+**When to Use**:
+- Before sending data to backend (ensures consistency)
+- After calculating session duration
+- To fix discrepancies between page and session durations
+
+**Parameters**:
+- `pageVisits`: Array of page visit objects
+- `sessionDuration`: Target session duration in seconds
+
+**Returns**: Updated page visits array
+
+**Example**:
+```javascript
+const alignedPageVisits = DurationManager.alignPageDurations(
+  sessionData.pageVisits,
+  sessionData.duration
+);
+sessionData.pageVisits = alignedPageVisits;
+```
+
+---
+
+#### `DurationManager.calculateBounceStatus(duration, pagesViewed)`
+**Purpose**: Determine if session is a bounce.
+
+**Logic**:
+- Bounce = duration < 30 seconds AND pagesViewed <= 1
+- Uses `CONFIG.SESSION.BOUNCE_THRESHOLD_SECONDS` (30 seconds)
+
+**When to Use**:
+- When you need to check if session is a bounce
+- Before sending data to backend
+- For bounce rate calculations
+
+**Parameters**:
+- `duration`: Session duration in seconds
+- `pagesViewed`: Number of pages viewed
+
+**Returns**: `true` if bounce, `false` if not
+
+**Example**:
+```javascript
+const isBounce = DurationManager.calculateBounceStatus(
+  sessionData.duration,
+  sessionData.pagesViewed
+);
+sessionData.isBounce = isBounce;
+```
+
+---
+
+#### `DurationManager.ensureValid(duration)`
+**Purpose**: Ensure duration is always a valid number.
+
+**Logic**:
+- Converts to number
+- If null, undefined, NaN, or <= 0: return 1 (minimum)
+- Otherwise: return floored value
+
+**When to Use**:
+- Before using duration values
+- When validating duration data
+- To prevent invalid durations
+
+**Parameters**: `duration` - Duration value (any type)
+
+**Returns**: Valid duration number (minimum 1 second)
+
+**Example**:
+```javascript
+const validDuration = DurationManager.ensureValid(page.duration);
+// Always returns valid number (minimum 1)
+```
+
+---
+
+### Calculation Methods
+
+#### Method A: From Page Mount/Unmount Times (Preferred)
+- **Uses**: `mountTime` and `unmountTime` of pages
+- **Accuracy**: Most accurate
+- **Logic**: `lastPage.unmountTime - firstPage.mountTime`
+- **When**: If page visits have `mountTime` data
+
+#### Method B: From Session Start Time (Fallback)
+- **Uses**: `sessionData.startTime` and current time
+- **Accuracy**: Less accurate (includes navigation time)
+- **Logic**: `currentTime - startTime`
+- **When**: If no page mount/unmount times available
+
+### Key Principles
+
+1. **Single Source of Truth**: Only `updateSessionDuration()` modifies `sessionData.duration`
+2. **Preferred Method**: Use page mount/unmount times when available
+3. **Fallback Logic**: Always have a fallback calculation method
+4. **Consistency**: Page durations must sum to session duration
+5. **Validation**: Always validate durations before use
+6. **Minimum Values**: Never allow 0 or negative durations
+
+### Reusability
+
+✅ **DurationManager.updateSessionDuration()**: **MUST USE** - This is the ONLY function that should modify `sessionData.duration`. Never modify duration directly.
+
+✅ **DurationManager.calculateBounceStatus()**: Reusable for bounce detection anywhere.
+
+✅ **DurationManager.ensureValid()**: Reusable for validating any duration value.
+
+---
+
+## Section 5: Location/Geolocation Management
+
+### Purpose
+Single source of truth for location/geolocation data fetching and storage. Handles IP-based geolocation via ipinfo.io API.
+
+### Why It Matters
+- Centralized location data management
+- Caching prevents unnecessary API calls
+- Fallback ensures we always have location data
+- Single place to fix location bugs
+
+### LocationManager Object
+
+#### `LocationManager.fetchLocationData()`
+**Purpose**: Fetch location data from ipinfo.io API.
+
+**Logic Flow**:
+1. Try primary URL with timeout
+2. If fails, try backup URL
+3. If both fail, return default values
+4. Parse and store location data
+
+**When to Use**:
+- Initializing location data
+- Refreshing location data
+- When location data is missing
+
+**Returns**: Promise that resolves with location data object
+
+**Location Data Structure**:
+```javascript
+{
+  country: "US",
+  ip_address: "192.168.1.1",
+  city: "New York",
+  region: "NY",
+  latitude: "40.7128",
+  longitude: "-74.0060",
+  timezone: "America/New_York",
+  org: "AS12345 Example Org",
+  postal: "10001"
+}
+```
+
+---
+
+#### `LocationManager.storeLocationData(locationData)`
+**Purpose**: Store location data in sessionData (flattened fields).
+
+**Logic**:
+- Stores all location fields directly on sessionData:
+  - `ip_address`, `city`, `region`, `country`, `latitude`, `longitude`, `timezone`, `org`, `postal`
+- Also stores in `sessionData.locationData` object (for structured access)
+- Updates cached country name
+
+**When to Use**:
+- After fetching location data
+- When location data is updated
+
+**Parameters**: `locationData` - Location data object
+
+---
+
+#### `LocationManager.getCountryName()`
+**Purpose**: Get country name (cached or fetch).
+
+**Logic**:
+1. Check runtimeState.countryName cache
+2. Check sessionData.country
+3. If not available, fetch and cache
+
+**Returns**: Promise that resolves with country name string
+
+---
+
+#### `LocationManager.getLocationData()`
+**Purpose**: Get full location data (cached or fetch).
+
+**Logic**:
+1. Check sessionData.locationData
+2. If not available or invalid, fetch
+3. Return location data object
+
+**Returns**: Promise that resolves with location data
+
+---
+
+#### `LocationManager.initialize()`
+**Purpose**: Initialize location data (non-blocking).
+
+**When to Use**:
+- On SDK initialization
+- Should be called early but doesn't block other operations
+
+---
+
+### Reusability
+
+✅ **LocationManager.fetchLocationData()**: Reusable for fetching location anywhere.
+
+✅ **LocationManager.storeLocationData()**: Reusable for storing location data.
+
+---
+
+## Section 6: Session Data Structure & Normalization
+
+### Purpose
+Complete sessionData structure initialization and data normalization for backend compatibility. Handles field mapping (camelCase → snake_case) and ensures all required fields are present.
+
+### Why It Matters
+- Ensures all required fields are present (even if null)
+- Handles field mapping consistently (camelCase → snake_case)
+- Single place to manage session data structure
+- Prevents missing fields errors
+
+### Complete SessionData Structure
+
+```javascript
+let sessionData = {
+  // IDs
+  sessionId: null,              // UUID v4 (internal camelCase)
+  siteId: SITE_ID,
+  teamId: null,                 // May be set externally or from backend
+  userId: null,
+  
+  // Time fields
+  startTime: null,              // ISO string (internal)
+  endTime: null,                // ISO string (internal)
+  lastActivity: null,           // Timestamp (internal)
+  duration: 0,                  // Seconds
+  
+  // Basic session data
+  pagesViewed: 0,               // Internal camelCase
+  isBounce: true,               // Internal camelCase
+  previousSessionId: null,
+  timeSinceLastSession: null,
+  
+  // Entry/Exit pages
+  entryPage: null,
+  exitPage: null,
+  referrer: "direct",
+  
+  // Location fields (FLATTENED - stored directly on sessionData)
+  ip_address: null,             // snake_case for backend
+  city: null,
+  region: null,
+  country: "",
+  latitude: null,
+  longitude: null,
+  timezone: null,
+  org: null,
+  postal: null,
+  
+  // Browser fields (FLATTENED)
+  browser_name: null,
+  browser_version: null,
+  
+  // Device fields (FLATTENED)
+  device_type: null,
+  os: null,
+  resolution: null,
+  user_agent: null,
+  language: null,
+  
+  // Wallet fields (FLATTENED)
+  wallet_address: null,
+  wallet_type: null,
+  chain_name: null,
+  is_web3_user: false,
+  wallet_connected: false,
+  
+  // UTM fields (FLATTENED)
+  utm_source: null,
+  utm_medium: null,
+  utm_campaign: null,
+  utm_term: null,
+  utm_content: null,
+  utm_id: null,
+  
+  // JSONB fields
+  interactions: {},
+  visited_pages: []
+};
+```
+
+### SessionDataManager Object
+
+#### `SessionDataManager.initialize()`
+**Purpose**: Initialize complete sessionData structure.
+
+**Logic**:
+- Ensures all required fields exist (some may already be set)
+- Sets default values for missing fields
+- Initializes time fields (startTime, endTime, lastActivity, duration)
+- Initializes basic session data (pagesViewed, isBounce, etc.)
+- Initializes all location, browser, device, wallet, and UTM fields
+- Initializes JSONB fields (interactions, visited_pages)
+
+**When to Use**:
+- On SDK initialization
+- When sessionData structure needs to be validated
+- Before sending data to backend
+
+**Example**:
+```javascript
+SessionDataManager.initialize();
+// Ensures all fields are present and properly initialized
+```
+
+---
+
+#### `SessionDataManager.toSnakeCase(camelCase)`
+**Purpose**: Convert camelCase field name to snake_case.
+
+**Examples**:
+- `sessionId` → `session_id`
+- `pagesViewed` → `pages_viewed`
+- `isBounce` → `is_bounce`
+
+**Parameters**: `camelCase` - Field name in camelCase
+
+**Returns**: Field name in snake_case
+
+---
+
+#### `SessionDataManager.toCamelCase(snakeCase)`
+**Purpose**: Convert snake_case field name to camelCase.
+
+**Examples**:
+- `session_id` → `sessionId`
+- `pages_viewed` → `pagesViewed`
+- `is_bounce` → `isBounce`
+
+**Parameters**: `snakeCase` - Field name in snake_case
+
+**Returns**: Field name in camelCase
+
+---
+
+#### `SessionDataManager.mapFieldName(internalName)`
+**Purpose**: Map internal field names to backend field names.
+
+**Logic**:
+- Uses predefined field map for special cases
+- Falls back to `toSnakeCase()` for unmapped fields
+- Handles special cases where mapping isn't straightforward
+
+**Field Map**:
+- `sessionId` → `session_id`
+- `siteId` → `site_id`
+- `teamId` → `team_id`
+- `userId` → `user_id`
+- `startTime` → `start_time`
+- `endTime` → `end_time`
+- `lastActivity` → `last_activity`
+- `pagesViewed` → `pages_viewed`
+- `isBounce` → `is_bounce`
+- `previousSessionId` → `previous_session_id`
+- `timeSinceLastSession` → `time_since_last_session`
+- `entryPage` → `entry_page`
+- `exitPage` → `exit_page`
+
+**Parameters**: `internalName` - Internal field name (camelCase)
+
+**Returns**: Backend field name (snake_case)
+
+---
+
+### Field Mapping Strategy
+
+**Internal (JavaScript - camelCase)**:
+- `sessionId` → Backend: `id` (auto-generated by PostgreSQL) and `session_id`
+- `siteId` → Backend: `site_id`
+- `userId` → Backend: `user_id`
+- `startTime` → Backend: `start_time`
+- `pagesViewed` → Backend: `pages_viewed`
+- `isBounce` → Backend: `is_bounce`
+- `lastActivity` → Backend: `last_activity`
+- `previousSessionId` → Backend: `previous_session_id`
+- `timeSinceLastSession` → Backend: `time_since_last_session`
+- `entryPage` → Backend: `entry_page`
+- `exitPage` → Backend: `exit_page`
+
+**Location fields**: Already in snake_case (stored directly)
+
+**Browser/Device/Wallet/UTM fields**: Already in snake_case (stored directly)
+
+---
+
+## Section 7: Browser/Device Detection
+
+### Purpose
+Extract and store browser/device information as flattened fields. Centralized browser and device detection for consistent data collection.
+
+### Why It Matters
+- Centralized browser/device detection
+- Consistent field structure
+- Single place to fix detection bugs
+- Handles modern User-Agent Client Hints API with fallbacks
+
+### BrowserDeviceManager Object
+
+#### `BrowserDeviceManager.detect()`
+**Purpose**: Detect browser and device information.
+
+**Logic**:
+1. Detects device type (desktop/mobile/tablet) from user agent
+2. Extracts browser name using modern User-Agent Client Hints API (if available)
+3. Falls back to parsing user agent string for browser name
+4. Extracts OS, resolution, user agent, and language
+
+**Device Type Detection**:
+- Mobile: `/Mobi|Android/i` in user agent
+- Tablet: `/Tablet|iPad/i` in user agent
+- Desktop: Default (if not mobile or tablet)
+
+**Browser Detection**:
+- Primary: `navigator.userAgentData?.brands?.[0]?.brand` (modern API)
+- Fallback: Parse user agent string (Chrome, Firefox, Safari, Edge, Opera)
+- Final fallback: `navigator.appName`
+
+**Returns**: Object with browser/device fields (all snake_case):
+```javascript
+{
+  browser_name: "Chrome",           // Browser name
+  browser_version: "120.0.0.0",     // Browser version
+  device_type: "desktop",           // "desktop" | "mobile" | "tablet"
+  os: "Win32",                      // Operating system
+  resolution: "1920x1080",          // Screen resolution
+  user_agent: navigator.userAgent,  // Full user agent string
+  language: "en-US"                 // Browser language
+}
+```
+
+**When to Use**:
+- On SDK initialization
+- When browser/device info needs to be refreshed
+- Before sending data to backend
+
+**Example**:
+```javascript
+const browserDeviceData = BrowserDeviceManager.detect();
+// Returns: { browser_name: "Chrome", device_type: "desktop", ... }
+```
+
+---
+
+#### `BrowserDeviceManager.store(data)`
+**Purpose**: Store browser/device data in sessionData (flattened).
+
+**Logic**:
+- Stores all fields directly on sessionData (flattened for backend compatibility)
+- If no data provided, calls `detect()` first
+- All fields stored in snake_case format
+
+**Stores on sessionData**:
+- `browser_name` - Browser name
+- `browser_version` - Browser version
+- `device_type` - Device type (desktop/mobile/tablet)
+- `os` - Operating system
+- `resolution` - Screen resolution (e.g., "1920x1080")
+- `user_agent` - Full user agent string
+- `language` - Browser language
+
+**Parameters**: `data` (optional) - Browser/device data object. If not provided, calls `detect()`.
+
+**When to Use**:
+- After detecting browser/device info
+- On SDK initialization
+- When browser/device data needs to be updated
+
+**Example**:
+```javascript
+BrowserDeviceManager.store(); // Auto-detects and stores
+// OR
+const data = BrowserDeviceManager.detect();
+BrowserDeviceManager.store(data);
+```
+
+---
+
+#### `BrowserDeviceManager.initialize()`
+**Purpose**: Initialize browser/device detection.
+
+**Logic**:
+- Calls `detect()` to get browser/device information
+- Calls `store()` to save data to sessionData
+
+**When to Use**:
+- On SDK initialization
+- Should be called early in initialization flow
+
+**Example**:
+```javascript
+BrowserDeviceManager.initialize();
+// Detects and stores browser/device info in sessionData
+```
+
+---
+
+### Reusability
+
+✅ **BrowserDeviceManager.detect()**: Reusable for detecting browser/device anywhere.
+
+✅ **BrowserDeviceManager.store()**: Reusable for storing browser/device data.
+
+✅ **BrowserDeviceManager.initialize()**: Reusable for initialization.
+
+---
+
+## Section 8: UTM Parameter Management
+
+### Purpose
+Extract and store UTM parameters as flattened fields. Centralized UTM parameter extraction from URL query string.
+
+### Why It Matters
+- Centralized UTM parameter extraction
+- Consistent field structure
+- Single place to fix UTM bugs
+- Handles missing parameters gracefully
+
+### UTMManager Object
+
+#### `UTMManager.extract()`
+**Purpose**: Extract UTM parameters from URL query string.
+
+**Logic**:
+- Uses `URLSearchParams` to parse query string
+- Extracts all 6 UTM parameters
+- Returns null for missing parameters (not empty strings)
+
+**Returns**: Object with UTM fields (all snake_case):
+```javascript
+{
+  utm_source: "google",        // or null
+  utm_medium: "cpc",           // or null
+  utm_campaign: "summer_sale",  // or null
+  utm_term: "keyword",         // or null
+  utm_content: "ad_variant",   // or null
+  utm_id: "12345"              // or null
+}
+```
+
+**When to Use**:
+- On SDK initialization
+- When UTM parameters need to be refreshed
+- Before sending data to backend
+
+**Example**:
+```javascript
+const utmData = UTMManager.extract();
+// Returns: { utm_source: "google", utm_medium: "cpc", ... }
+```
+
+---
+
+#### `UTMManager.store(data)`
+**Purpose**: Store UTM data in sessionData (flattened).
+
+**Logic**:
+- Stores all 6 UTM fields directly on sessionData (flattened)
+- Also stores in `sessionData.utmData` object (for backward compatibility)
+- If no data provided, calls `extract()` first
+
+**Stores on sessionData**:
+- `utm_source` - UTM source parameter
+- `utm_medium` - UTM medium parameter
+- `utm_campaign` - UTM campaign parameter
+- `utm_term` - UTM term parameter
+- `utm_content` - UTM content parameter
+- `utm_id` - UTM ID parameter
+
+**Parameters**: `data` (optional) - UTM data object. If not provided, calls `extract()`.
+
+**When to Use**:
+- After extracting UTM parameters
+- On SDK initialization
+- When UTM data needs to be updated
+
+**Example**:
+```javascript
+UTMManager.store(); // Auto-extracts and stores
+// OR
+const data = UTMManager.extract();
+UTMManager.store(data);
+```
+
+---
+
+#### `UTMManager.initialize()`
+**Purpose**: Initialize UTM parameter extraction.
+
+**Logic**:
+- Calls `extract()` to get UTM parameters
+- Calls `store()` to save data to sessionData
+
+**When to Use**:
+- On SDK initialization
+- Should be called early in initialization flow
+
+**Example**:
+```javascript
+UTMManager.initialize();
+// Extracts and stores UTM parameters in sessionData
+```
+
+---
+
+### Reusability
+
+✅ **UTMManager.extract()**: Reusable for extracting UTM parameters anywhere.
+
+✅ **UTMManager.store()**: Reusable for storing UTM data.
+
+✅ **UTMManager.initialize()**: Reusable for initialization.
+
+---
+
+## Section 9: Wallet/Web3 Management
+
+### Purpose
+Detect and store wallet/Web3 information as flattened fields. Comprehensive support for EVM wallets and chains with real-time tracking.
+
+### Why It Matters
+- **Comprehensive Wallet Detection**: Supports 30+ EVM wallets
+- **Multi-Chain Support**: Recognizes 40+ EVM-compatible chains
+- **EIP-6963 Support**: Modern multi-wallet detection standard
+- **Real-Time Tracking**: Listens for wallet events (account changes, chain changes)
+- **Non-Intrusive**: Detects wallets without prompting user
+- **Single Source of Truth**: Centralized wallet state management
+
+### WalletManager Object
+
+#### Supported Wallets (30+ EVM Wallets)
+
+**Major Wallets:**
+- ✅ **MetaMask** - Most popular Ethereum wallet
+- ✅ **Trust Wallet** - Popular mobile wallet
+- ✅ **Coinbase Wallet** - Coinbase's official wallet
+- ✅ **Brave Wallet** - Built into Brave browser
+- ✅ **Frame** - Privacy-focused wallet
+- ✅ **Phantom** - Solana wallet (EVM support)
+- ✅ **TronLink** - Tron wallet
+
+**Additional Wallets:**
+- ✅ **OKX Wallet** - OKX exchange wallet
+- ✅ **TokenPocket** - Multi-chain wallet
+- ✅ **SafePal** - Hardware wallet software
+- ✅ **MathWallet** - Multi-chain wallet
+- ✅ **1inch Wallet** - DEX aggregator wallet
+- ✅ **Alpha Wallet** - Mobile wallet
+- ✅ **AToken** - Multi-chain wallet
+- ✅ **BitKeep** - Popular DeFi wallet
+- ✅ **BlockWallet** - Privacy wallet
+- ✅ **Coin98** - Vietnamese wallet
+- ✅ **Dawn** - Ethereum wallet
+- ✅ **Enkrypt** - Multi-chain wallet
+- ✅ **Exodus** - Desktop wallet
+- ✅ **Frontier** - DeFi wallet
+- ✅ **Gamestop** - GameStop wallet
+- ✅ **HyperPay** - Payment wallet
+- ✅ **ImToken** - Chinese wallet
+- ✅ **Infinity Wallet** - Multi-chain wallet
+- ✅ **Liquality** - Atomic swap wallet
+- ✅ **MEW CX** - MyEtherWallet
+- ✅ **Opera** - Opera browser wallet
+- ✅ **Portal** - WalletConnect wallet
+- ✅ **Rabby** - DeFi wallet
+- ✅ **Rainbow** - Beautiful mobile wallet
+- ✅ **Status** - Mobile wallet
+- ✅ **Tally** - Community wallet
+- ✅ **Tokenary** - iOS wallet
+- ✅ **Torus** - Social login wallet
+- ✅ **XDEFI** - Multi-chain wallet
+- ✅ **Zerion** - DeFi portfolio wallet
+
+**Detection Methods:**
+1. **EIP-6963** (Modern Standard): Detects wallets via `eip6963:announceProvider` event
+2. **window.ethereum Properties**: Checks wallet-specific properties (e.g., `isMetaMask`)
+3. **Global Wallet Objects**: Checks for wallet-specific global objects (e.g., `window.okxwallet`)
+
+---
+
+#### Supported Chains (40+ EVM-Compatible Chains)
+
+**Mainnets:**
+- ✅ **Ethereum Mainnet** (Chain ID: 1)
+- ✅ **Binance Smart Chain** (Chain ID: 56)
+- ✅ **Polygon** (Chain ID: 137)
+- ✅ **Optimism** (Chain ID: 10)
+- ✅ **Arbitrum One** (Chain ID: 42161)
+- ✅ **Avalanche C-Chain** (Chain ID: 43114)
+- ✅ **Fantom Opera** (Chain ID: 250)
+- ✅ **Gnosis Chain** (Chain ID: 100)
+- ✅ **Aurora** (Chain ID: 1313161554)
+- ✅ **Base** (Chain ID: 8453)
+- ✅ **zkSync Era** (Chain ID: 324)
+- ✅ **Linea** (Chain ID: 59144)
+- ✅ **Scroll** (Chain ID: 534352)
+- ✅ **Mantle** (Chain ID: 5000)
+- ✅ **Celo** (Chain ID: 42220)
+- ✅ **Moonbeam** (Chain ID: 1284)
+- ✅ **Moonriver** (Chain ID: 1285)
+- ✅ **Harmony** (Chain ID: 1666600000)
+- ✅ **Cronos** (Chain ID: 25)
+- ✅ **Metis** (Chain ID: 1088)
+- ✅ **Polygon zkEVM** (Chain ID: 1101)
+- ✅ **opBNB** (Chain ID: 204)
+- ✅ **OKXChain** (Chain ID: 196)
+- ✅ **Blast** (Chain ID: 81457)
+- ✅ **Chiliz Chain** (Chain ID: 88888)
+- ✅ **ZetaChain** (Chain ID: 7001)
+- ✅ **Core** (Chain ID: 1116)
+- ✅ **Astar zkEVM** (Chain ID: 3776)
+
+**Testnets:**
+- ✅ **Holesky** (Chain ID: 17000)
+- ✅ **Sepolia** (Chain ID: 11155111)
+- ✅ **Goerli** (Chain ID: 5)
+- ✅ **BSC Testnet** (Chain ID: 97)
+- ✅ **Mumbai** (Chain ID: 80001)
+- ✅ **Arbitrum Sepolia** (Chain ID: 421614)
+- ✅ **Optimism Sepolia** (Chain ID: 11155420)
+- ✅ **Base Sepolia** (Chain ID: 84532)
+- ✅ **Avalanche Fuji** (Chain ID: 43113)
+- ✅ **Fantom Testnet** (Chain ID: 4002)
+
+**Unknown Chains:**
+- ✅ Automatically displays as `Unknown Chain (ID: <chainId>)` for unrecognized chains
+
+---
+
+#### `WalletManager.detectWalletType()`
+**Purpose**: Detect wallet type from available providers.
+
+**Logic**:
+1. Checks EIP-6963 providers first (modern standard)
+2. Checks `window.ethereum` wallet patterns (30+ wallets)
+3. Checks global wallet objects (OKX, TokenPocket, etc.)
+4. Falls back to "Web3 Wallet" if `window.ethereum` exists but no specific wallet detected
+5. Returns "No Wallet Detected" if no wallet found
+
+**Returns**: Wallet name string (e.g., "MetaMask", "Trust Wallet", "No Wallet Detected")
+
+**When to Use**:
+- On SDK initialization
+- When wallet type needs to be refreshed
+- Before sending data to backend
+
+**Example**:
+```javascript
+const walletType = WalletManager.detectWalletType();
+// Returns: "MetaMask" or "Trust Wallet" or "No Wallet Detected"
+```
+
+---
+
+#### `WalletManager.getChainNameFromId(chainId)`
+**Purpose**: Convert chain ID to human-readable chain name.
+
+**Logic**:
+- Handles hex string chain IDs (e.g., "0x1" → 1)
+- Handles decimal string chain IDs (e.g., "1" → 1)
+- Looks up chain name in `CHAIN_NAMES` mapping
+- Returns "Unknown Chain (ID: <chainId>)" for unrecognized chains
+
+**Parameters**: `chainId` - Chain ID (number, hex string, or decimal string)
+
+**Returns**: Chain name string (e.g., "Ethereum Mainnet", "Polygon")
+
+**Example**:
+```javascript
+const chainName = WalletManager.getChainNameFromId(1);
+// Returns: "Ethereum Mainnet"
+
+const chainName = WalletManager.getChainNameFromId("0x38");
+// Returns: "Binance Smart Chain"
+```
+
+---
+
+#### `WalletManager.detectChainId()`
+**Purpose**: Detect chain ID from provider.
+
+**Logic**:
+1. Checks `window.ethereum.chainId` property (modern providers)
+2. Requests chain ID via `eth_chainId` method
+3. Falls back to Web3.js if available
+4. Returns null if no provider or error
+
+**Returns**: Promise that resolves to chain ID (hex string) or null
+
+**When to Use**:
+- When chain ID needs to be detected
+- Before converting to chain name
+
+**Example**:
+```javascript
+const chainId = await WalletManager.detectChainId();
+// Returns: "0x1" (Ethereum) or null
+```
+
+---
+
+#### `WalletManager.detectChainName()`
+**Purpose**: Detect chain name from provider.
+
+**Logic**:
+1. Gets chain ID via `detectChainId()`
+2. Converts chain ID to chain name via `getChainNameFromId()`
+3. Returns "Not Connected" if no chain ID
+
+**Returns**: Promise that resolves to chain name string
+
+**When to Use**:
+- On SDK initialization
+- When chain name needs to be refreshed
+- After chain change events
+
+**Example**:
+```javascript
+const chainName = await WalletManager.detectChainName();
+// Returns: "Ethereum Mainnet" or "Not Connected"
+```
+
+---
+
+#### `WalletManager.checkWalletConnected()`
+**Purpose**: Check if wallet is connected (non-intrusive).
+
+**Logic**:
+- Uses `eth_accounts` method (doesn't prompt user)
+- Returns true if accounts exist, false otherwise
+- Returns false if no provider
+
+**Returns**: Promise that resolves to boolean
+
+**When to Use**:
+- On SDK initialization (silent check)
+- Before updating wallet info
+- To check connection status without prompting
+
+**Example**:
+```javascript
+const isConnected = await WalletManager.checkWalletConnected();
+// Returns: true or false
+```
+
+---
+
+#### `WalletManager.getWalletAddress()`
+**Purpose**: Get connected wallet address (non-intrusive).
+
+**Logic**:
+- Uses `eth_accounts` method (doesn't prompt user)
+- Returns first account address or null
+- Returns null if no provider or error
+
+**Returns**: Promise that resolves to wallet address (hex string) or null
+
+**When to Use**:
+- When wallet address needs to be retrieved
+- After wallet connection
+- On account change events
+
+**Example**:
+```javascript
+const address = await WalletManager.getWalletAddress();
+// Returns: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" or null
+```
+
+---
+
+#### `WalletManager.updateWalletInfo()`
+**Purpose**: Update all wallet information (comprehensive).
+
+**Logic**:
+1. Detects wallet type
+2. Checks if wallet is connected
+3. Gets wallet address if connected
+4. Gets chain name if connected
+5. Determines if user is Web3 user (has wallet installed)
+6. Stores all fields in sessionData (flattened)
+
+**Stores on sessionData**:
+- `wallet_address` - Connected wallet address (or null)
+- `wallet_type` - Wallet name (e.g., "MetaMask")
+- `chain_name` - Chain name (e.g., "Ethereum Mainnet")
+- `is_web3_user` - Boolean (true if wallet installed, even if not connected)
+- `wallet_connected` - Boolean (true only if wallet is connected)
+
+**Returns**: Promise that resolves to wallet info object or null on error
+
+**When to Use**:
+- On SDK initialization
+- After wallet connection
+- On account change events
+- On chain change events
+- Before sending data to backend
+
+**Example**:
+```javascript
+const walletInfo = await WalletManager.updateWalletInfo();
+// Returns: {
+//   wallet_address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
+//   wallet_type: "MetaMask",
+//   chain_name: "Ethereum Mainnet",
+//   is_web3_user: true,
+//   wallet_connected: true
+// }
+```
+
+---
+
+#### `WalletManager.setupEventListeners()`
+**Purpose**: Setup wallet event listeners for real-time tracking.
+
+**Logic**:
+- Listens for `accountsChanged` event (wallet connect/disconnect, account switch)
+- Listens for `chainChanged` event (network switch)
+- Updates wallet info automatically on events
+- Handles wallet disconnection gracefully
+
+**When to Use**:
+- On SDK initialization
+- Should be called once to setup listeners
+
+**Example**:
+```javascript
+WalletManager.setupEventListeners();
+// Now automatically tracks wallet changes
+```
+
+---
+
+#### `WalletManager.initialize()`
+**Purpose**: Initialize wallet detection and tracking.
+
+**Logic**:
+1. Calls `updateWalletInfo()` (non-blocking, initial detection)
+2. Calls `setupEventListeners()` (setup real-time tracking)
+
+**When to Use**:
+- On SDK initialization
+- Should be called early but doesn't block other operations
+
+**Example**:
+```javascript
+await WalletManager.initialize();
+// Detects wallet, sets up listeners, tracks changes
+```
+
+---
+
+### Wallet Detection Flow
+
+```
+1. SDK Initialization
+   ↓
+2. WalletManager.initialize()
+   ↓
+3. Check EIP-6963 providers (modern standard)
+   ↓
+4. Check window.ethereum wallet patterns (30+ wallets)
+   ↓
+5. Check global wallet objects
+   ↓
+6. Detect wallet type
+   ↓
+7. Check connection status (non-intrusive)
+   ↓
+8. Get wallet address (if connected)
+   ↓
+9. Get chain ID and convert to chain name
+   ↓
+10. Store all fields in sessionData
+   ↓
+11. Setup event listeners (accountsChanged, chainChanged)
+   ↓
+12. Real-time tracking active
+```
+
+---
+
+### Key Features
+
+✅ **Non-Intrusive Detection**: Never prompts user for wallet connection
+✅ **EIP-6963 Support**: Modern multi-wallet detection standard
+✅ **30+ Wallet Support**: Comprehensive EVM wallet detection
+✅ **40+ Chain Support**: Recognizes all major EVM chains
+✅ **Real-Time Tracking**: Automatically updates on wallet events
+✅ **Error Handling**: Graceful fallbacks on errors
+✅ **Flattened Storage**: All fields stored directly on sessionData
+
+---
+
+### Reusability
+
+✅ **WalletManager.detectWalletType()**: Reusable for detecting wallet anywhere.
+
+✅ **WalletManager.getChainNameFromId()**: Reusable for chain ID to name conversion.
+
+✅ **WalletManager.updateWalletInfo()**: Reusable for updating wallet state.
+
+✅ **WalletManager.initialize()**: Reusable for initialization.
+
+---
+
+## Section 10: Interaction Management
+
+### Purpose
+Single source of truth for interaction tracking and management. Handles all user interactions (clicks, forms, scroll, hover, etc.) with automatic timestamping, categorization, and chronological sorting.
+
+### Why It Matters
+- Centralized interaction tracking
+- Consistent data structure
+- Single place to fix interaction bugs
+- Prevents repeating interactions
+- Automatic timestamping and categorization
+- Immediate session storage updates
+
+### InteractionManager Object
+
+#### Interaction Categories (19 Categories)
+
+**User Actions:**
+- `clicks` - Click events
+- `hoverEvents` - Hover/mouseover events
+- `touchEvents` - Touch events (mobile)
+- `keyboardEvents` - Keyboard input events
+- `copyPasteEvents` - Copy/paste events
+- `contextMenuEvents` - Right-click context menu events
+- `dragDropEvents` - Drag and drop events
+
+**Form Interactions:**
+- `formInteractions` - General form interactions
+- `formSubmissions` - Form submission events
+- `fieldChanges` - Form field value changes
+- `validationErrors` - Form validation errors
+- `formAnalytics` - Form analytics data
+
+**Media & Content:**
+- `mediaInteractions` - Video/audio player interactions
+
+**Navigation & Scrolling:**
+- `scrollEvents` - Scroll events
+- `focusEvents` - Focus/blur events
+- `windowEvents` - Window resize, visibility, etc.
+
+**Performance & Errors:**
+- `performanceEvents` - Performance metrics
+- `errorEvents` - JavaScript errors
+- `networkEvents` - Network request events
+
+---
+
+#### `InteractionManager.initialize()`
+**Purpose**: Initialize interactions structure.
+
+**Logic**:
+- Creates empty interactions object with all 19 categories
+- Sets `totalInteractions` to 0
+- Initializes all category arrays as empty arrays
+
+**When to Use**:
+- On SDK initialization
+- When interactions need to be reset
+- Before adding interactions
+
+**Example**:
+```javascript
+InteractionManager.initialize();
+// Creates empty interactions structure
+```
+
+---
+
+#### `InteractionManager.add(category, interactionData)`
+**Purpose**: Add interaction to appropriate category.
+
+**Logic**:
+1. Ensures interactions are initialized
+2. Validates category
+3. Adds timestamp if not provided
+4. Adds to specific category array
+5. Updates total interactions count
+6. Updates session activity
+7. Immediately updates session storage
+
+**Parameters**:
+- `category` - Interaction category (e.g., 'clicks', 'formInteractions')
+- `interactionData` - Interaction data object (can include any fields)
+
+**Interaction Data Structure**:
+```javascript
+{
+  timestamp: "2024-12-15T10:30:00.000Z",  // Auto-added if not provided
+  elementId: "button-123",                 // Optional: Element identifier
+  target: "button",                         // Optional: Target element
+  selector: "#submit-btn",                 // Optional: CSS selector
+  // ... any other fields specific to interaction type
+}
+```
+
+**When to Use**:
+- When tracking any user interaction
+- Called by event trackers (Section 14)
+- For custom interaction tracking
+
+**Example**:
+```javascript
+// Track a click
+InteractionManager.add('clicks', {
+  elementId: 'submit-button',
+  target: 'button',
+  selector: '#submit-btn',
+  x: 100,
+  y: 200
+});
+
+// Track a form submission
+InteractionManager.add('formSubmissions', {
+  formId: 'contact-form',
+  fields: ['name', 'email', 'message'],
+  success: true
+});
+```
+
+---
+
+#### `InteractionManager.updateTotalCount()`
+**Purpose**: Update total interactions count.
+
+**Logic**:
+- Calculates total from all category arrays
+- Updates `sessionData.interactions.totalInteractions`
+
+**When to Use**:
+- Automatically called by `add()`
+- After manual interaction modifications
+- After deduplication
+
+---
+
+#### `InteractionManager.updateSessionStorage()`
+**Purpose**: Update session storage with interactions.
+
+**Logic**:
+- Loads current session from storage
+- Updates interactions in session data
+- Saves session back to storage
+
+**When to Use**:
+- Automatically called by `add()`
+- After bulk interaction updates
+
+---
+
+#### `InteractionManager.getChronological()`
+**Purpose**: Get all interactions sorted chronologically.
+
+**Logic**:
+1. Collects all interactions from all categories
+2. Adds category identifiers (`category`, `originalCategory`)
+3. Sorts by timestamp (oldest first)
+
+**Returns**: Array of interactions sorted by timestamp
+
+**Interaction Structure in Chronological Array**:
+```javascript
+[
+  {
+    timestamp: "2024-12-15T10:30:00.000Z",
+    category: "click",                    // Normalized category name
+    originalCategory: "clicks",           // Original category array name
+    elementId: "button-123",
+    // ... other interaction data
+  },
+  {
+    timestamp: "2024-12-15T10:30:05.000Z",
+    category: "scrollEvent",
+    originalCategory: "scrollEvents",
+    scrollY: 100,
+    // ... other interaction data
+  }
+]
+```
+
+**When to Use**:
+- Before sending data to backend
+- For analytics/reporting
+- For chronological interaction analysis
+
+**Example**:
+```javascript
+const chronological = InteractionManager.getChronological();
+// Returns: Array of all interactions sorted by time
+```
+
+---
+
+#### `InteractionManager.getChronologicalForBackend()`
+**Purpose**: Get chronological interactions for backend.
+
+**Logic**:
+- Gets chronological array via `getChronological()`
+- Returns both chronological and categorized structures
+
+**Returns**: Object with:
+```javascript
+{
+  chronological: [...],      // Sorted array
+  categorized: {...}         // Original categorized structure
+}
+```
+
+**When to Use**:
+- When sending data to backend
+- When both formats are needed
+
+**Example**:
+```javascript
+const interactions = InteractionManager.getChronologicalForBackend();
+// Returns: { chronological: [...], categorized: {...} }
+```
+
+---
+
+#### `InteractionManager.deduplicate()`
+**Purpose**: Remove duplicate interactions.
+
+**Logic**:
+- Compares interactions by timestamp, category, and element identifier
+- Keeps first occurrence of duplicates
+- Updates total count after deduplication
+- Updates session storage
+
+**Deduplication Key**: `${timestamp}_${category}_${elementId}`
+
+**When to Use**:
+- Before sending data to backend
+- After bulk interaction imports
+- To clean up duplicate events
+
+**Example**:
+```javascript
+InteractionManager.deduplicate();
+// Removes duplicate interactions
+```
+
+---
+
+#### `InteractionManager.getByCategory(category)`
+**Purpose**: Get interactions by category.
+
+**Parameters**: `category` - Interaction category name
+
+**Returns**: Array of interactions for that category
+
+**When to Use**:
+- When analyzing specific interaction types
+- For category-specific analytics
+
+**Example**:
+```javascript
+const clicks = InteractionManager.getByCategory('clicks');
+// Returns: Array of all click interactions
+```
+
+---
+
+#### `InteractionManager.getTotalCount()`
+**Purpose**: Get total interactions count.
+
+**Returns**: Total number of interactions across all categories
+
+**When to Use**:
+- For analytics/reporting
+- To check interaction volume
+
+**Example**:
+```javascript
+const total = InteractionManager.getTotalCount();
+// Returns: 42 (total interactions)
+```
+
+---
+
+#### `InteractionManager.clear()`
+**Purpose**: Clear all interactions.
+
+**Logic**:
+- Resets all category arrays to empty
+- Sets total count to 0
+- Updates session storage
+
+**When to Use**:
+- For testing/reset
+- When starting fresh session
+
+**Example**:
+```javascript
+InteractionManager.clear();
+// Clears all interactions
+```
+
+---
+
+### Reusability
+
+✅ **InteractionManager.add()**: Reusable for tracking any interaction type.
+
+✅ **InteractionManager.getChronological()**: Reusable for chronological analysis.
+
+✅ **InteractionManager.deduplicate()**: Reusable for cleaning duplicate interactions.
+
+✅ **InteractionManager.getByCategory()**: Reusable for category-specific queries.
+
+---
+
+## Section 11: Page Visit Management
+
+### Purpose
+Track and manage page visits with durations. Handles entry/exit pages, mount/unmount times, and page duration calculations.
+
+### Why It Matters
+- Centralized page visit tracking
+- Accurate page duration calculations
+- Proper entry/exit page tracking
+- Single place to fix page visit bugs
+- Prevents duplicate page visits
+
+### PageVisitManager Object
+
+#### `PageVisitManager.track(path, timestamp)`
+**Purpose**: Track a page visit.
+
+**Logic**:
+1. Ensures session ID exists
+2. Gets current path and URL
+3. Checks if page already visited (prevents duplicates)
+4. Creates page visit entry with mount time
+5. Updates previous page's unmount time and duration
+6. Sets entry page if first page
+7. Updates pagesViewed count
+8. Calculates session duration
+9. Updates session activity
+10. Saves to storage
+
+**Parameters**:
+- `path` (optional) - Page path. Defaults to `window.location.pathname + search`
+- `timestamp` (optional) - Page visit timestamp. Defaults to current time
+
+**Stores in `visited_pages` array**:
+```javascript
+{
+  path: "/home",
+  timestamp: "2024-12-15T10:30:00.000Z",
+  duration: 180,
+  isEntry: true,
+  isExit: false,
+  mountTime: 1702641000000,  // Milliseconds
+  unmountTime: 1702641180000  // Milliseconds
+}
+```
+
+**When to Use**:
+- On page load
+- On SPA navigation
+- When tracking page visits
+
+**Example**:
+```javascript
+PageVisitManager.track();
+// Tracks current page visit
+```
+
+---
+
+#### `PageVisitManager.trackUnmount()`
+**Purpose**: Track page unmount (when user navigates away).
+
+**Logic**:
+- Finds current page in page visits
+- Sets unmount time
+- Calculates page duration using DurationManager
+- Recalculates session duration
+- Saves to storage
+
+**When to Use**:
+- Automatically called on `beforeunload` event
+- Automatically called on `visibilitychange` event (SPA navigation)
+- Can be called manually if needed
+
+**Example**:
+```javascript
+PageVisitManager.trackUnmount();
+// Tracks current page unmount
+```
+
+---
+
+#### `PageVisitManager.getAll()`
+**Purpose**: Get all page visits.
+
+**Returns**: Array of all page visits
+
+**When to Use**:
+- For analytics/reporting
+- To check page visit history
+
+**Example**:
+```javascript
+const visits = PageVisitManager.getAll();
+// Returns: Array of all page visits
+```
+
+---
+
+#### `PageVisitManager.getEntryPage()`
+**Purpose**: Get entry page (first page visited).
+
+**Returns**: First page visit object or null
+
+**When to Use**:
+- To get entry page information
+- For analytics
+
+**Example**:
+```javascript
+const entryPage = PageVisitManager.getEntryPage();
+// Returns: First page visit or null
+```
+
+---
+
+#### `PageVisitManager.getExitPage()`
+**Purpose**: Get exit page (last page visited).
+
+**Returns**: Last page visit object or null
+
+**When to Use**:
+- To get exit page information
+- For analytics
+
+**Example**:
+```javascript
+const exitPage = PageVisitManager.getExitPage();
+// Returns: Last page visit or null
+```
+
+---
+
+#### `PageVisitManager.initialize()`
+**Purpose**: Initialize page visit tracking.
+
+**Logic**:
+- Tracks initial page visit
+- Sets up `beforeunload` listener for page unmount
+- Sets up `visibilitychange` listener for SPA navigation
+
+**When to Use**:
+- On SDK initialization
+- Should be called early in initialization flow
+
+**Example**:
+```javascript
+PageVisitManager.initialize();
+// Tracks initial page and sets up listeners
+```
+
+---
+
+### Reusability
+
+✅ **PageVisitManager.track()**: Reusable for tracking any page visit.
+
+✅ **PageVisitManager.trackUnmount()**: Reusable for tracking page unmount.
+
+✅ **PageVisitManager.getAll()**: Reusable for getting page visit data.
+
+---
+
+## Section 12: Data Transformation/Normalization
+
+### Purpose
+Transform sessionData from internal format (camelCase) to backend format (snake_case). Handles data normalization, field mapping, and ensures all required fields are present.
+
+### Why It Matters
+- Consistent data format for backend
+- Single place to handle data transformation
+- Prevents missing fields errors
+- Handles data shape normalization
+- Ensures proper timestamp formatting
+
+### DataTransformer Object
+
+#### `DataTransformer.normalizeShape(raw)`
+**Purpose**: Normalize client session shape.
+
+**Logic**:
+1. Handles field aliases:
+   - `pageViews` → `pagesViewed`
+   - `visitedPages` → `pageVisits`
+   - `id` → `sessionId`
+2. Ensures arrays exist (`pageVisits`, `visited_pages`, `interactions`)
+3. Normalizes timestamps to ISO strings
+4. Normalizes page visit timestamps
+
+**Parameters**: `raw` - Raw session data object
+
+**Returns**: Normalized session data object
+
+**When to Use**:
+- Before transforming to backend format
+- When loading data from storage
+- To ensure consistent data shape
+
+**Example**:
+```javascript
+const normalized = DataTransformer.normalizeShape(rawData);
+// Returns: Normalized data with aliases fixed and timestamps formatted
+```
+
+---
+
+#### `DataTransformer.toBackendFormat(data)`
+**Purpose**: Transform sessionData to backend-compatible format.
+
+**Logic**:
+1. Normalizes data shape using `normalizeShape()`
+2. Maps camelCase fields to snake_case
+3. Ensures `id` and `session_id` both set to sessionId value
+4. Flattens nested structures
+5. Removes internal-only fields (`utmData`, `isFirstPage`, `locationData`)
+6. Adds chronological interactions
+7. Ensures all required fields are present (even if null)
+
+**Parameters**: `data` (optional) - Session data object. Defaults to `sessionData`.
+
+**Returns**: Transformed object ready for backend
+
+**Field Mapping**:
+- `sessionId` → `id` and `session_id` (both set to same value)
+- `siteId` → `site_id`
+- `userId` → `user_id`
+- `startTime` → `start_time`
+- `pagesViewed` → `pages_viewed`
+- `isBounce` → `is_bounce`
+- `entryPage` → `entry_page`
+- `exitPage` → `exit_page`
+- All location, browser, device, wallet, UTM fields already in snake_case
+
+**Removed Fields**:
+- `utmData` (internal object, already flattened to utm_* fields)
+- `isFirstPage` (internal tracking flag)
+- `locationData` (internal object, already flattened)
+
+**Example**:
+```javascript
+// Internal format
+{
+  sessionId: "abc-123",
+  pagesViewed: 3,
+  isBounce: false,
+  startTime: "2024-12-15T10:30:00.000Z"
+}
+
+// Backend format
+{
+  id: "abc-123",              // Same as session_id (PostgreSQL auto-generates)
+  session_id: "abc-123",
+  pages_viewed: 3,
+  is_bounce: false,
+  start_time: "2024-12-15T10:30:00.000Z",
+  // ... all other fields in snake_case
+  interactions: {
+    ...interactions,
+    chronological: [...]  // Added chronological interactions
+  }
+}
+```
+
+**When to Use**:
+- Before sending data to backend API
+- When preparing session data for storage
+- For data export/analytics
+
+**Example**:
+```javascript
+const backendData = DataTransformer.toBackendFormat();
+// Returns: Transformed data ready for backend
+```
+
+---
+
+#### `DataTransformer.toOverviewFormat(data)`
+**Purpose**: Transform for overview API (simplified format).
+
+**Logic**:
+- Creates simplified format for overview/analytics endpoint
+- Includes essential fields only
+- Formats data for overview payload
+
+**Parameters**: `data` (optional) - Session data object. Defaults to `sessionData`.
+
+**Returns**: Transformed object for overview API
+
+**When to Use**:
+- When sending data to overview/analytics endpoint
+- For summary/aggregated data
+
+**Example**:
+```javascript
+const overviewData = DataTransformer.toOverviewFormat();
+// Returns: Simplified format for overview API
+```
+
+---
+
+### Reusability
+
+✅ **DataTransformer.normalizeShape()**: Reusable for normalizing any session data.
+
+✅ **DataTransformer.toBackendFormat()**: Reusable for transforming data to backend format.
+
+✅ **DataTransformer.toOverviewFormat()**: Reusable for overview/analytics data.
+
+---
+
+## Section 13: API Communication
+
+### Purpose
+Unified API client for all backend communication. Handles sending session data, overview data, custom events, and UTM events with proper error handling and retry logic.
+
+### Why It Matters
+- Single place to handle all API communication
+- Consistent error handling
+- Retry logic for reliability
+- Proper use of sendBeacon vs fetch
+- Debouncing to reduce network noise
+
+### APIClient Object
+
+#### `APIClient.determineTrafficSource()`
+**Purpose**: Determine traffic source for overview data.
+
+**Logic**:
+1. Checks UTM source (highest priority)
+2. Checks external referrer
+3. Defaults to "direct"
+
+**Returns**: Traffic source string
+
+**When to Use**:
+- When building overview payload
+- For traffic source analysis
+
+**Example**:
+```javascript
+const source = APIClient.determineTrafficSource();
+// Returns: "google", "example.com", or "direct"
+```
+
+---
+
+#### `APIClient.send(endpoint, data, options)`
+**Purpose**: Send data to API endpoint (unified method).
+
+**Logic**:
+1. Transforms data using DataTransformer if needed
+2. Uses sendBeacon if `useBeacon` is true (for beforeunload)
+3. Uses fetch with keepalive for regular sends
+4. Handles errors gracefully
+5. Retries on failure (if retries > 0)
+
+**Parameters**:
+- `endpoint` - API endpoint URL
+- `data` - Data to send
+- `options` (optional) - Configuration object:
+  - `useBeacon` (default: false) - Use sendBeacon instead of fetch
+  - `retries` (default: 0) - Number of retry attempts
+  - `timeout` (default: 5000) - Request timeout in milliseconds
+  - `transform` (default: true) - Transform data before sending
+
+**Returns**: Promise that resolves on success
+
+**When to Use**:
+- For all API communication
+- When sending any data to backend
+
+**Example**:
+```javascript
+// Regular send with retries
+await APIClient.send(CONFIG.API.TRACK, payload, {
+  retries: 2,
+  timeout: 5000
+});
+
+// SendBeacon for beforeunload
+await APIClient.send(CONFIG.API.OVERVIEW, payload, {
+  useBeacon: true,
+  retries: 0
+});
+```
+
+---
+
+#### `APIClient.sendSessionData(data)`
+**Purpose**: Send session data to TRACK endpoint.
+
+**Logic**:
+1. Ensures session ID exists
+2. Transforms data using DataTransformer.toBackendFormat()
+3. Sends to TRACK endpoint
+4. Retries on failure (2 attempts)
+
+**Parameters**: `data` (optional) - Session data object. Defaults to `sessionData`.
+
+**When to Use**:
+- On session initialization
+- Periodically during session (via interval)
+- On session updates
+
+**Example**:
+```javascript
+await APIClient.sendSessionData();
+// Sends current session data to TRACK endpoint
+```
+
+---
+
+#### `APIClient.sendOverviewData(useBeacon)`
+**Purpose**: Send overview data to OVERVIEW endpoint.
+
+**Logic**:
+1. Recalculates session duration
+2. Updates bounce status
+3. Builds overview payload with user journey
+4. Determines traffic source
+5. Sends to OVERVIEW endpoint
+
+**Parameters**: `useBeacon` (optional, default: false) - Use sendBeacon instead of fetch
+
+**Overview Payload Structure**:
+```javascript
+{
+  siteId: SITE_ID,
+  userId: userId,
+  sessionId: sessionId,
+  sessionStartDate: "2024-12-15",
+  totalSessions: 1,
+  bounceSessions: 0,
+  totalPagesVisited: 3,
+  isBounce: false,
+  userJourney: {
+    [userId]: {
+      currentSessionId: sessionId,
+      country: "US",
+      isWeb3User: true,
+      walletAddress: "0x...",
+      walletConnected: true,
+      visitTimes: [Date],
+      walletConnectedInVisit: [boolean],
+      visitDuration: [number], // Seconds
+      sessionPaths: [[paths]], // Array of arrays
+      trafficSource: "google"
+    }
+  }
+}
+```
+
+**When to Use**:
+- At session end
+- Periodically (debounced)
+- On beforeunload (with useBeacon: true)
+
+**Example**:
+```javascript
+// Regular send
+await APIClient.sendOverviewData();
+
+// Beforeunload send
+await APIClient.sendOverviewData(true);
+```
+
+---
+
+#### `APIClient.scheduleSendOverview(debounceMs, useBeacon)`
+**Purpose**: Schedule overview data send (debounced).
+
+**Logic**:
+- Clears existing timeout if any
+- Sets new timeout to send overview data
+- Debounces to reduce network noise
+
+**Parameters**:
+- `debounceMs` (optional, default: 10000) - Debounce time in milliseconds
+- `useBeacon` (optional, default: false) - Use sendBeacon
+
+**When to Use**:
+- During session tracking interval
+- To debounce overview sends
+
+**Example**:
+```javascript
+APIClient.scheduleSendOverview(10000, false);
+// Schedules overview send in 10 seconds
+```
+
+---
+
+#### `APIClient.sendCustomEvent(eventKey, eventName, eventType, parameters)`
+**Purpose**: Send custom event to CUSTOM_EVENTS endpoint.
+
+**Logic**:
+1. Validates eventKey and eventName
+2. Gets location data (non-blocking)
+3. Updates session activity
+4. Updates wallet info (non-blocking)
+5. Converts parameters to array format
+6. Builds custom event payload
+7. Sends to CUSTOM_EVENTS endpoint
+
+**Parameters**:
+- `eventKey` - Event key/identifier
+- `eventName` - Event name
+- `eventType` - Event type
+- `parameters` (optional) - Event parameters (object or array)
+
+**Custom Event Payload Structure**:
+```javascript
+{
+  siteId: SITE_ID,
+  eventKey: "evt_123",
+  eventName: "Button Click",
+  eventType: "click",
+  eventDescription: "",
+  parameters: [{ name: "buttonId", value: "submit", paramType: "string" }],
+  pagePath: "/home",
+  sessionIds: [sessionId],
+  userIds: [userId],
+  datetimes: ["2024-12-15T10:30:00.000Z"],
+  geography: [{ city, country, region, timezone }],
+  source: ["google"],
+  web3user: [true],
+  walletAddress: ["0x..."]
+}
+```
+
+**When to Use**:
+- When tracking custom events
+- For user-defined events
+
+**Example**:
+```javascript
+await APIClient.sendCustomEvent(
+  "evt_123",
+  "Button Click",
+  "click",
+  { buttonId: "submit", page: "/home" }
+);
+```
+
+---
+
+#### `APIClient.sendUTMEvent()`
+**Purpose**: Send UTM event to UTM_EVENTS endpoint.
+
+**Logic**:
+1. Extracts UTM parameters
+2. Only sends if UTM parameters exist
+3. Builds UTM event payload
+4. Sends to UTM_EVENTS endpoint
+
+**When to Use**:
+- On page load with UTM parameters
+- For UTM campaign tracking
+
+**Example**:
+```javascript
+await APIClient.sendUTMEvent();
+// Sends UTM data if UTM parameters exist
+```
+
+---
+
+### Error Handling
+
+**Retry Logic**:
+- Automatic retries on failure (configurable)
+- Exponential backoff (1 second delay)
+- Maximum retry attempts configurable
+
+**sendBeacon vs fetch**:
+- **sendBeacon**: Used for beforeunload (fire-and-forget, no response)
+- **fetch**: Used for regular sends (with keepalive, can retry)
+
+**Error Logging**:
+- Comprehensive error logging
+- Network error detection
+- CORS error detection
+- Ad blocker detection
+
+---
+
+### Reusability
+
+✅ **APIClient.send()**: Reusable for sending data to any endpoint.
+
+✅ **APIClient.sendSessionData()**: Reusable for session tracking.
+
+✅ **APIClient.sendOverviewData()**: Reusable for overview/analytics.
+
+✅ **APIClient.sendCustomEvent()**: Reusable for custom event tracking.
+
+---
+
+## Section 14: Event Trackers
+
+### Purpose
+Individual tracking modules for different event types. All trackers listen to DOM events and use `InteractionManager.add()` to store interactions.
+
+### Why It Matters
+- Modular tracking (can enable/disable individual trackers)
+- Single source of truth for interaction storage
+- Easy to add new trackers
+- Consistent interaction data structure
+- Error handling prevents tracker failures from breaking SDK
+
+### EventTrackers Object
+
+All trackers are methods of the `EventTrackers` object. Each tracker:
+- Listens to specific DOM events
+- Extracts relevant data
+- Uses `InteractionManager.add()` to store interactions
+- Handles errors gracefully
+
+---
+
+#### `EventTrackers.startClickTracking()`
+**Purpose**: Track click events on interactive elements.
+
+**Logic**:
+1. Listens to click events on document body
+2. Finds closest interactive element (a, button, [role="button"], [data-cryptique-id])
+3. Extracts element data (tagName, id, className, href, etc.)
+4. Captures click coordinates
+5. Stores interaction using `InteractionManager.add('clicks', ...)`
+
+**Tracks**:
+- Click coordinates (x, y)
+- Element details (tagName, id, className, href, aria-label, role)
+- Path where click occurred
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startClickTracking();
+// Now tracking all clicks on interactive elements
+```
+
+---
+
+#### `EventTrackers.startFormTracking()`
+**Purpose**: Track form interactions (submissions, field changes, focus/blur, validation errors).
+
+**Logic**:
+1. Listens to form submit events
+2. Listens to input/change events on form fields
+3. Listens to focus/blur events on form fields
+4. Listens to invalid events for validation errors
+5. Stores interactions using `InteractionManager.add()`
+
+**Tracks**:
+- Form submissions (formId, formAction, formMethod, fieldCount)
+- Field changes (fieldType, fieldName, fieldId, valueLength)
+- Focus/blur events (fieldType, fieldName, fieldId, formId)
+- Validation errors (fieldType, fieldName, validationMessage)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startFormTracking();
+// Now tracking all form interactions
+```
+
+---
+
+#### `EventTrackers.startMediaTracking()`
+**Purpose**: Track media interactions (video play/pause, image clicks/loads).
+
+**Logic**:
+1. Listens to play/pause events on video elements
+2. Listens to click events on image elements
+3. Tracks existing images on page load
+4. Stores interactions using `InteractionManager.add('mediaInteractions', ...)`
+
+**Tracks**:
+- Video play/pause (mediaType, mediaId, mediaSrc, currentTime)
+- Image clicks (imageId, imageSrc, imageAlt, imageWidth, imageHeight)
+- Image loads (imageWidth, imageHeight)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startMediaTracking();
+// Now tracking all media interactions
+```
+
+---
+
+#### `EventTrackers.startScrollTracking()`
+**Purpose**: Track scroll events with debouncing.
+
+**Logic**:
+1. Listens to scroll events
+2. Debounces scroll events (150ms)
+3. Calculates scroll position and percentage
+4. Only tracks if scroll position changed significantly (>50px)
+5. Stores interactions using `InteractionManager.add('scrollEvents', ...)`
+
+**Tracks**:
+- Scroll position (scrollY, scrollPercent)
+- Window and document dimensions
+- Path where scroll occurred
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startScrollTracking();
+// Now tracking scroll events (debounced)
+```
+
+---
+
+#### `EventTrackers.startHoverTracking()`
+**Purpose**: Track hover events on interactive elements.
+
+**Logic**:
+1. Listens to mouseenter events
+2. Only tracks hovers longer than 200ms
+3. Tracks hover duration
+4. Updates hover duration on mouseleave
+5. Stores interactions using `InteractionManager.add('hoverEvents', ...)`
+
+**Tracks**:
+- Element details (elementType, elementId, elementClass)
+- Hover duration (updated on mouseleave)
+- Path where hover occurred
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startHoverTracking();
+// Now tracking hover events (200ms threshold)
+```
+
+---
+
+#### `EventTrackers.startKeyboardTracking()`
+**Purpose**: Track keyboard shortcuts and special keys.
+
+**Logic**:
+1. Listens to keydown events
+2. Tracks significant keys (Enter, Escape, Tab, Arrows, F-keys, etc.)
+3. Tracks modifier key combinations (Ctrl, Alt, Shift, Meta)
+4. Stores interactions using `InteractionManager.add('keyboardEvents', ...)`
+
+**Tracks**:
+- Key pressed (key, keyCode)
+- Modifier keys (ctrlKey, altKey, shiftKey, metaKey)
+- Target element (tagName, id, className)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startKeyboardTracking();
+// Now tracking keyboard shortcuts
+```
+
+---
+
+#### `EventTrackers.startCopyPasteTracking()`
+**Purpose**: Track copy and paste actions.
+
+**Logic**:
+1. Listens to copy events
+2. Listens to paste events
+3. Extracts selected text (copy) or target element (paste)
+4. Stores interactions using `InteractionManager.add('copyPasteEvents', ...)`
+
+**Tracks**:
+- Copy actions (selectedText, target element)
+- Paste actions (target element)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startCopyPasteTracking();
+// Now tracking copy/paste actions
+```
+
+---
+
+#### `EventTrackers.startContextMenuTracking()`
+**Purpose**: Track right-click context menu usage.
+
+**Logic**:
+1. Listens to contextmenu events
+2. Captures click coordinates
+3. Extracts target element details
+4. Stores interactions using `InteractionManager.add('contextMenuEvents', ...)`
+
+**Tracks**:
+- Target element (tagName, id, className)
+- Click coordinates (x, y)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startContextMenuTracking();
+// Now tracking context menu usage
+```
+
+---
+
+#### `EventTrackers.startDragDropTracking()`
+**Purpose**: Track drag and drop operations.
+
+**Logic**:
+1. Listens to dragstart events
+2. Listens to drop events
+3. Extracts dataTransfer information
+4. Stores interactions using `InteractionManager.add('dragDropEvents', ...)`
+
+**Tracks**:
+- Drag start (target element, dataTransfer types, files count)
+- Drop action (target element, dataTransfer types, files count)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startDragDropTracking();
+// Now tracking drag/drop operations
+```
+
+---
+
+#### `EventTrackers.startTouchTracking()`
+**Purpose**: Track touch events for mobile devices.
+
+**Logic**:
+1. Listens to touchstart events
+2. Listens to touchmove events
+3. Listens to touchend events
+4. Extracts touch coordinates and count
+5. Stores interactions using `InteractionManager.add('touchEvents', ...)`
+
+**Tracks**:
+- Touch start (touches count, coordinates, target element)
+- Touch move (touches count)
+- Touch end (touches count)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startTouchTracking();
+// Now tracking touch events
+```
+
+---
+
+#### `EventTrackers.startWindowTracking()`
+**Purpose**: Track window resize, orientation changes, focus/blur.
+
+**Logic**:
+1. Listens to resize events (debounced 250ms)
+2. Listens to orientationchange events
+3. Listens to window focus/blur events
+4. Extracts window dimensions and focused element
+5. Stores interactions using `InteractionManager.add('windowEvents', ...)`
+
+**Tracks**:
+- Window resize (dimensions, focused element)
+- Orientation change (orientation, focused element)
+- Window focus/blur (focused element)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startWindowTracking();
+// Now tracking window events
+```
+
+---
+
+#### `EventTrackers.startPerformanceTracking()`
+**Purpose**: Track page load performance metrics.
+
+**Logic**:
+1. Listens to window load event
+2. Waits 1 second for all resources to load
+3. Extracts performance metrics (loadTime, domContentLoaded, firstPaint)
+4. Stores interactions using `InteractionManager.add('performanceEvents', ...)`
+
+**Tracks**:
+- Load time (navigationStart to loadEventEnd)
+- DOM content loaded time
+- First paint time
+- First contentful paint time
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startPerformanceTracking();
+// Now tracking page load performance
+```
+
+---
+
+#### `EventTrackers.startErrorTracking()`
+**Purpose**: Track JavaScript errors and unhandled promise rejections.
+
+**Logic**:
+1. Listens to window error events
+2. Listens to unhandledrejection events
+3. Extracts error details (message, filename, line, column, stack)
+4. Stores interactions using `InteractionManager.add('errorEvents', ...)`
+
+**Tracks**:
+- JavaScript errors (message, filename, lineno, colno, stack, errorElement)
+- Unhandled promise rejections (message, error)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startErrorTracking();
+// Now tracking JavaScript errors
+```
+
+---
+
+#### `EventTrackers.startNetworkTracking()`
+**Purpose**: Track network errors (fetch and XMLHttpRequest).
+
+**Logic**:
+1. Wraps window.fetch to intercept requests
+2. Wraps XMLHttpRequest.open and send
+3. Only tracks error status codes (4xx, 5xx) and network errors
+4. Extracts error details (url, method, status, error message, duration)
+5. Stores interactions using `InteractionManager.add('networkEvents', ...)`
+
+**Tracks**:
+- API errors (url, method, status, error, duration)
+- Network errors (url, method, status: 0, error, duration)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startNetworkTracking();
+// Now tracking network errors (4xx, 5xx, network failures)
+```
+
+---
+
+#### `EventTrackers.startAdvancedFormTracking()`
+**Purpose**: Track form completion rates and abandonment.
+
+**Logic**:
+1. Tracks form start time on first field focus
+2. Tracks form completion time on submit
+3. Calculates completion time
+4. Stores interactions using `InteractionManager.add('formAnalytics', ...)`
+
+**Tracks**:
+- Form completion (formId, completionTime, fieldCount)
+
+**When to Use**: Automatically called during initialization.
+
+**Example**:
+```javascript
+EventTrackers.startAdvancedFormTracking();
+// Now tracking form analytics
+```
+
+---
+
+#### `EventTrackers.initialize()`
+**Purpose**: Initialize all event trackers.
+
+**Logic**:
+- Calls all tracker start methods in sequence
+- All trackers are started automatically
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+EventTrackers.initialize();
+// Starts all event trackers
+```
+
+---
+
+### Tracker Categories
+
+Each tracker stores interactions in specific categories:
+- `clicks` - Click events
+- `formSubmissions` - Form submissions
+- `fieldChanges` - Form field changes
+- `focusEvents` - Focus/blur events
+- `validationErrors` - Form validation errors
+- `mediaInteractions` - Video/audio/image interactions
+- `scrollEvents` - Scroll events
+- `hoverEvents` - Hover events
+- `keyboardEvents` - Keyboard shortcuts
+- `copyPasteEvents` - Copy/paste actions
+- `contextMenuEvents` - Context menu usage
+- `dragDropEvents` - Drag/drop operations
+- `touchEvents` - Touch events
+- `windowEvents` - Window events (resize, orientation, focus/blur)
+- `performanceEvents` - Performance metrics
+- `errorEvents` - JavaScript errors
+- `networkEvents` - Network errors
+- `formAnalytics` - Form analytics
+
+---
+
+### Error Handling
+
+All trackers have try-catch blocks to prevent failures from breaking the SDK:
+- Errors are logged to console
+- Tracker failures don't affect other trackers
+- SDK continues to function even if a tracker fails
+
+---
+
+### Reusability
+
+✅ **Modular Design**: Each tracker is independent and can be enabled/disabled.
+
+✅ **Consistent API**: All trackers use `InteractionManager.add()` to store interactions.
+
+✅ **Easy to Extend**: Add new trackers by following the same pattern.
+
+✅ **Error Resilient**: Trackers handle errors gracefully without breaking the SDK.
+
+---
+
+## Section 15: Initialization
+
+### Purpose
+Orchestrates all sections in the correct order. Handles initialization, session tracking intervals, beforeunload events, and error recovery.
+
+### Why It Matters
+- Single entry point for SDK initialization
+- Clear initialization order
+- Error recovery and fallbacks
+- Prevents duplicate initialization
+- Handles unsent session data from previous page loads
+
+### Initializer Object
+
+The `Initializer` object contains all initialization functions and orchestrates the SDK startup.
+
+---
+
+#### `Initializer.checkForUnsentData()`
+**Purpose**: Check for unsent session data from previous page loads.
+
+**Logic**:
+1. Checks localStorage for `cryptique_last_session`
+2. Sends stored session data if found
+3. Clears stored data after successful send
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+await Initializer.checkForUnsentData();
+// Sends any unsent session data from previous page load
+```
+
+---
+
+#### `Initializer.initializeSessionData()`
+**Purpose**: Initialize session data structure.
+
+**Logic**:
+1. Gets or creates session ID
+2. Gets or creates user ID
+3. Initializes session data structure
+4. Initializes interactions
+5. Initializes page visits
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+Initializer.initializeSessionData();
+// Initializes all session data structures
+```
+
+---
+
+#### `Initializer.initializeLocation()`
+**Purpose**: Initialize location data (non-blocking).
+
+**Logic**:
+- Starts location fetch asynchronously
+- Doesn't block initialization
+- Errors are non-critical
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+Initializer.initializeLocation();
+// Starts location fetch (non-blocking)
+```
+
+---
+
+#### `Initializer.initializeBrowserDevice()`
+**Purpose**: Initialize browser/device detection.
+
+**Logic**:
+- Calls BrowserDeviceManager.detect()
+- Extracts browser/device information
+- Stores in sessionData
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+Initializer.initializeBrowserDevice();
+// Detects and stores browser/device info
+```
+
+---
+
+#### `Initializer.initializeUTM()`
+**Purpose**: Initialize UTM parameters.
+
+**Logic**:
+- Calls UTMManager.extract()
+- Extracts UTM parameters from URL
+- Stores in sessionData
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+Initializer.initializeUTM();
+// Extracts and stores UTM parameters
+```
+
+---
+
+#### `Initializer.initializeWallet()`
+**Purpose**: Initialize wallet/Web3 detection.
+
+**Logic**:
+- Calls WalletManager.initialize()
+- Detects wallets and chains
+- Sets up wallet event listeners
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+Initializer.initializeWallet();
+// Initializes wallet detection
+```
+
+---
+
+#### `Initializer.trackInitialPage()`
+**Purpose**: Track initial page visit.
+
+**Logic**:
+- Calls PageVisitManager.track()
+- Records page mount time
+- Sets entry page flag
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+Initializer.trackInitialPage();
+// Tracks the initial page visit
+```
+
+---
+
+#### `Initializer.startSessionTracking()`
+**Purpose**: Start session tracking interval.
+
+**Logic**:
+1. Clears any existing interval
+2. Sets up interval (every 15 seconds)
+3. In each interval:
+   - Updates session duration
+   - Updates wallet info (non-blocking)
+   - Updates session activity
+   - Syncs data from storage
+   - Updates bounce status
+   - Saves session to storage
+   - Sends session data
+   - Schedules overview send (debounced)
+
+**Interval**: 15 seconds (CONFIG.INTERVALS.SESSION_TRACKING_MS)
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+Initializer.startSessionTracking();
+// Starts periodic session tracking
+```
+
+---
+
+#### `Initializer.setupBeforeUnload()`
+**Purpose**: Set up beforeunload handler for final data send.
+
+**Logic**:
+1. Listens to beforeunload event
+2. Syncs all data from storage
+3. Tracks page unmount
+4. Updates final session duration
+5. Updates bounce status
+6. Clears pending debounced sends
+7. Sends final overview data (sendBeacon)
+8. Sends final session data (sendBeacon)
+9. Stores backup in localStorage if send fails
+10. Clears tracking interval
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+Initializer.setupBeforeUnload();
+// Sets up beforeunload handler
+```
+
+---
+
+#### `Initializer.sendInitialSessionData()`
+**Purpose**: Send initial session data after initialization.
+
+**Logic**:
+1. Waits 500ms for location data to load
+2. Sends initial session data
+3. Errors are non-critical (will retry in interval)
+
+**When to Use**: Called during SDK initialization.
+
+**Example**:
+```javascript
+await Initializer.sendInitialSessionData();
+// Sends initial session data
+```
+
+---
+
+#### `Initializer.initialize()`
+**Purpose**: Main initialization function that orchestrates all sections.
+
+**Initialization Order**:
+1. Check sessionStorage availability
+2. Check for unsent session data
+3. Initialize session data structure
+4. Initialize location (non-blocking)
+5. Initialize browser/device detection
+6. Initialize UTM parameters
+7. Initialize wallet/Web3 detection
+8. Track initial page visit
+9. Start event trackers
+10. Start session tracking interval
+11. Set up beforeunload handler
+12. Mark SDK as initialized
+13. Send initial session data (non-blocking)
+
+**When to Use**: Called automatically on DOMContentLoaded or immediately if DOM already loaded.
+
+**Example**:
+```javascript
+await Initializer.initialize();
+// Initializes entire SDK
+```
+
+---
+
+### Auto-Initialization
+
+The SDK automatically initializes when:
+- DOM is ready (DOMContentLoaded event)
+- DOM is already loaded (immediate initialization)
+
+**No manual initialization required** - the SDK initializes automatically when the script loads.
+
+---
+
+### Error Handling
+
+All initialization functions have try-catch blocks:
+- Errors in one section don't break other sections
+- Non-critical errors are logged as warnings
+- Critical errors are logged as errors
+- SDK continues to function even if some sections fail
+
+---
+
+### Reusability
+
+✅ **Modular Design**: Each initialization step is independent.
+
+✅ **Error Resilient**: Failures in one section don't break others.
+
+✅ **Auto-Initialization**: SDK initializes automatically.
+
+✅ **Recovery**: Handles unsent session data from previous page loads.
+
+---
+
+## Notes
+
+- All functions are designed to be self-contained and reusable
+- Error handling is built into each function
+- Functions follow consistent naming conventions
+- Documentation is kept in sync with code
+- This guide is a living document - update as you add new functions
+- **Field Naming**: Internal uses camelCase, backend uses snake_case
+- **Transformation**: Data is transformed on send, not stored
+- **Flattening**: All nested objects are flattened before sending to backend
+
+## Notes
+
+- All functions are designed to be self-contained and reusable
+- Error handling is built into each function
+- Functions follow consistent naming conventions
+- Documentation is kept in sync with code
+- This guide is a living document - update as you add new functions