@tracelog/lib 2.10.0-rc.113.17 → 2.10.0

package/README.md

@@ -1,15 +1,15 @@
 # TraceLog
 
-Lightweight web analytics library for tracking user behavior. Works standalone or with the TraceLog SaaS backend.
+Lightweight web analytics library for tracking user behavior. Works standalone or with optional backend integrations.
 
 ## Features
 
-- **Zero-config** — Auto-captures clicks, scrolls, page views, sessions, performance metrics, and JavaScript errors
-- **Standalone-first** — Works without any backend; opt in to TraceLog SaaS by passing a `projectId`
-- **Privacy-first** — PII sanitization, client-side sampling, `data-tlog-ignore` attribute, sensitive URL param stripping
-- **Cross-tab sessions** — BroadcastChannel sync with localStorage + sessionStorage recovery
-- **Event-driven** — Subscribe via `on()` / `off()` for real-time consumption
-- **Lightweight** — Single dependency (`web-vitals`), ~62KB gzipped
+- **Zero-config** - Auto-captures clicks, scrolls, page views, sessions, and performance metrics
+- **Standalone** - No backend required; optional integrations (TraceLog SaaS, custom API)
+- **Privacy-first** - PII sanitization, client-side sampling, `data-tlog-ignore` attribute
+- **Cross-tab sessions** - BroadcastChannel sync with localStorage recovery
+- **Event-driven** - Subscribe via `on()`/`off()` for real-time events
+- **Lightweight** - Single dependency (`web-vitals`), ~62KB gzipped
 
 ## Live Demo
 
@@ -20,7 +20,6 @@ Lightweight web analytics library for tracking user behavior. Works standalone o
 ## Installation
 
 ### NPM (Recommended)
-
 ```bash
 npm install @tracelog/lib
 ```
@@ -41,7 +40,6 @@ const { sessionId } = await tracelog.init({
 ```
 
 ### CDN (Script Tag)
-
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@tracelog/lib@latest/dist/browser/tracelog.js"></script>
 <script>
@@ -50,7 +48,6 @@ const { sessionId } = await tracelog.init({
 ```
 
 ### CDN (ES Module)
-
 ```html
 <script type="module">
   import { tracelog } from 'https://cdn.jsdelivr.net/npm/@tracelog/lib@latest/dist/browser/tracelog.esm.js';
@@ -58,52 +55,70 @@ const { sessionId } = await tracelog.init({
 </script>
 ```
 
----
-
 ## Quick Start
 
 ### Initialization Order
 
-Set up listeners **before** calling `init()` so they receive the initial `SESSION_START` and `PAGE_VIEW` events that fire during init.
+**Important:** Set up listeners and transformers **before** calling `init()` to capture all events from the start:
 
 ```typescript
-// 1. Obtain user consent first (your responsibility — see "User Consent" below)
-const hasConsent = await getUserConsent();
-if (!hasConsent) return;
+// 1. Obtain user consent FIRST (your responsibility)
+// See "User Consent Management" section below for implementation details
+const hasConsent = await getUserConsent(); // Your consent management system
+
+if (!hasConsent) {
+  console.log('User declined tracking');
+  return;
+}
 
-// 2. Register listeners (before init)
+// 2. Register event listeners SECOND (before init)
 tracelog.on('event', (event) => {
   console.log(event.type, event);
 });
 
-// 3. Identify the user (optional — can be called before or after init)
-tracelog.identify('cust_123', { name: 'Maria Garcia', plan: 'pro' });
+// 3. Configure transformers THIRD (if using custom backend)
+tracelog.setTransformer('beforeSend', (event) => {
+  // Transform events before they're queued
+  return { ...event, custom_metadata: { app: 'v1' } };
+});
 
-// 4. Initialize (starts tracking immediately)
-const { sessionId } = await tracelog.init({
+// 4. Configure custom headers FOURTH (if using custom backend with auth)
+tracelog.setCustomHeaders(() => ({
+  'Authorization': `Bearer ${getAuthToken()}`
+}));
+
+// 5. Initialize FIFTH (starts tracking immediately)
+await tracelog.init({
   integrations: {
-    tracelog: { projectId: 'your-project-id' }
+    custom: { collectApiUrl: 'https://api.example.com' }
   }
 });
 
-// 5. Track custom events at any point after init
-tracelog.event('button_clicked', { buttonId: 'signup-cta', source: 'homepage' });
+// 6. Identify user (after init, optional)
+tracelog.identify('cust_123', { name: 'Maria Garcia', plan: 'pro' });
+
+// 7. Track custom events (after init)
+tracelog.event('button_clicked', {
+  buttonId: 'signup-cta',
+  source: 'homepage'
+});
 
-// 6. On logout: reset identity (clears identity, regenerates UUID, opens a new session)
+// 8. On logout: reset identity
 await tracelog.resetIdentity();
 
-// 7. Cleanup on consent revoke or app unmount
+// 9. Cleanup (on consent revoke or app unmount)
 tracelog.destroy();
 ```
 
-**Auto-captured events** (no code required):
+**Why this order?** You must obtain user consent before initializing. Events like `SESSION_START` and `PAGE_VIEW` fire during initialization. Registering listeners, transformers, and custom headers before init ensures you capture, transform, and send these initial events with proper authentication.
 
-- Page views & navigation (including SPA route changes)
+**That's it!** TraceLog now automatically tracks:
+- Page views & navigation (including SPA routes)
 - Click interactions
 - Scroll behavior
 - User sessions
 - Web Vitals (LCP, INP, CLS, FCP, TTFB)
-- JavaScript errors & unhandled promise rejections
+- JavaScript errors
 
 ---
 
@@ -111,40 +126,53 @@ tracelog.destroy();
 
 | Method | Description |
 |--------|-------------|
-| `init(config?)` | Initialize tracking. Returns `Promise<{ sessionId }>`. See [Configuration](#configuration). |
-| `event(name, metadata?, options?)` | Track a custom event. `options.critical: true` drains the queue via `sendBeacon` right after tracking, so the batch (the critical event + anything already queued) survives an imminent navigation. Subject to `sendBeacon`'s 64KB cap — oversized batches are persisted to `localStorage` and recovered on next `init()` via their idempotency token; the backend deduplicates by `event.id`. |
-| `on(event, callback)` | Subscribe to events (`'event'` or `'queue'`). Local consumption — independent of backend sends. |
-| `off(event, callback)` | Unsubscribe. Must pass the exact callback reference used in `on()`. |
-| `identify(userId, traits?)` | Associate the current visitor with a known user identity. `traits` accepts a `Record<string, string>`; non-string values are dropped silently. |
-| `resetIdentity()` | Flush pending events under the old identity, clear identity, regenerate the visitor UUID, and start a new session. Use for logout flows. |
-| `isInitialized()` | `true` after a successful `init()`, `false` otherwise (including during teardown). |
-| `getSessionId()` | Current session ID, or `null` if not initialized. |
-| `getUserId()` | Current visitor UUID, or `null` if not initialized. |
-| `destroy()` | Stop tracking, drain pending events via `sendBeacon`, and release all resources. |
+| `init(config?)` | Initialize tracking (see [Configuration](#configuration)) |
+| `event(name, metadata?, options?)` | Track custom events. `options.critical: true` drains the queue via `sendBeacon` right after tracking, so the batch (the critical event + anything already queued) survives an imminent navigation. Subject to `sendBeacon`'s 64KB cap — oversized batches are persisted to `localStorage` and recovered on next `init()` via their idempotency token; the backend deduplicates by `event.id`. See [API_REFERENCE.md](./API_REFERENCE.md#eventname-metadata-options) for the full contract. |
+| `flushImmediately()` | Force an async `fetch` flush of all pending events. Returns `Promise<boolean>`. |
+| `flushImmediatelySync()` | Force a `sendBeacon` flush. Use for custom unload handlers; the library already wires this to `pagehide`/`beforeunload`/`visibilitychange`. |
+| `updateGlobalMetadata(metadata)` | Replace all global metadata |
+| `mergeGlobalMetadata(metadata)` | Merge with existing global metadata |
+| `on(event, callback)` | Subscribe to events (`'event'` or `'queue'`) |
+| `off(event, callback)` | Unsubscribe from events |
+| `setTransformer(hook, fn)` | Transform events before sending (see [Transformers](#transformers)) |
+| `removeTransformer(hook)` | Remove a previously set transformer |
+| `setCustomHeaders(provider)` | Add custom HTTP headers to requests (see [Custom Headers](#custom-headers)) |
+| `removeCustomHeaders()` | Remove custom headers provider |
+| `identify(userId, traits?)` | Associate visitor with a known user identity |
+| `resetIdentity()` | Clear identity, regenerate UUID, start new session |
+| `isInitialized()` | Check initialization status |
+| `getSessionId()` | Get current session ID (or null) |
+| `setQaMode(enabled)` | Enable/disable QA mode (console logging) |
+| `destroy()` | Stop tracking and cleanup |
 
 **→ [Complete API Reference](./API_REFERENCE.md)**
 
 ---
 
-## User Consent
+## User Consent Management
 
-TraceLog does not ship a consent manager. You are responsible for obtaining consent **before** calling `init()`.
+TraceLog requires you to obtain user consent **before** calling `init()`. The library does not include a built-in consent management system.
 
 ```typescript
+// Your responsibility: Obtain consent before initialization
 const userConsent = await showCookieBanner(); // Your consent solution
 
 if (userConsent.analytics) {
+  // Initialize only after consent
   await tracelog.init({
-    integrations: { tracelog: { projectId: 'your-project-id' } }
+    integrations: {
+      tracelog: { projectId: 'your-project-id' }
+    }
   });
 } else {
-  // User rejected — don't initialize
+  // User rejected - don't initialize
+  console.log('Analytics consent denied');
 }
 
-// If consent is revoked later
+// If user revokes consent later
 function handleConsentRevoke() {
-  tracelog.destroy();
-  localStorage.clear();
+  tracelog.destroy(); // Stop tracking immediately
+  localStorage.clear(); // Clear stored session data
 }
 ```
 
@@ -152,76 +180,140 @@ function handleConsentRevoke() {
 
 ## Configuration
 
-All configuration is optional. TraceLog works out-of-the-box with sensible defaults.
+All configuration is **optional**. TraceLog works out-of-the-box with sensible defaults.
 
 ```typescript
 await tracelog.init({
   // Session
-  sessionTimeout: 900000,           // 15 min (default)
+  sessionTimeout: 900000,  // 15 min (default)
 
   // Privacy
-  samplingRate: 1.0,                // 100% (default)
-  errorSampling: 1.0,               // 100% (default)
-  sensitiveQueryParams: ['token'],  // Added to the 15-param default deny-list
-
-  // Throttles
-  pageViewThrottleMs: 1000,         // Min interval between page_view events
-  clickThrottleMs: 300,             // Min interval between click events per element
-  maxSameEventPerMinute: 60,        // Per-name custom-event rate cap
+  samplingRate: 1.0,               // 100% (default)
+  sensitiveQueryParams: ['token'], // Add to defaults
 
-  // Batch flush
-  sendIntervalMs: 10000,            // Default batch interval
-  flushOnSpaNavigation: false,      // Opt-in: flush after pushState / replaceState / popstate / hashchange
-  flushOnPageHidden: true,          // Flush when document.hidden becomes true (mobile Safari coverage)
+  // Flush behavior (defaults shown)
+  flushOnSpaNavigation: false, // Opt-in: flush after pushState/replaceState/popstate/hashchange (default false; per-route flushing multiplies request volume on SPAs)
+  flushOnPageHidden: true,     // Flush when document.hidden becomes true (mobile Safari coverage)
 
-  // Web Vitals
-  webVitalsMode: 'needs-improvement', // 'all' | 'needs-improvement' | 'poor'
-  webVitalsThresholds: { LCP: 2500 }, // Optional per-metric overrides
+  // Integrations (pick one, multiple, or none)
+  integrations: {
+    tracelog: { projectId: 'your-id' },              // TraceLog SaaS
+    custom: { collectApiUrl: 'https://api.com' },    // Custom backend
 
-  // Global metadata appended to every event
-  globalMetadata: {
-    env: 'production',
-    version: '1.2.0',
-    appName: 'MyApp'
+    // Multi-integration: Send to multiple backends simultaneously
+    // tracelog: { projectId: 'proj-123' },            // Analytics dashboard
+    // custom: { collectApiUrl: 'https://warehouse.com' }  // Data warehouse
+    // Events sent to BOTH independently with separate error handling
   },
 
-  // Integration (omit for standalone mode)
-  integrations: {
-    tracelog: {
-      projectId: 'your-project-id',
-      shopify: false                // Optional: enable Shopify cart attribute linking
-    }
+  // Web Vitals filtering
+  webVitalsMode: 'needs-improvement',  // 'all' | 'needs-improvement' | 'poor'
+
+  // Viewport tracking (element visibility)
+  viewport: {
+    elements: [{ selector: '.cta', id: 'hero-cta' }],
+    threshold: 0.5,      // 50% visible
+    minDwellTime: 1000   // 1 second
   }
 });
 ```
 
-**→ [Full Configuration Reference](./API_REFERENCE.md#configuration)**
+**→ [Full Configuration Guide](./API_REFERENCE.md#configuration)**
 
 ---
 
 ## Automatic Event Types
 
-| Event Type      | What It Tracks                                  |
-|-----------------|-------------------------------------------------|
-| `page_view`     | Initial load, SPA route changes, hash changes   |
-| `click`         | User interactions with elements                 |
-| `session_start` | New session creation (server infers session end)|
-| `scroll`        | Depth and direction per scrollable container    |
-| `web_vitals`    | Core Web Vitals (LCP, INP, CLS, FCP, TTFB)      |
-| `error`         | JavaScript errors, unhandled promise rejections |
+TraceLog captures these events automatically (no code required):
+
+| Event Type        | What It Tracks                              |
+|-------------------|---------------------------------------------|
+| `page_view`       | Navigation, SPA route changes               |
+| `click`           | User interactions with elements             |
+| `session_start`   | New session creation                        |
+| `scroll`          | Scroll depth, velocity, engagement          |
+| `web_vitals`      | Core Web Vitals (LCP, INP, CLS, FCP, TTFB) |
+| `error`           | JavaScript errors, promise rejections       |
+| `viewport_visible`| Element visibility (requires `viewport` config) |
+
+**Filtering Events:**
+
+You can filter specific events before they're sent to your backend using the `beforeSend` transformer. This gives you complete control over what data is transmitted.
+
+```typescript
+// Filter out high-volume events (scroll, web_vitals)
+tracelog.setTransformer('beforeSend', (event) => {
+  // Skip scroll and web vitals events
+  if (['scroll', 'web_vitals'].includes(event.type)) {
+    return null; // Returning null excludes the event from being sent
+  }
+  return event; // Send all other events normally
+});
+
+await tracelog.init({
+  integrations: {
+    custom: { collectApiUrl: 'https://api.example.com' }
+  }
+});
+```
+
+**Advanced Filtering:**
+
+```typescript
+// Conditional filtering based on custom logic
+tracelog.setTransformer('beforeSend', (event) => {
+  // Only send errors in production
+  if (event.type === 'error' && process.env.NODE_ENV !== 'production') {
+    return null;
+  }
+
+  // Only send 10% of scroll events (sampling)
+  if (event.type === 'scroll' && Math.random() > 0.1) {
+    return null;
+  }
+
+  return event;
+});
+```
+
+**Multi-Integration Behavior:**
+
+```typescript
+// Transformers ONLY apply to custom backends
+// TraceLog SaaS always receives all events unmodified
+tracelog.setTransformer('beforeSend', (event) => {
+  if (['scroll', 'web_vitals'].includes(event.type)) {
+    return null; // Filtered from custom backend only
+  }
+  return event;
+});
+
+await tracelog.init({
+  integrations: {
+    tracelog: { projectId: 'proj-123' },            // Gets ALL events (unfiltered)
+    custom: { collectApiUrl: 'https://warehouse.com' }  // Gets filtered events
+  }
+});
+```
+
+**Important:** Transformers (`beforeSend`, `beforeBatch`) only apply to **custom backend integrations**. TraceLog SaaS always receives all events unmodified to maintain schema integrity and ensure complete analytics. This behavior is the same as the removed `disabledEvents` configuration.
 
-**Custom events:**
+**Use Cases:**
+- Reduce bandwidth and backend costs for custom backends
+- Already using Sentry/Datadog for errors (filter out `error` events from custom backend)
+- Data warehouse doesn't need scroll/vitals granularity
+- Minimize custom backend data volume for privacy compliance
+- Custom sampling logic per event type
 
+**Note:** Filtered events are still captured locally. Use `tracelog.on('event')` to access all events client-side, even those excluded from backend transmission.
+
+**Custom Events:**
 ```typescript
 tracelog.event('purchase_completed', {
   orderId: 'ord-123',
   total: 99.99,
   currency: 'USD'
 });
-
-// Right before a navigation — guarantee delivery via sendBeacon
-tracelog.event('purchase_completed', { orderId: 'ord-123' }, { critical: true });
-window.location.href = '/thanks';
 ```
 
 **→ [Event Types Reference](./API_REFERENCE.md#event-types)**
@@ -230,37 +322,441 @@ window.location.href = '/thanks';
 
 ## Global Metadata
 
-Set at `init()` time and attached to every event the library sends. Replace it by destroying and re-initializing TraceLog with a new config (typical at login / logout).
+Global metadata is automatically attached to **every event** sent to your backend, making it ideal for user context, environment info, or app-wide properties.
+
+### Setting Initial Metadata
+
+Configure global metadata during initialization:
 
 ```typescript
 await tracelog.init({
   globalMetadata: {
     env: 'production',
     version: '1.2.0',
-    plan: user?.plan ?? 'anonymous'
+    appName: 'MyApp'
   }
 });
 ```
 
-**Validation rules:**
+### Updating Metadata at Runtime
+
+**Replace all metadata** (previous keys removed):
+
+```typescript
+// User login: Replace with user context
+tracelog.updateGlobalMetadata({
+  userId: 'user-456',
+  plan: 'premium',
+  cohort: 'beta-testers'
+});
+
+// User logout: Clear all metadata
+tracelog.updateGlobalMetadata({});
+```
+
+**Merge with existing metadata** (preserves other keys):
+
+```typescript
+// Add user ID while preserving env and version
+tracelog.mergeGlobalMetadata({ userId: 'user-123' });
+
+// Update version while preserving others
+tracelog.mergeGlobalMetadata({ version: '1.3.0' });
+
+// Add feature flags
+tracelog.mergeGlobalMetadata({
+  feature_new_ui: true,
+  feature_dark_mode: false
+});
+```
+
+### Use Cases
+
+**User Authentication:**
+```typescript
+// Login
+tracelog.mergeGlobalMetadata({
+  userId: user.id,
+  email: user.email,
+  plan: user.subscription.plan
+});
+
+// Logout
+tracelog.updateGlobalMetadata({});
+```
+
+**A/B Testing:**
+```typescript
+tracelog.mergeGlobalMetadata({
+  experiment_checkout: 'variant-b',
+  experiment_pricing: 'control'
+});
+```
+
+**Environment Context:**
+```typescript
+tracelog.mergeGlobalMetadata({
+  build: process.env.BUILD_NUMBER,
+  region: user.location.region,
+  language: navigator.language
+});
+```
+
+### Validation Rules
 
-- **Allowed types**: primitives (string, number, boolean), string arrays, nested objects (up to 10 levels)
-- **Disallowed**: functions, symbols, `undefined`, circular references
-- **Limits**: max 100 keys, 48 KB serialized size, 500 items per array, 1000 chars per string
+- **Allowed Types**: Primitives (string, number, boolean), string arrays, nested objects (up to 10 levels)
+- **NOT Allowed**: Functions, symbols, undefined, circular references
+- **Limits**: Max 100 keys, 48KB serialized size, 500 items per array, 1000 chars per string
 
-**→ [Metadata Reference](./API_REFERENCE.md#globalmetadata)**
+**→ [Metadata API Reference](./API_REFERENCE.md#global-metadata)**
+
+---
+
+## Transformers
+
+Transform events dynamically at runtime before they're sent to integrations. Useful for adding custom logic, enrichment, or filtering.
+
+**Important**: Transformers are **integration-specific** to protect TraceLog SaaS schema integrity:
+
+| Integration | `beforeSend` | `beforeBatch` | Notes |
+|-------------|--------------|---------------|-------|
+| **Standalone (no backend)** | ✅ Applied | ⚠️ Not supported | Only local event emission; `beforeBatch` requires backend |
+| **TraceLog SaaS (only)** | ❌ Silently ignored | ❌ Silently ignored | Schema protection |
+| **Custom Backend (only)** | ✅ Applied | ✅ Applied | Full control |
+| **Multi-Integration** | ⚠️ Custom only | ⚠️ Custom only | SaaS gets original events, custom gets transformed |
+
+**Multi-Integration Behavior:**
+- When using both TraceLog SaaS + Custom backend simultaneously
+- SaaS receives **original events** (transformers not applied)
+- Custom backend receives **transformed events**
+- Independent error handling and retry per integration
+
+**Event Listeners and Transformers:**
+
+Event listeners (`tracelog.on('event', ...)`) receive **original events**, not transformed events. Transformers only affect data sent to backends.
+
+```typescript
+tracelog.setTransformer('beforeSend', (data) => {
+  if ('type' in data) {
+    return { ...data, enrichedField: 'value' };
+  }
+  return data;
+});
+
+tracelog.on('event', (ev) => {
+  console.log(ev.enrichedField); // undefined - listeners receive original events
+});
+```
+
+**Workaround for GTM/Third-Party Relay:**
+
+If you need to forward enriched events to GTM or other systems, apply the transformation in your listener:
+
+```typescript
+// Define enrichment function once
+const enrichEvent = (event) => ({
+  ...event,
+  appVersion: '1.0.0',
+  environment: 'production'
+});
+
+// Use in transformer (for backend)
+tracelog.setTransformer('beforeSend', (data) => {
+  if ('type' in data) {
+    return enrichEvent(data);
+  }
+  return data;
+});
+
+// Use in listener (for GTM relay)
+tracelog.on('event', (event) => {
+  const enrichedEvent = enrichEvent(event);
+  window.dataLayer?.push({ event: 'tracelog_event', ...enrichedEvent });
+});
+```
+
+### Available Hooks
+
+#### `beforeSend` - Per-Event Transformation
+
+Transform individual events **before** deduplication, sampling, and queueing.
+
+**Timing (depends on integration mode):**
+- **Standalone mode (no backend)**: Runs in `EventManager.buildEventPayload()` before dedup/sampling/queueing
+- **Custom-only mode**: Runs in `EventManager.buildEventPayload()` before dedup/sampling/queueing
+- **Multi-integration mode (SaaS + Custom)**: Runs in `SenderManager` per-integration (SaaS skipped, Custom applied)
+- **TraceLog SaaS-only mode**: Silently ignored (not applied)
+
+```typescript
+import { tracelog } from '@tracelog/lib';
+import type { EventData, EventsQueue } from '@tracelog/lib';
+
+// Add custom metadata to all events
+tracelog.setTransformer('beforeSend', (data: EventData | EventsQueue) => {
+  if ('type' in data) {
+    return {
+      ...data,
+      custom_event: {
+        ...data.custom_event,
+        metadata: {
+          ...data.custom_event?.metadata,
+          environment: 'production',
+          version: '1.0.0'
+        }
+      }
+    };
+  }
+  return data;
+});
+
+// Filter out sensitive events
+tracelog.setTransformer('beforeSend', (data) => {
+  if ('type' in data && data.custom_event?.name === 'internal_event') {
+    return null; // Event will be dropped
+  }
+  return data;
+});
+```
+
+#### `beforeBatch` - Batch Transformation
+
+Transform the entire batch before sending to backend. Runs once per batch (every 10s or 50 events).
+
+```typescript
+// Add batch-level metadata
+tracelog.setTransformer('beforeBatch', (data) => {
+  if ('events' in data) {
+    return {
+      ...data,
+      global_metadata: {
+        ...data.global_metadata,
+        batchSize: data.events.length,
+        batchTimestamp: Date.now()
+      }
+    };
+  }
+  return data;
+});
+
+// Filter batch based on conditions
+tracelog.setTransformer('beforeBatch', (data) => {
+  if ('events' in data && data.events.length < 5) {
+    return null; // Don't send small batches
+  }
+  return data;
+});
+```
+
+### Removing Transformers
+
+```typescript
+// Remove specific transformer
+tracelog.removeTransformer('beforeSend');
+tracelog.removeTransformer('beforeBatch');
+```
+
+### Error Handling & Validation
+
+Transformers are designed to be resilient and flexible:
+
+**Input Validation:**
+- **Function type check**: `setTransformer()` throws error if `fn` is not a function
+- **Example**: `tracelog.setTransformer('beforeSend', null)` → Throws `Error: [TraceLog] Transformer must be a function, received: object`
+
+**Error Handling:**
+- **Exceptions**: Caught and logged, original event/batch used
+- **Invalid return**: Logged warning, original event/batch used
+- **`null` return**: Event/batch filtered out (intended behavior)
+
+**Validation:**
+- **Minimal checks only**: `beforeSend` requires `'type'` field, `beforeBatch` requires `'events'` array
+- **Custom schemas supported**: All other fields optional for maximum flexibility with custom backends
+- **Use case**: Transform data to match your backend's schema (e.g., data warehouses, custom APIs)
+
+```typescript
+// Safe transformer - errors won't break tracking
+tracelog.setTransformer('beforeSend', (data) => {
+  try {
+    // Complex transformation logic
+    return transformData(data);
+  } catch (error) {
+    console.error('Transformer error:', error);
+    return data; // Fallback to original
+  }
+});
+
+// Custom schema example - completely reshape for your backend
+tracelog.setTransformer('beforeSend', (data) => {
+  if ('type' in data) {
+    return {
+      type: 'analytics_event',
+      eventName: data.custom_event?.name,
+      timestamp: Date.now(),
+      // Your custom fields - TraceLog won't reject this!
+      customField1: 'value',
+      customField2: 123
+    };
+  }
+  return data;
+});
+```
+
+### Use Cases
+
+**Data Enrichment:**
+```typescript
+tracelog.setTransformer('beforeSend', (data) => {
+  if ('type' in data) {
+    return {
+      ...data,
+      custom_event: {
+        ...data.custom_event,
+        metadata: {
+          ...data.custom_event?.metadata,
+          userId: getCurrentUserId(),
+          sessionContext: getSessionContext()
+        }
+      }
+    };
+  }
+  return data;
+});
+```
+
+**Event Filtering:**
+```typescript
+// Filter out bot traffic
+tracelog.setTransformer('beforeBatch', (data) => {
+  if ('events' in data) {
+    const filteredEvents = data.events.filter(
+      event => !isBotUserAgent(navigator.userAgent)
+    );
+    return { ...data, events: filteredEvents };
+  }
+  return data;
+});
+```
+
+**PII Sanitization (Custom Backend):**
+```typescript
+// Additional sanitization for custom backend
+tracelog.setTransformer('beforeSend', (data) => {
+  if ('type' in data && data.custom_event?.metadata) {
+    const sanitized = { ...data.custom_event.metadata };
+    delete sanitized.email;
+    delete sanitized.phone;
+    return {
+      ...data,
+      custom_event: {
+        ...data.custom_event,
+        metadata: sanitized
+      }
+    };
+  }
+  return data;
+});
+```
+
+---
+
+## Custom Headers
+
+Add custom HTTP headers to requests sent to custom backends. Useful for authentication, tenant identification, or API versioning.
+
+**Important**: Custom headers **only apply to custom backend integrations**. TraceLog SaaS always receives requests without custom headers.
+
+### Static Headers (Config)
+
+Set fixed headers in configuration:
+
+```typescript
+await tracelog.init({
+  integrations: {
+    custom: {
+      collectApiUrl: 'https://api.example.com/collect',
+      headers: {
+        'X-Tenant-Id': 'tenant-123',
+        'X-Brand': 'my-brand',
+        'X-API-Version': '2.0'
+      }
+    }
+  }
+});
+```
+
+### Dynamic Headers (Provider)
+
+Set headers dynamically at runtime (e.g., auth tokens that expire):
+
+```typescript
+// Set before or after init
+tracelog.setCustomHeaders(() => ({
+  'Authorization': `Bearer ${getAuthToken()}`,
+  'X-Request-ID': crypto.randomUUID()
+}));
+
+await tracelog.init({
+  integrations: {
+    custom: { collectApiUrl: 'https://api.example.com/collect' }
+  }
+});
+```
+
+### Static + Dynamic Headers
+
+Combine both approaches. Dynamic headers override static on key collision:
+
+```typescript
+await tracelog.init({
+  integrations: {
+    custom: {
+      collectApiUrl: 'https://api.example.com/collect',
+      headers: {
+        'X-Brand': 'static-brand',       // Static
+        'X-Tenant-Id': 'tenant-123'      // Static
+      }
+    }
+  }
+});
+
+// Dynamic provider overrides 'X-Brand'
+tracelog.setCustomHeaders(() => ({
+  'X-Brand': 'dynamic-brand',           // Overrides static
+  'Authorization': 'Bearer token'        // New header
+}));
+
+// Result: { 'X-Tenant-Id': 'tenant-123', 'X-Brand': 'dynamic-brand', 'Authorization': 'Bearer token' }
+```
+
+### Removing Headers
+
+```typescript
+// Remove dynamic provider (static headers from config remain)
+tracelog.removeCustomHeaders();
+```
+
+### sendBeacon Limitation
+
+⚠️ Custom headers are **NOT applied** to `sendBeacon()` requests (page unload). The browser API doesn't support custom headers. For scenarios requiring headers on all requests:
+- Ensure async sends complete before page unload
+- Use short-lived tokens that don't require refresh per request
+
+**→ [Custom Headers API Reference](./API_REFERENCE.md#setcustomheadersprovider-customheadersprovider-void)**
 
 ---
 
 ## Integration Modes
 
-### 1. Standalone (no backend)
+TraceLog supports multiple integration modes. Choose what fits your needs:
+
+### 1. Standalone (No Backend)
 
-Default when no `integrations` are configured. Events are captured, queued, and emitted locally — no network requests.
+**Default mode when no integrations configured.** Events captured and emitted locally without network requests.
 
 ```typescript
 await tracelog.init();
 
+// Consume events locally
 tracelog.on('event', (event) => {
   myAnalytics.track(event);
 });
@@ -270,10 +766,15 @@ tracelog.on('queue', (batch) => {
 });
 ```
 
-Perfect for custom analytics pipelines, testing, or privacy-focused implementations where you want to ship events to your own destination via a listener.
+**Behavior:**
+- ✅ Events captured and queued normally
+- ✅ `beforeSend` transformer applied (per-event transformation)
+- ⚠️ `beforeBatch` transformer **NOT supported** (no SenderManager created)
+- ✅ Events emitted to local listeners every 10 seconds or 50 events
+- ❌ **NO network requests made** (no backends configured)
+- ✅ Perfect for custom analytics pipelines, testing, or privacy-focused implementations
 
 ### 2. TraceLog SaaS
-
 ```typescript
 await tracelog.init({
   integrations: {
@@ -282,64 +783,126 @@ await tracelog.init({
 });
 ```
 
-**Domain requirement.** The SaaS endpoint is derived from the host page's domain (`https://{projectId}.{rootDomain}/collect`), so `init()` rejects when called from `localhost` or a raw IP address. For local development, omit `integrations.tracelog` to run in standalone mode, or test against a staging domain mapped via `/etc/hosts`.
+### 3. Custom Backend
+```typescript
+await tracelog.init({
+  integrations: {
+    custom: {
+      collectApiUrl: 'https://api.example.com/collect',
+      allowHttp: false,          // Only true for local testing
+      fetchCredentials: 'include' // Cookie policy: 'include' | 'same-origin' | 'omit'
+    }
+  }
+});
+```
+
+### 4. Multi-Integration (TraceLog SaaS + Custom Backend)
+```typescript
+await tracelog.init({
+  integrations: {
+    tracelog: { projectId: 'your-project-id' },           // Analytics dashboard
+    custom: { collectApiUrl: 'https://warehouse.com' }    // Data warehouse
+  }
+});
+
+// Events sent to BOTH endpoints independently
+// - Independent error handling per integration
+// - Independent retry/persistence per integration
+// - Parallel sending (non-blocking)
+```
 
-**→ [Integration Reference](./API_REFERENCE.md#integration-configuration)**
+**→ [Integration Setup Guide](./API_REFERENCE.md#integration-configuration)**
 
 ---
 
 ## Error Handling & Reliability
 
-### Automatic retry strategy
+TraceLog implements intelligent error handling with automatic retries for transient failures:
 
-**Transient errors** (5xx, timeouts, network failures):
+### Automatic Retry Strategy
 
-- Up to 2 retry attempts (3 total)
-- Exponential backoff with jitter (200–300 ms, 400–500 ms)
-- Persisted to `localStorage` after exhaustion for next-page recovery
+**Transient Errors** (5xx, timeouts, network failures):
+- **Up to 2 retry attempts** per integration (3 total attempts)
+- **Exponential backoff with jitter**: 200-300ms, 400-500ms
+- **Independent retries** per integration (SaaS and Custom retry separately)
+- **Persistence after exhaustion**: Events saved to localStorage for next-page recovery
 
-**Rate limit (429):**
+**Rate Limit** (429):
+- **No in-session retries** — arms a 60-second cooldown instead
+- **Cooldown is mirrored to localStorage** and shared across tabs/windows on the same origin (prevents every fresh page load from hammering the server's 429 window)
+- **Events persisted immediately** to localStorage; retried once the cooldown elapses
+- TraceLog SaaS deduplicates retries server-side; custom backends should implement idempotency
 
-- No in-session retries — arms a 60-second cooldown instead
-- Cooldown is mirrored to `localStorage` and shared across tabs/windows on the same origin (prevents every fresh page load from hammering the server during its 429 window)
-- Events are persisted immediately and retried once the cooldown elapses
-- The backend deduplicates retries via the batch idempotency token
+**Permanent Errors** (4xx except 408, 429):
+- **No retries** (immediate failure)
+- **Events discarded** (not persisted)
+- **Exception**: 408 Request Timeout is treated as transient
 
-**Permanent errors** (4xx except 408, 429):
+```typescript
+// Multi-backend example with automatic retries
+await tracelog.init({
+  integrations: {
+    tracelog: { projectId: 'project-id' },
+    custom: { collectApiUrl: 'https://api.example.com/collect' }
+  }
+});
+
+// If tracelog SaaS returns 500:
+// - Retries 2 times with backoff (200-300ms, 400-500ms)
+// - If all fail → persists to localStorage for next page
 
-- No retries — events are discarded
-- 408 Request Timeout is treated as transient
+// If custom backend succeeds:
+// - Events removed from queue (optimistic removal)
+// - Failed integration recovered on next page load
+```
 
-### Error classification
+### Error Classification
 
-| Status                | Type        | Retries          | Persistence       |
-|-----------------------|-------------|------------------|-------------------|
-| **2xx**               | Success     | None             | Cleared           |
-| **4xx** (except 408/429) | Permanent | ❌ None          | ❌ Discarded      |
-| **408**               | Transient   | ✅ Up to 2       | ✅ After exhaustion |
-| **429**               | Rate Limit  | ❌ None (60s cooldown, shared across tabs) | ✅ Immediate |
-| **5xx**               | Transient   | ✅ Up to 2       | ✅ After exhaustion |
-| **Network error**     | Transient   | ✅ Up to 2       | ✅ After exhaustion |
-| **Timeout**           | Transient   | ✅ Up to 2       | ✅ After exhaustion |
+| Status Code | Type | Retries | Persistence |
+|-------------|------|---------|-------------|
+| **2xx** | Success | None | Cleared |
+| **4xx** (except 408, 429) | Permanent | ❌ None | ❌ Discarded |
+| **408** Request Timeout | Transient | ✅ Up to 2 | ✅ After exhaustion |
+| **429** Too Many Requests | Rate Limited (60s cooldown, shared across tabs) | ❌ None | ✅ Immediate |
+| **5xx** | Transient | ✅ Up to 2 | ✅ After exhaustion |
+| **Network Error** | Transient | ✅ Up to 2 | ✅ After exhaustion |
+| **Timeout** | Transient | ✅ Up to 2 | ✅ After exhaustion |
 
-### Recovery on page load
+### Optimistic Queue Management
 
-Failed events are recovered automatically on the next `init()`:
+**Multi-Integration Behavior:**
+- Events removed from queue if **AT LEAST ONE** integration succeeds
+- Failed integrations persist independently for next-page recovery
+- Successful integration doesn't retry (performance optimization)
 
+**Example Scenario:**
 ```typescript
-// Page 1: events fail to send (5xx after retries) → persisted with idempotency token
-// Page 2: init() recovers and resends; backend deduplicates by idempotency token
+// SaaS succeeds immediately → no retry needed
+// Custom fails with 503 → retries 2 times → persists for recovery
+// Events removed from queue (SaaS succeeded)
+// Next page load → only Custom integration recovers persisted events
 ```
 
-Multi-tab protection: a 1-second window prevents two tabs from re-sending the same persisted batch simultaneously.
+### Recovery on Page Load
 
-**Circuit breaker.** After `MAX_CONSECUTIVE_NETWORK_FAILURES` consecutive network-level failures (DNS, connection refused), the sender opens its circuit and skips further requests until `CIRCUIT_BREAKER_COOLDOWN_MS` elapses. A single probe request is then allowed (half-open state) before fully closing.
+Failed events automatically recovered on next `init()`:
+
+```typescript
+// Page 1: Events fail to send (5xx error after retries)
+// → Persisted to localStorage per-integration
+
+// Page 2: User navigates to new page
+await tracelog.init({ /* same config */ });
+// ✅ Automatically recovers and resends persisted events
+// ✅ Independent recovery per integration
+// ✅ Multi-tab protection (1s window prevents duplicates)
+```
 
 **→ [Full Error Handling Reference](./API_REFERENCE.md#error-handling)**
 
-### Session continuity across external redirects
+### Session Continuity (External Redirects)
 
-TraceLog preserves sessions across external redirects (payment processors, OAuth flows, etc.) with zero developer action. Session data is mirrored to `sessionStorage` alongside `localStorage`, so when a user returns from an external site and `localStorage` is empty, the session is recovered from `sessionStorage` transparently.
+TraceLog automatically preserves sessions across external redirects (payment processors, OAuth flows, etc.) with zero developer action. Session data is mirrored to `sessionStorage` alongside `localStorage`, so when a user returns from an external site and `localStorage` is empty, the session is recovered from `sessionStorage` transparently.
 
 ```typescript
 // No special handling needed before redirect
@@ -351,7 +914,7 @@ tracelog.event('purchase', { orderId: '12345', amount: 99.99 });
 // Same session as before the redirect
 ```
 
-- Automatic — no API calls or developer action required
+- Automatic: no API calls or developer action required
 - `sessionStorage` mirror survives same-tab navigation (cleared on tab close)
 - Session timeout still applies (expired sessions are not recovered)
 
@@ -359,26 +922,26 @@ tracelog.event('purchase', { orderId: '12345', amount: 99.99 });
 
 ## Privacy & Security
 
-TraceLog is privacy-first by design:
+TraceLog is **privacy-first** by design:
 
-- ✅ **PII sanitization** — auto-redacts emails, phones, credit cards, IBANs, API keys, bearer tokens, and connection-string passwords from click text and error messages
-- ✅ **Input protection** — never captures values from `<input>`, `<textarea>`, `<select>`
-- ✅ **URL filtering** — removes 15 default sensitive query params (token, password, auth, secret, api_key, …) plus any you add via `sensitiveQueryParams`
-- ✅ **Element exclusion** — use `data-tlog-ignore` on any container to exclude its contents from click tracking
-- ✅ **Client-side controls** — sampling, dedup, and validation all happen in the browser
+- ✅ **PII Sanitization** - Auto-redacts emails, phones, credit cards, API keys
+- ✅ **Input Protection** - Never captures `<input>`, `<textarea>`, `<select>` values
+- ✅ **URL Filtering** - Removes sensitive query params (15 defaults + custom)
+- ✅ **Element Exclusion** - Use `data-tlog-ignore` to exclude sensitive areas
+- ✅ **Client-Side Controls** - All sampling and validation happens in browser
 
+**Example:**
 ```html
-<!-- Exclude sensitive forms entirely -->
+<!-- Exclude sensitive forms -->
 <div data-tlog-ignore>
   <input type="password" name="password">
   <input type="text" name="credit_card">
 </div>
 ```
 
-**Your responsibilities:**
-
-- Obtain user consent before calling `init()` (GDPR / CCPA / LOPD)
-- Avoid PII in custom event metadata (TraceLog only sanitizes element text and error messages)
+**Your Responsibilities:**
+- Get user consent before calling `init()` (GDPR/CCPA)
+- Sanitize custom event metadata (avoid PII)
 - Call `destroy()` on consent revoke
 
 **→ [Complete Security Guide](./SECURITY.md)**
@@ -387,20 +950,30 @@ TraceLog is privacy-first by design:
 
 ## QA Mode
 
-QA mode logs custom events to the browser console so you can verify tracking implementation without inspecting the network tab.
+Enable QA mode for debugging and development:
 
-### URL activation
+### URL Activation
+```bash
+# Enable
+?tlog_mode=qa
 
-```text
-?tlog_mode=qa       # Enable (persists in sessionStorage for the tab)
-?tlog_mode=qa_off   # Disable
+# Disable
+?tlog_mode=qa_off
+```
+
+### Programmatic API
+```typescript
+tracelog.setQaMode(true);   // Enable
+tracelog.setQaMode(false);  // Disable
 ```
 
-**Effects in QA mode:**
+**Features:**
+- Custom events logged to browser console
+- Strict validation (throws errors instead of warnings)
+- Session state visible in console
+- Persistent across page reloads (sessionStorage)
 
-- Custom events logged to console with their name and metadata
-- Strict validation: invalid custom-event payloads throw instead of being silently dropped
-- Persists across navigations within the same tab (cleared on tab close)
+**→ [QA Mode Documentation](./API_REFERENCE.md#setqamodeenabled-boolean-void)**
 
 ---
 
@@ -411,7 +984,7 @@ QA mode logs custom events to the browser console so you can verify tracking imp
 - Safari 12+
 - Edge 79+
 
-**SSR/SSG compatible** — safe to import in Angular Universal, Next.js, Nuxt, SvelteKit. All methods no-op in Node.js.
+**SSR/SSG Compatible:** Safe to import in Angular Universal, Next.js, Nuxt, SvelteKit (no-ops in Node.js).
 
 ---
 
@@ -419,9 +992,9 @@ QA mode logs custom events to the browser console so you can verify tracking imp
 
 ```bash
 npm install              # Install dependencies
-npm run build:all        # Build ESM + CJS + browser bundles
+npm run build:all        # Build ESM + CJS + Browser bundles
 npm run check            # Lint + format validation
-npm test                 # Run all tests
+npm run test             # Run all tests
 npm run test:coverage    # Generate coverage report
 ```
 
@@ -433,10 +1006,10 @@ npm run test:coverage    # Generate coverage report
 
 | Document | Description |
 |----------|-------------|
-| **[API Reference](./API_REFERENCE.md)** | Complete API documentation: methods, config options, event types |
-| **[Best Practices](./BEST_PRACTICES.md)** | Patterns, anti-patterns, optimization tips |
-| **[Security Guide](./SECURITY.md)** | Privacy, GDPR compliance, security checklist |
-| **[Changelog](./CHANGELOG.md)** | Release history |
+| **[API Reference](./API_REFERENCE.md)** | Complete API documentation with all methods, config options, and event types |
+| **[Best Practices](./BEST_PRACTICES.md)** | Patterns, anti-patterns, and optimization tips |
+| **[Security Guide](./SECURITY.md)** | Privacy, GDPR compliance, and security best practices |
+| **[Changelog](./CHANGELOG.md)** | Release history and migration guides |
 | **[Handlers](./src/handlers/README.md)** | Event capture implementation details |
 | **[Managers](./src/managers/README.md)** | Core component architecture |