@tracelog/lib 2.10.0 → 3.0.0-rc.115.6

package/README.md

@@ -1,15 +1,15 @@
 # TraceLog
 
-Lightweight web analytics library for tracking user behavior. Works standalone or with optional backend integrations.
+Lightweight web analytics library for tracking user behavior. Works standalone or with the TraceLog SaaS backend.
 
 ## Features
 
-- **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
+- **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
 
 ## Live Demo
 
@@ -20,6 +20,7 @@ Lightweight web analytics library for tracking user behavior. Works standalone o
 ## Installation
 
 ### NPM (Recommended)
+
 ```bash
 npm install @tracelog/lib
 ```
@@ -40,6 +41,7 @@ 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>
@@ -48,6 +50,7 @@ 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';
@@ -55,70 +58,52 @@ const { sessionId } = await tracelog.init({
 </script>
 ```
 
+---
+
 ## Quick Start
 
 ### Initialization Order
 
-**Important:** Set up listeners and transformers **before** calling `init()` to capture all events from the start:
+Set up listeners **before** calling `init()` so they receive the initial `SESSION_START` and `PAGE_VIEW` events that fire during init.
 
 ```typescript
-// 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;
-}
+// 1. Obtain user consent first (your responsibility — see "User Consent" below)
+const hasConsent = await getUserConsent();
+if (!hasConsent) return;
 
-// 2. Register event listeners SECOND (before init)
+// 2. Register listeners (before init)
 tracelog.on('event', (event) => {
   console.log(event.type, event);
 });
 
-// 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. Configure custom headers FOURTH (if using custom backend with auth)
-tracelog.setCustomHeaders(() => ({
-  'Authorization': `Bearer ${getAuthToken()}`
-}));
+// 3. Identify the user (optional — can be called before or after init)
+tracelog.identify('cust_123', { name: 'Maria Garcia', plan: 'pro' });
 
-// 5. Initialize FIFTH (starts tracking immediately)
-await tracelog.init({
+// 4. Initialize (starts tracking immediately)
+const { sessionId } = await tracelog.init({
   integrations: {
-    custom: { collectApiUrl: 'https://api.example.com' }
+    tracelog: { projectId: 'your-project-id' }
   }
 });
 
-// 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'
-});
+// 5. Track custom events at any point after init
+tracelog.event('button_clicked', { buttonId: 'signup-cta', source: 'homepage' });
 
-// 8. On logout: reset identity
+// 6. On logout: reset identity (clears identity, regenerates UUID, opens a new session)
 await tracelog.resetIdentity();
 
-// 9. Cleanup (on consent revoke or app unmount)
+// 7. Cleanup on consent revoke or app unmount
 tracelog.destroy();
 ```
 
-**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.
+**Auto-captured events** (no code required):
 
-**That's it!** TraceLog now automatically tracks:
-- Page views & navigation (including SPA routes)
+- Page views & navigation (including SPA route changes)
 - Click interactions
 - Scroll behavior
 - User sessions
 - Web Vitals (LCP, INP, CLS, FCP, TTFB)
-- JavaScript errors
+- JavaScript errors & unhandled promise rejections
 
 ---
 
@@ -126,53 +111,40 @@ tracelog.destroy();
 
 | Method | Description |
 |--------|-------------|
-| `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 |
+| `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. |
 
 **→ [Complete API Reference](./API_REFERENCE.md)**
 
 ---
 
-## User Consent Management
+## User Consent
 
-TraceLog requires you to obtain user consent **before** calling `init()`. The library does not include a built-in consent management system.
+TraceLog does not ship a consent manager. You are responsible for obtaining consent **before** calling `init()`.
 
 ```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
-  console.log('Analytics consent denied');
+  // User rejected — don't initialize
 }
 
-// If user revokes consent later
+// If consent is revoked later
 function handleConsentRevoke() {
-  tracelog.destroy(); // Stop tracking immediately
-  localStorage.clear(); // Clear stored session data
+  tracelog.destroy();
+  localStorage.clear();
 }
 ```
 
@@ -180,140 +152,76 @@ 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)
-  sensitiveQueryParams: ['token'], // Add to defaults
+  samplingRate: 1.0,                // 100% (default)
+  errorSampling: 1.0,               // 100% (default)
+  sensitiveQueryParams: ['token'],  // Added to the 15-param default deny-list
 
-  // 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)
+  // 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
 
-  // Integrations (pick one, multiple, or none)
-  integrations: {
-    tracelog: { projectId: 'your-id' },              // TraceLog SaaS
-    custom: { collectApiUrl: 'https://api.com' },    // Custom backend
+  // 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)
 
-    // 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
-  },
+  // Web Vitals
+  webVitalsMode: 'needs-improvement', // 'all' | 'needs-improvement' | 'poor'
+  webVitalsThresholds: { LCP: 2500 }, // Optional per-metric overrides
 
-  // Web Vitals filtering
-  webVitalsMode: 'needs-improvement',  // 'all' | 'needs-improvement' | 'poor'
+  // Global metadata appended to every event
+  globalMetadata: {
+    env: 'production',
+    version: '1.2.0',
+    appName: 'MyApp'
+  },
 
-  // Viewport tracking (element visibility)
-  viewport: {
-    elements: [{ selector: '.cta', id: 'hero-cta' }],
-    threshold: 0.5,      // 50% visible
-    minDwellTime: 1000   // 1 second
+  // Integration (omit for standalone mode)
+  integrations: {
+    tracelog: {
+      projectId: 'your-project-id',
+      shopify: false                // Optional: enable Shopify cart attribute linking
+    }
   }
 });
 ```
 
-**→ [Full Configuration Guide](./API_REFERENCE.md#configuration)**
+**→ [Full Configuration Reference](./API_REFERENCE.md#configuration)**
 
 ---
 
 ## Automatic Event Types
 
-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.
+| 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 |
 
-**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
+**Custom events:**
 
-**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)**
@@ -322,441 +230,37 @@ tracelog.event('purchase_completed', {
 
 ## Global Metadata
 
-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:
+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).
 
 ```typescript
 await tracelog.init({
   globalMetadata: {
     env: 'production',
     version: '1.2.0',
-    appName: 'MyApp'
+    plan: user?.plan ?? 'anonymous'
   }
 });
 ```
 
-### 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
+**Validation rules:**
 
-- **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
+- **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
 
-**→ [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)**
+**→ [Metadata Reference](./API_REFERENCE.md#globalmetadata)**
 
 ---
 
 ## Integration Modes
 
-TraceLog supports multiple integration modes. Choose what fits your needs:
-
-### 1. Standalone (No Backend)
+### 1. Standalone (no backend)
 
-**Default mode when no integrations configured.** Events captured and emitted locally without network requests.
+Default when no `integrations` are configured. Events are captured, queued, and emitted locally — no network requests.
 
 ```typescript
 await tracelog.init();
 
-// Consume events locally
 tracelog.on('event', (event) => {
   myAnalytics.track(event);
 });
@@ -766,143 +270,76 @@ tracelog.on('queue', (batch) => {
 });
 ```
 
-**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
+Perfect for custom analytics pipelines, testing, or privacy-focused implementations where you want to ship events to your own destination via a listener.
 
 ### 2. TraceLog SaaS
-```typescript
-await tracelog.init({
-  integrations: {
-    tracelog: { projectId: 'your-project-id' }
-  }
-});
-```
 
-### 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'
-    }
+    tracelog: { projectId: 'your-project-id' }
   }
 });
 ```
 
-### 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)
-```
+**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`.
 
-**→ [Integration Setup Guide](./API_REFERENCE.md#integration-configuration)**
+**→ [Integration Reference](./API_REFERENCE.md#integration-configuration)**
 
 ---
 
 ## Error Handling & Reliability
 
-TraceLog implements intelligent error handling with automatic retries for transient failures:
+### Automatic retry strategy
 
-### Automatic Retry Strategy
+**Transient errors** (5xx, timeouts, network failures):
 
-**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
+- 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
 
-**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
+**Rate limit (429):**
 
-**Permanent Errors** (4xx except 408, 429):
-- **No retries** (immediate failure)
-- **Events discarded** (not persisted)
-- **Exception**: 408 Request Timeout is treated as transient
+- 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
 
-```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
+**Permanent errors** (4xx except 408, 429):
 
-// If custom backend succeeds:
-// - Events removed from queue (optimistic removal)
-// - Failed integration recovered on next page load
-```
+- No retries — events are discarded
+- 408 Request Timeout is treated as transient
 
-### Error Classification
+### Error classification
 
-| 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 |
+| 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 |
 
-### Optimistic Queue Management
+### Recovery on page load
 
-**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)
+Failed events are recovered automatically on the next `init()`:
 
-**Example Scenario:**
 ```typescript
-// 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
+// Page 1: events fail to send (5xx after retries) → persisted with idempotency token
+// Page 2: init() recovers and resends; backend deduplicates by idempotency token
 ```
 
-### Recovery on Page Load
+Multi-tab protection: a 1-second window prevents two tabs from re-sending the same persisted batch simultaneously.
 
-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)
-```
+**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.
 
 **→ [Full Error Handling Reference](./API_REFERENCE.md#error-handling)**
 
-### Session Continuity (External Redirects)
+### Session continuity across external redirects
 
-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.
+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.
 
 ```typescript
 // No special handling needed before redirect
@@ -914,7 +351,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)
 
@@ -922,26 +359,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, 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
+- ✅ **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
 
-**Example:**
 ```html
-<!-- Exclude sensitive forms -->
+<!-- Exclude sensitive forms entirely -->
 <div data-tlog-ignore>
   <input type="password" name="password">
   <input type="text" name="credit_card">
 </div>
 ```
 
-**Your Responsibilities:**
-- Get user consent before calling `init()` (GDPR/CCPA)
-- Sanitize custom event metadata (avoid PII)
+**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)
 - Call `destroy()` on consent revoke
 
 **→ [Complete Security Guide](./SECURITY.md)**
@@ -950,30 +387,20 @@ TraceLog is **privacy-first** by design:
 
 ## QA Mode
 
-Enable QA mode for debugging and development:
+QA mode logs custom events to the browser console so you can verify tracking implementation without inspecting the network tab.
 
-### URL Activation
-```bash
-# Enable
-?tlog_mode=qa
+### URL activation
 
-# Disable
-?tlog_mode=qa_off
-```
-
-### Programmatic API
-```typescript
-tracelog.setQaMode(true);   // Enable
-tracelog.setQaMode(false);  // Disable
+```text
+?tlog_mode=qa       # Enable (persists in sessionStorage for the tab)
+?tlog_mode=qa_off   # Disable
 ```
 
-**Features:**
-- Custom events logged to browser console
-- Strict validation (throws errors instead of warnings)
-- Session state visible in console
-- Persistent across page reloads (sessionStorage)
+**Effects in QA mode:**
 
-**→ [QA Mode Documentation](./API_REFERENCE.md#setqamodeenabled-boolean-void)**
+- 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)
 
 ---
 
@@ -984,7 +411,7 @@ tracelog.setQaMode(false);  // Disable
 - Safari 12+
 - Edge 79+
 
-**SSR/SSG Compatible:** Safe to import in Angular Universal, Next.js, Nuxt, SvelteKit (no-ops in Node.js).
+**SSR/SSG compatible** — safe to import in Angular Universal, Next.js, Nuxt, SvelteKit. All methods no-op in Node.js.
 
 ---
 
@@ -992,9 +419,9 @@ tracelog.setQaMode(false);  // Disable
 
 ```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 run test             # Run all tests
+npm test                 # Run all tests
 npm run test:coverage    # Generate coverage report
 ```
 
@@ -1006,10 +433,10 @@ npm run test:coverage    # Generate coverage report
 
 | Document | Description |
 |----------|-------------|
-| **[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 |
+| **[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 |
 | **[Handlers](./src/handlers/README.md)** | Event capture implementation details |
 | **[Managers](./src/managers/README.md)** | Core component architecture |