@tracelog/lib 2.9.0 → 2.10.0-rc.113.17

package/dist/public-api.d.ts

@@ -78,66 +78,10 @@ interface InitResult {
     sessionId: string;
 }
 
-/**
- * Element configuration for viewport tracking with optional identifiers
- */
-interface ViewportElement {
-    /**
-     * CSS selector for the element
-     * @example '.hero' | '.cta-button' | '#pricing'
-     */
-    selector: string;
-    /**
-     * Optional unique identifier for analytics
-     * Used to distinguish between multiple elements with the same selector
-     * @example 'homepage-hero' | 'pricing-cta' | 'customer-testimonials'
-     */
-    id?: string;
-    /**
-     * Optional human-readable name for dashboards and reports
-     * @example 'Homepage Hero Banner' | 'Pricing Page CTA' | 'Customer Testimonials Section'
-     */
-    name?: string;
-}
-/**
- * Configuration for viewport visibility tracking
- */
-interface ViewportConfig {
-    /**
-     * Elements to track with optional identifiers
-     * Provides analytics support with business identifiers
-     * @example [{ selector: '.hero', id: 'homepage-hero', name: 'Homepage Hero Banner' }]
-     */
-    elements: ViewportElement[];
-    /**
-     * Minimum percentage of element that must be visible (0-1)
-     * @default 0.5 (50%)
-     */
-    threshold?: number;
-    /**
-     * Minimum time (ms) element must be visible to count as a view
-     * @default 1000 (1 second)
-     */
-    minDwellTime?: number;
-    /**
-     * Cooldown period (ms) before same element can fire visibility event again
-     * Prevents repeated events from carousels, sticky headers, and scrolling patterns
-     * @default 60000 (60 seconds)
-     */
-    cooldownPeriod?: number;
-    /**
-     * Maximum number of elements to track simultaneously (Phase 3)
-     * Prevents memory/server issues with broad selectors
-     * @default 100
-     */
-    maxTrackedElements?: number;
-}
-
 /**
  * Coordinate information from a click event
- * Includes absolute and relative positioning
  */
-type ClickCoordinates = Pick<ClickData, 'x' | 'y' | 'relativeX' | 'relativeY'>;
+type ClickCoordinates = Pick<ClickData, 'x' | 'y'>;
 /**
  * Web performance metric types tracked by the library
  * - LCP: Largest Contentful Paint
@@ -145,9 +89,8 @@ type ClickCoordinates = Pick<ClickData, 'x' | 'y' | 'relativeX' | 'relativeY'>;
  * - INP: Interaction to Next Paint
  * - FCP: First Contentful Paint
  * - TTFB: Time to First Byte
- * - LONG_TASK: Tasks exceeding 50ms
  */
-type WebVitalType = 'LCP' | 'CLS' | 'INP' | 'FCP' | 'TTFB' | 'LONG_TASK';
+type WebVitalType = 'LCP' | 'CLS' | 'INP' | 'FCP' | 'TTFB';
 /**
  * Event type name
  */
@@ -169,32 +112,13 @@ declare enum EventType {
     /** Performance metrics */
     WEB_VITALS = "web_vitals",
     /** JavaScript errors and rejections */
-    ERROR = "error",
-    /** Element visibility tracking */
-    VIEWPORT_VISIBLE = "viewport_visible"
+    ERROR = "error"
 }
 /**
- * Per-session event counts structure for rate limiting
- *
- * **Purpose**: Tracks how many events of each type have been generated
- * during the current session to enforce per-session limits and prevent
- * runaway event generation.
- *
- * **Usage**:
- * - Persisted to localStorage: `tlog:{userId}:session_counts:{sessionId}`
- * - Restored on page reload to maintain limits across navigations
- * - Debounced writes for performance (500ms delay)
- *
- * **Limits** (from config.constants.ts):
- * - Total: 1000 events per session
- * - Clicks: 500 per session
- * - Page Views: 100 per session
- * - Custom: 500 per session
- * - Viewport: 200 per session
- * - Scroll: 120 per session
- *
- * @see src/managers/event.manager.ts for implementation
- * @see src/constants/config.constants.ts for limit values
+ * Per-session event counts structure for rate limiting.
+ *
+ * Persisted to localStorage: `tlog:{userId}:session_counts:{sessionId}`
+ * Restored on page reload to maintain limits across navigations.
  */
 interface SessionEventCounts {
     /** Total events across all types */
@@ -205,8 +129,6 @@ interface SessionEventCounts {
     [EventType.PAGE_VIEW]: number;
     /** Custom events count */
     [EventType.CUSTOM]: number;
-    /** Viewport visibility events count */
-    [EventType.VIEWPORT_VISIBLE]: number;
     /** Scroll events count */
     [EventType.SCROLL]: number;
     /** Index signature for dynamic event type access */
@@ -240,12 +162,6 @@ interface ScrollData {
     direction: ScrollDirection;
     /** CSS selector of the scrolled container */
     container_selector: string;
-    /** Whether this is the primary viewport scroll */
-    is_primary: boolean;
-    /** Scroll velocity in pixels per second */
-    velocity: number;
-    /** Maximum scroll depth reached during session (0-100) */
-    max_depth_reached: number;
 }
 /**
  * Click event data capturing user interaction details
@@ -255,10 +171,6 @@ interface ClickData {
     x: number;
     /** Absolute Y coordinate in viewport (pixels) */
     y: number;
-    /** Relative X position within element (0-1) */
-    relativeX: number;
-    /** Relative Y position within element (0-1) */
-    relativeY: number;
     /** Element ID attribute */
     id?: string;
     /** Element class attribute */
@@ -269,16 +181,6 @@ interface ClickData {
     text?: string;
     /** Link href for anchor elements */
     href?: string;
-    /** Element title attribute */
-    title?: string;
-    /** Image alt text for img elements */
-    alt?: string;
-    /** ARIA role attribute */
-    role?: string;
-    /** ARIA label attribute */
-    ariaLabel?: string;
-    /** Custom data attributes (data-*) */
-    dataAttributes?: Record<string, string>;
 }
 /**
  * Element data for specialized click tracking
@@ -301,6 +203,22 @@ interface CustomEventData {
     /** Additional event metadata */
     metadata?: Record<string, MetadataType> | Record<string, MetadataType>[];
 }
+/**
+ * Optional flags for `tracelog.event()`.
+ */
+interface EventOptions {
+    /**
+     * If `true`, the event queue is flushed via `navigator.sendBeacon()`
+     * immediately after this event is tracked. The browser guarantees the
+     * request is queued for delivery even if the page is about to unload.
+     *
+     * Use for high-value events where loss is unacceptable (Purchase, Signup,
+     * AddPaymentInfo).
+     *
+     * @default false
+     */
+    critical?: boolean;
+}
 /**
  * Web performance metrics data
  */
@@ -318,6 +236,8 @@ interface ErrorData {
     type: ErrorType;
     /** Error message text */
     message: string;
+    /** Error constructor name (TypeError, ReferenceError, etc.) when available */
+    name?: string;
     /** Source file where error occurred */
     filename?: string;
     /** Line number in source file */
@@ -350,27 +270,6 @@ interface PageViewData {
     referrer?: string;
     /** Page title from document */
     title?: string;
-    /** URL pathname */
-    pathname?: string;
-    /** URL query string */
-    search?: string;
-    /** URL hash fragment */
-    hash?: string;
-}
-/**
- * Data captured when element becomes visible
- */
-interface ViewportEventData {
-    /** CSS selector that matched the element */
-    selector: string;
-    /** Optional unique identifier for analytics (if configured) */
-    id?: string;
-    /** Optional human-readable name (if configured) */
-    name?: string;
-    /** Actual time (ms) element was visible before event fired */
-    dwellTime: number;
-    /** Actual visibility ratio when event fired (0-1) */
-    visibilityRatio: number;
 }
 /**
  * Complete event data structure
@@ -401,11 +300,20 @@ interface EventData {
     page_view?: PageViewData;
     /** Error details (when type is ERROR) */
     error_data?: ErrorData;
-    /** Viewport visibility details (when type is VIEWPORT_VISIBLE) */
-    viewport_data?: ViewportEventData;
     /** Campaign tracking parameters */
     utm?: UTM;
 }
+/**
+ * Internal queue entry: an `EventData` enriched with the session ID frozen at
+ * `track()` time. Survives session renewal — when the user is idle past the
+ * timeout, `state.sessionId` is nulled but events already in the queue keep
+ * their original `_session_id`, so `EventManager.buildBatchesWithIds()` can
+ * still attribute them correctly instead of emitting `session_id: null` to the
+ * wire.
+ */
+interface QueuedEvent extends EventData {
+    _session_id: string;
+}
 
 /**
  * Web Vitals filtering mode
@@ -425,10 +333,6 @@ interface Config {
     errorSampling?: number;
     /** Event sampling rate between 0 and 1. @default 1 */
     samplingRate?: number;
-    /** CSS selector to manually override primary scroll container detection. */
-    primaryScrollSelector?: string;
-    /** Viewport visibility tracking configuration. */
-    viewport?: ViewportConfig;
     /** Page view throttle duration in milliseconds to prevent rapid navigation spam. @default 1000 */
     pageViewThrottleMs?: number;
     /** Click throttle duration in milliseconds to prevent double-clicks and rapid spam. @default 300 */
@@ -449,36 +353,28 @@ interface Config {
     webVitalsThresholds?: Partial<Record<WebVitalType, number>>;
     /** Interval in milliseconds between event batch sends. @default 10000 (10 seconds) */
     sendIntervalMs?: number;
-    /** Optional configuration for third-party integrations. */
+    /**
+     * Opt-in: when `true`, the event queue is flushed after every SPA navigation
+     * (`pushState`, `replaceState`, `popstate`, `hashchange`). Defaults to `false`
+     * because per-route flushing can multiply request volume on SPA-heavy apps.
+     * @default false
+     */
+    flushOnSpaNavigation?: boolean;
+    /**
+     * If true, the event queue is flushed when `document.hidden` becomes `true`
+     * (tab switch, lock screen, app backgrounding). Especially relevant on mobile Safari
+     * where `pagehide`/`beforeunload` may not fire reliably.
+     * @default true
+     */
+    flushOnPageHidden?: boolean;
+    /** TraceLog SaaS integration. */
     integrations?: {
-        /** TraceLog integration options. */
         tracelog?: {
-            /** Required project ID TraceLog SaaS integration. */
+            /** Required project ID for TraceLog SaaS integration. */
             projectId: string;
             /** Enable Shopify cart attribute linking for webhook revenue attribution. */
             shopify?: boolean;
         };
-        /** Custom integration options. */
-        custom?: {
-            /** Endpoint for collecting events. */
-            collectApiUrl: string;
-            /** Allow HTTP URLs (not recommended for production). @default false */
-            allowHttp?: boolean;
-            /**
-             * Static HTTP headers to include in every request.
-             * For dynamic headers, use `setCustomHeaders()` instead.
-             * @example { 'X-Brand': 'my-brand', 'X-Tenant-Id': 'tenant-123' }
-             */
-            headers?: Record<string, string>;
-            /**
-             * Controls whether cookies and credentials are sent with fetch requests.
-             * - `'include'`: Always send cookies (even cross-origin) — required for cookie-based auth
-             * - `'same-origin'`: Only send cookies for same-origin requests
-             * - `'omit'`: Never send cookies
-             * @default 'include'
-             */
-            fetchCredentials?: RequestCredentials;
-        };
     };
 }
 declare enum SpecialApiUrl {
@@ -685,90 +581,15 @@ declare enum Mode {
     QA = "qa"
 }
 
-/**
- * Primary scroll event type (main viewport scroll)
- *
- * **Purpose**: Type-safe representation of primary viewport scroll events
- *
- * Primary scroll events track the main page/viewport scrolling,
- * which is the most important scroll metric for engagement analysis.
- */
-type PrimaryScrollEvent = EventData & {
-    type: EventType.SCROLL;
-    scroll_data: ScrollData & {
-        is_primary: true;
-    };
-};
-/**
- * Secondary scroll event type (scrollable container scroll)
- *
- * **Purpose**: Type-safe representation of container-specific scroll events
- *
- * Secondary scroll events track scrolling within specific elements
- * (e.g., modals, sidebars, embedded content) for granular engagement analysis.
- */
-type SecondaryScrollEvent = EventData & {
-    type: EventType.SCROLL;
-    scroll_data: ScrollData & {
-        is_primary: false;
-    };
-};
-/**
- * Type guard to check if an event is a primary scroll event
- *
- * **Purpose**: Runtime type narrowing for primary viewport scrolls
- *
- * **Use Cases**:
- * - Filter events to process only main viewport scrolling
- * - Separate primary from secondary scroll analytics
- * - Type-safe event processing in transformers
- *
- * @param event - Event to check
- * @returns `true` if event is a primary scroll event
- *
- * @example
- * ```typescript
- * if (isPrimaryScrollEvent(event)) {
- *   // event.scroll_data.is_primary is guaranteed to be true
- *   console.log('Main viewport scrolled to', event.scroll_data.depth, '%');
- * }
- * ```
- */
-declare const isPrimaryScrollEvent: (event: EventData) => event is PrimaryScrollEvent;
-/**
- * Type guard to check if an event is a secondary scroll event
- *
- * **Purpose**: Runtime type narrowing for container-specific scrolls
- *
- * **Use Cases**:
- * - Filter events to process only container scrolling
- * - Analyze engagement with specific page sections
- * - Type-safe event processing in transformers
- *
- * @param event - Event to check
- * @returns `true` if event is a secondary scroll event
- *
- * @example
- * ```typescript
- * if (isSecondaryScrollEvent(event)) {
- *   // event.scroll_data.is_primary is guaranteed to be false
- *   console.log('Container scrolled:', event.scroll_data.container_selector);
- * }
- * ```
- */
-declare const isSecondaryScrollEvent: (event: EventData) => event is SecondaryScrollEvent;
-
 interface State {
     /** QA mode flag - when true, custom events are logged to console */
     mode?: Mode;
     /**
      * Collection of API URLs for different integrations.
      * - saas: TraceLog SaaS endpoint (if projectId configured)
-     * - custom: Custom backend endpoint (if collectApiUrl configured)
      */
     collectApiUrls: {
         saas?: string;
-        custom?: string;
     };
     config: Config;
     sessionId: string | null;
@@ -784,6 +605,15 @@ interface State {
     identity?: IdentifyData;
 }
 
+/**
+ * Regular expressions used to detect and redact common PII patterns from
+ * free-form text (click text, error messages, stack traces, etc.).
+ *
+ * Mirrors the patterns relied on by `ClickHandler` and `ErrorHandler`. Adding
+ * a pattern here automatically widens coverage for both handlers.
+ */
+declare const PII_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
+
 /**
  * Type-safe event emitter for TraceLog internal events
  *
@@ -944,35 +774,15 @@ declare class Emitter {
 /**
  * Abstract base class providing centralized, type-safe state management.
  *
- * **Purpose**: Foundation for all TraceLog managers and handlers, providing
- * synchronized access to shared application state.
- *
- * **Architecture**:
- * - All managers/handlers extend this class
- * - Single global state instance shared across all subclasses
- * - Type-safe operations via generic methods
- * - In-memory only (no automatic persistence)
- *
- * **Supported State Properties**:
- * - **Core State**: `collectApiUrls`, `config`, `sessionId`, `userId`, `device`, `pageUrl`
- * - **Control Flags**: `mode` (QA/production), `hasStartSession`, `suppressNextScroll`
- * - **Runtime Counters**: `scrollEventCount` (optional)
- *
- * **Implementation Details**:
- * - Synchronous operations (no async overhead)
- * - Memory-efficient (minimal object creation)
- * - No built-in logging (consumers handle their own state logging)
- * - Read-only snapshots via `getState()` prevent accidental mutations
- *
- * @see src/managers/README.md (lines 170-201) for detailed documentation
+ * All managers/handlers extend this class. The global state is shared
+ * across every subclass instance.
  *
  * @example
  * ```typescript
  * class MyManager extends StateManager {
  *   initialize() {
- *     const userId = this.get('userId');      // Read state
- *     this.set('mode', 'qa');                 // Write state
- *     const snapshot = this.getState();       // Readonly copy
+ *     const userId = this.get('userId');
+ *     this.set('mode', 'qa');
  *   }
  * }
  * ```
@@ -980,52 +790,14 @@ declare class Emitter {
 declare abstract class StateManager {
     /**
      * Retrieves a value from global state.
-     *
-     * Type-safe getter with compile-time key validation.
-     *
-     * @template T - State key type (compile-time validated)
-     * @param key - State property key
-     * @returns Current value for the given key (may be undefined)
-     *
-     * @example
-     * ```typescript
-     * const userId = this.get('userId');
-     * const config = this.get('config');
-     * const sessionId = this.get('sessionId');
-     * ```
      */
     protected get<T extends keyof State>(key: T): State[T];
     /**
      * Sets a value in global state.
-     *
-     * Type-safe setter with compile-time type checking.
-     * Changes are immediately visible to all StateManager subclasses.
-     *
-     * @template T - State key type (compile-time validated)
-     * @param key - State property key
-     * @param value - New value (type must match State[T])
-     *
-     * @example
-     * ```typescript
-     * this.set('sessionId', 'session-123');
-     * this.set('mode', Mode.QA);
-     * this.set('hasStartSession', true);
-     * ```
      */
     protected set<T extends keyof State>(key: T, value: State[T]): void;
     /**
      * Returns an immutable snapshot of the entire global state.
-     *
-     * Creates a shallow copy to prevent accidental mutations.
-     * Use for debugging or when multiple state properties are needed.
-     *
-     * @returns Readonly shallow copy of global state
-     *
-     * @example
-     * ```typescript
-     * const snapshot = this.getState();
-     * console.log(snapshot.userId, snapshot.sessionId);
-     * ```
      */
     protected getState(): Readonly<State>;
 }
@@ -1033,212 +805,29 @@ declare abstract class StateManager {
 /**
  * Robust localStorage and sessionStorage wrapper with automatic fallback to in-memory storage.
  *
- * **Purpose**: Provides consistent storage APIs across all browser environments,
- * handling quota limits, privacy modes, and SSR scenarios gracefully.
- *
- * **Core Functionality**:
- * - **Dual Storage**: localStorage (persistent) and sessionStorage (tab-scoped)
- * - **Automatic Fallback**: In-memory Maps when browser storage unavailable
- * - **Quota Handling**: Intelligent cleanup on QuotaExceededError
- * - **SSR-Safe**: No-op in Node.js environments
- *
- * **Key Features**:
- * - Separate fallback Maps for each storage type
- * - Storage quota error handling with automatic cleanup and retry
- * - Intelligent cleanup: Prioritizes removing persisted events over critical data
- * - Preserves: session, user, device, and config keys during cleanup
- * - Test key validation during initialization (`__tracelog_test__`)
- * - Public `isAvailable()` and `hasQuotaError()` for conditional logic
- * - Explicit `clear()` method for TraceLog-namespaced data only (`tracelog_*` prefix)
- *
- * **Cleanup Strategy** (on QuotaExceededError):
- * 1. Remove persisted events (`tracelog_persisted_events_*`) - usually largest data
- * 2. If no persisted events, remove up to 5 non-critical keys
- * 3. Preserve critical keys: `tracelog_session_*`, `tracelog_user_id`, `tracelog_device_id`, `tracelog_config`
- *
- * @see src/managers/README.md (lines 203-226) for detailed documentation
- *
- * @example
- * ```typescript
- * const storage = new StorageManager();
- *
- * // localStorage operations
- * storage.setItem('key', 'value');
- * const value = storage.getItem('key');
- * storage.removeItem('key');
- *
- * // sessionStorage operations
- * storage.setSessionItem('session_key', 'data');
- * const sessionValue = storage.getSessionItem('session_key');
- *
- * // Check availability
- * if (storage.isAvailable()) {
- *   // localStorage is working
- * }
- *
- * // Check for quota issues
- * if (storage.hasQuotaError()) {
- *   // Data may not persist
- * }
- * ```
+ * - Dual storage: localStorage (persistent) + sessionStorage (tab-scoped).
+ * - Automatic in-memory fallback when browser storage unavailable (privacy modes, SSR).
+ * - On `QuotaExceededError`: single-pass cleanup — purges `tracelog_persisted_events_*`
+ *   first (largest, recoverable), retries once. Preserves session/user/device/config keys.
  */
 declare class StorageManager {
     private readonly storage;
     private readonly sessionStorageRef;
     private readonly fallbackStorage;
     private readonly fallbackSessionStorage;
-    private hasQuotaExceededError;
     constructor();
-    /**
-     * Retrieves an item from localStorage.
-     *
-     * Automatically falls back to in-memory storage if localStorage unavailable.
-     *
-     * @param key - Storage key
-     * @returns Stored value or null if not found
-     */
     getItem(key: string): string | null;
-    /**
-     * Stores an item in localStorage with automatic quota handling.
-     *
-     * **Behavior**:
-     * 1. Updates fallback storage first (ensures consistency)
-     * 2. Attempts to store in localStorage
-     * 3. On QuotaExceededError: Triggers cleanup and retries once
-     * 4. Falls back to in-memory storage if retry fails
-     *
-     * **Cleanup on Quota Error**:
-     * - Removes persisted events (largest data)
-     * - Removes up to 5 non-critical keys
-     * - Preserves session, user, device, and config keys
-     *
-     * @param key - Storage key
-     * @param value - String value to store
-     */
     setItem(key: string, value: string): void;
-    /**
-     * Removes an item from localStorage and fallback storage.
-     *
-     * Safe to call even if key doesn't exist (idempotent).
-     *
-     * @param key - Storage key to remove
-     */
     removeItem(key: string): void;
     /**
-     * Clears all TraceLog-related items from storage.
-     *
-     * Only removes keys with `tracelog_` prefix (safe for shared storage).
-     * Clears both localStorage and fallback storage.
-     *
-     * **Use Cases**:
-     * - User logout/privacy actions
-     * - Development/testing cleanup
-     * - Reset analytics state
-     */
-    clear(): void;
-    /**
-     * Checks if localStorage is available.
-     *
-     * @returns true if localStorage is working, false if using fallback
-     */
-    isAvailable(): boolean;
-    /**
-     * Checks if a QuotaExceededError has occurred during this session.
-     *
-     * **Purpose**: Detect when localStorage is full and data may not persist.
-     * Allows application to show warnings or adjust behavior.
-     *
-     * **Note**: Flag is set on first QuotaExceededError and never reset.
-     *
-     * @returns true if quota exceeded at any point during this session
-     */
-    hasQuotaError(): boolean;
-    /**
-     * Implements two-phase cleanup strategy to free storage space when quota exceeded.
-     *
-     * **Purpose**: Removes TraceLog data intelligently to make room for new writes
-     * while preserving critical user state (session, user ID, device ID, config).
-     *
-     * **Two-Phase Cleanup Strategy**:
-     * 1. **Phase 1 (Priority)**: Remove all persisted events (`tracelog_persisted_events_*`)
-     *    - These are typically the largest data items (batches of events)
-     *    - Safe to remove as they represent recoverable failed sends
-     *    - Returns immediately if any persisted events found and removed
-     *
-     * 2. **Phase 2 (Fallback)**: Remove up to 5 non-critical keys
-     *    - Only executed if no persisted events found
-     *    - Preserves critical keys: session data, user ID, device ID, config
-     *    - Limits to 5 keys to avoid excessive cleanup time
-     *
-     * **Critical Keys (Never Removed)**:
-     * - `tracelog_session_*` - Active session data
-     * - `tracelog_user_id` - User identification
-     * - `tracelog_device_id` - Device fingerprint
-     * - `tracelog_config` - Configuration cache
-     *
-     * **Error Handling**:
-     * - Individual key removal failures silently ignored (continue cleanup)
-     * - Overall cleanup errors logged and return false
-     *
-     * @returns true if any data was successfully removed, false if nothing cleaned up
+     * Single-pass cleanup for QuotaExceededError. Purges persisted-events keys
+     * (largest, safe to discard — recoverable) and up to 5 other non-critical
+     * tracelog_* keys in one pass. Preserves session/user/device/config keys.
      */
     private cleanupOldData;
-    /**
-     * Initializes storage with feature detection and write-test validation.
-     *
-     * **Purpose**: Validates storage availability by performing actual write/remove test,
-     * preventing false positives in privacy modes where storage API exists but throws on write.
-     *
-     * **Validation Strategy**:
-     * 1. SSR Safety: Returns null in Node.js environments (`typeof window === 'undefined'`)
-     * 2. API Check: Verifies storage object exists on window
-     * 3. Write Test: Attempts to write test key (`__tracelog_test__`)
-     * 4. Cleanup: Removes test key immediately after validation
-     *
-     * **Why Write Test is Critical**:
-     * - Safari private browsing: storage API exists but throws QuotaExceededError on write
-     * - iOS private mode: storage appears available but operations fail
-     * - Incognito modes: API exists but writes are silently ignored or throw
-     *
-     * **Fallback Behavior**:
-     * - Returns null if storage unavailable or test fails
-     * - Caller automatically falls back to in-memory Map storage
-     *
-     * @param type - Storage type to initialize ('localStorage' | 'sessionStorage')
-     * @returns Storage instance if available and writable, null otherwise
-     */
     private initializeStorage;
-    /**
-     * Retrieves an item from sessionStorage.
-     *
-     * Automatically falls back to in-memory storage if sessionStorage unavailable.
-     *
-     * @param key - Storage key
-     * @returns Stored value or null if not found
-     */
     getSessionItem(key: string): string | null;
-    /**
-     * Stores an item in sessionStorage with quota error detection.
-     *
-     * **Behavior**:
-     * 1. Updates fallback storage first (ensures consistency)
-     * 2. Attempts to store in sessionStorage
-     * 3. On QuotaExceededError: Logs error and uses fallback (no retry/cleanup)
-     *
-     * **Note**: sessionStorage quota errors are rare (typically 5-10MB per tab).
-     * No automatic cleanup unlike localStorage.
-     *
-     * @param key - Storage key
-     * @param value - String value to store
-     */
     setSessionItem(key: string, value: string): void;
-    /**
-     * Removes an item from sessionStorage and fallback storage.
-     *
-     * Safe to call even if key doesn't exist (idempotent).
-     *
-     * @param key - Storage key to remove
-     */
     removeSessionItem(key: string): void;
 }
 
@@ -1308,7 +897,6 @@ declare class StorageManager {
 declare class EventManager extends StateManager {
     private readonly dataSenders;
     private readonly emitter;
-    private readonly transformers;
     private readonly timeManager;
     private readonly recentEventFingerprints;
     private readonly perEventRateLimits;
@@ -1320,23 +908,16 @@ declare class EventManager extends StateManager {
     private rateLimitCounter;
     private rateLimitWindowStart;
     private lastSessionId;
+    private pendingSyncFlush;
     private sessionEventCounts;
     private readonly saveSessionCountsDebounced;
     /**
      * Creates an EventManager instance.
      *
-     * **Initialization**:
-     * - Creates SenderManager instances for configured integrations (SaaS/Custom)
-     * - Initializes event emitter for local consumption
-     *
      * @param storeManager - Storage manager for persistence
      * @param emitter - Optional event emitter for local event consumption
-     * @param transformers - Optional event transformation hooks
-     * @param staticHeaders - Optional static HTTP headers for custom backend (from config)
-     * @param customHeadersProvider - Optional callback for dynamic headers
-     * @param fetchCredentials - Fetch credentials mode for custom backend. @default 'include'
      */
-    constructor(storeManager: StorageManager, emitter?: Emitter | null, transformers?: TransformerMap, staticHeaders?: Record<string, string>, customHeadersProvider?: CustomHeadersProvider, fetchCredentials?: RequestCredentials);
+    constructor(storeManager: StorageManager, emitter?: Emitter | null);
     /**
      * Recovers persisted events from localStorage after a crash or page reload.
      *
@@ -1421,7 +1002,7 @@ declare class EventManager extends StateManager {
      *
      * @see src/managers/README.md (lines 5-75) for detailed tracking logic
      */
-    track({ type, page_url, from_page_url, scroll_data, click_data, custom_event, web_vitals, error_data, viewport_data, page_view, }: Partial<EventData>): void;
+    track({ type, page_url, from_page_url, scroll_data, click_data, custom_event, web_vitals, error_data, page_view, }: Partial<EventData>): void;
     /**
      * Stops event tracking and clears all queues and buffers.
      *
@@ -1477,7 +1058,10 @@ declare class EventManager extends StateManager {
      * **Note**: For page unload, use `flushImmediatelySync()` instead,
      * which uses `sendBeacon()` for guaranteed delivery.
      *
-     * @returns Promise resolving to `true` if all sends succeeded, `false` if any failed
+     * @returns Promise resolving to `true` if at least one integration accepted
+     *          the batch during this call (optimistic removal — failures
+     *          persist per-integration for retry). `false` if no events, all
+     *          senders failed, or a flush is already in flight.
      *
      * @example
      * ```typescript
@@ -1513,7 +1097,14 @@ declare class EventManager extends StateManager {
      * - No retry on failure (sendBeacon is fire-and-forget)
      * - 64KB payload limit (large batches may be truncated)
      *
-     * @returns `true` if all sends succeeded, `false` if any failed
+     * **In-flight contract**: if an async send is already running this call is
+     * deferred (queued for replay in the async send's `finally` block) and
+     * returns `false` — nothing has been delivered yet at the point of return.
+     * Mirrors `flushImmediately()`'s behaviour for the same condition.
+     *
+     * @returns `true` if at least one integration accepted the beacon batch
+     *          *during this call*, `false` otherwise (no events, all senders
+     *          failed, or the call was deferred behind an in-flight async send)
      *
      * @example
      * ```typescript
@@ -1527,17 +1118,6 @@ declare class EventManager extends StateManager {
      * @see src/managers/README.md (lines 5-75) for flush details
      */
     flushImmediatelySync(): boolean;
-    /**
-     * Sets the custom headers provider callback for the custom integration.
-     * Only affects requests to custom backend (not TraceLog SaaS).
-     *
-     * @param provider - Callback function that returns custom headers
-     */
-    setCustomHeadersProvider(provider: CustomHeadersProvider): void;
-    /**
-     * Removes the custom headers provider callback from the custom integration.
-     */
-    removeCustomHeadersProvider(): void;
     /**
      * Returns the current number of events in the main queue.
      *
@@ -1628,9 +1208,79 @@ declare class EventManager extends StateManager {
     flushPendingEvents(): void;
     private clearSendTimeout;
     private isSuccessfulResult;
+    /**
+     * Groups the queue by frozen `_session_id`, preserving insertion order.
+     * Single pass — `buildBatchesWithIds()` builds one batch + one eventIds list
+     * per group, so the grouping cost is O(N) per flush regardless of session
+     * count.
+     *
+     * **Self-heal**: any entry missing `_session_id` (an internal invariant
+     * violation — `buildEventPayload` always stamps it) is removed from the
+     * queue rather than left behind, otherwise a single corrupted entry would
+     * keep `eventsQueue.length > 0` forever and re-trigger periodic sends.
+     */
+    private groupQueuedEventsBySession;
+    /**
+     * Builds a parallel list of `(batch, eventIds)` for sending. The eventIds are
+     * the original `_session_id`-tagged event IDs in the queue that map to this
+     * batch — used for optimistic removal. We can't read them off the wrapper's
+     * `events[]` because dedup may have removed some signatures.
+     */
+    private buildBatchesWithIds;
     private flushEvents;
+    /**
+     * Reconciles the periodic send timer after a flush attempt. Clears the
+     * timer when the queue is empty, otherwise (re)schedules a retry tick.
+     *
+     * **Why**: a `flushImmediately()` / `flushImmediatelySync()` call where all
+     * integrations fail leaves events in `eventsQueue` for retry. The periodic
+     * timer is the safety net that drains them when the backend recovers — if
+     * we cleared it unconditionally here, the queue would sit untouched until
+     * the next tracked event resurrects the timer in `addToQueue`. Mirrors the
+     * pattern in `sendEventsQueue()` (the periodic path).
+     */
+    private settleSendTimeout;
+    /**
+     * Re-runs a sync flush that was deferred while an async send was in flight.
+     *
+     * Called from the `finally` blocks of `flushEvents(false)` and
+     * `sendEventsQueue()`. If `pendingSyncFlush` is set, clears the flag and
+     * invokes `flushImmediatelySync()` synchronously so any events that arrived
+     * after the deferred sync call are delivered before the next event loop
+     * tick. Critical for high-stakes events tracked mid-async-send.
+     */
+    private drainPendingSyncFlush;
+    /**
+     * Sends one batch synchronously across all integrations (sendBeacon path).
+     * Optimistic removal: if any integration succeeds, we remove the batch's
+     * events from the queue and emit it locally. Failures persist per-integration.
+     */
+    private sendBatchSync;
+    /**
+     * Sends one batch asynchronously across all integrations (fetch path).
+     */
+    private sendBatchAsync;
     private sendEventsQueue;
-    private buildEventsPayload;
+    /**
+     * Builds a single batch from a per-session group: dedup by signature,
+     * SESSION_START first, then timestamp order, strip `_session_id`, apply
+     * `beforeBatch` transformer when running standalone.
+     *
+     * **Why N batches per flush**: events freeze their `_session_id` at `track()`
+     * time. If the session was renewed (idle timeout) between two `track()`
+     * calls, the queue contains events from multiple sessions. `buildBatchesWithIds()`
+     * emits one batch per session so the backend's `EventsQueueDto.session_id`
+     * remains the single source of truth and stays consistent with the events it
+     * carries.
+     *
+     * **Strip**: `_session_id` is removed from each event in the wrapper's
+     * `events[]` because the backend uses `forbidNonWhitelisted: true` and would
+     * reject the batch if the field leaked through.
+     *
+     * **Transformer note**: `beforeBatch` is invoked **once per session-batch**,
+     * not once per flush. A queue spanning N sessions triggers N invocations.
+     */
+    private buildBatchFromGroup;
     private buildEventPayload;
     private isDuplicateEvent;
     private pruneOldFingerprints;
@@ -1765,7 +1415,6 @@ declare class EventManager extends StateManager {
  * - Custom threshold overrides via webVitalsThresholds config
  * - Navigation-based deduplication with 50-navigation FIFO history
  * - CLS accumulation with reset on navigation change
- * - Long task throttling (maximum 1 event per second)
  * - Automatic fallback to Performance Observer if web-vitals library fails
  * - Final values only (reportAllChanges: false for all metrics)
  *
@@ -1777,7 +1426,6 @@ declare class EventManager extends StateManager {
  * - FCP (First Contentful Paint): Initial rendering time
  * - TTFB (Time to First Byte): Server response time
  * - INP (Interaction to Next Paint): Responsiveness measure
- * - LONG_TASK: Tasks blocking main thread (>50ms, throttled to 1/second)
  *
  * **Filtering Modes**:
  * - 'all': Track all positive metric values (threshold = 0)
@@ -1798,7 +1446,6 @@ declare class PerformanceHandler extends StateManager {
     private readonly navigationHistory;
     private readonly observers;
     private vitalThresholds;
-    private lastLongTaskSentAt;
     private navigationCounter;
     constructor(eventManager: EventManager);
     /**
@@ -1811,7 +1458,6 @@ declare class PerformanceHandler extends StateManager {
      * - Reads webVitalsMode from config ('all', 'needs-improvement', 'poor')
      * - Merges webVitalsThresholds with mode defaults for custom thresholds
      * - Initializes web-vitals library observers (LCP, CLS, FCP, TTFB, INP)
-     * - Starts long task observation with 1/second throttling
      *
      * @returns Promise that resolves when tracking is initialized
      */
@@ -1829,7 +1475,6 @@ declare class PerformanceHandler extends StateManager {
     private observeWebVitalsFallback;
     private initWebVitals;
     private reportTTFB;
-    private observeLongTasks;
     private sendVital;
     private trackWebVital;
     /**
@@ -1871,45 +1516,70 @@ declare class PerformanceHandler extends StateManager {
  * - Message truncation (500 character limit)
  * - Burst detection (>10 errors/second triggers 5-second cooldown)
  * - Deduplication within 5-second window per error type+message
+ * - Per-pageview signature cap (`MAX_ERRORS_PER_SIGNATURE_PER_PAGEVIEW`): after the
+ *   5s dedup window expires, the same `(normalizedMessage, filename, line)` may only
+ *   recur up to N times per pageview. Counter resets on `pagehide`, `SESSION_START`,
+ *   and `PAGE_VIEW` (covers SPA navigation via patched History API + popstate/hashchange).
  *
  * **Privacy Protection**:
  * - Automatically redacts PII from error messages before storage
  * - Sanitizes emails, phone numbers, credit cards, IBAN, API keys, Bearer tokens
  *
- * @see src/handlers/README.md (lines 167-218) for detailed documentation
+ * @see src/handlers/README.md (`## ErrorHandler` section) for detailed documentation
  */
 declare class ErrorHandler extends StateManager {
     private readonly eventManager;
+    private readonly emitter?;
     private readonly recentErrors;
+    private readonly pageviewSignatureCounts;
     private errorBurstCounter;
     private burstWindowStart;
     private burstBackoffUntil;
-    constructor(eventManager: EventManager);
+    private pagehideHandler;
+    private pageviewResetListener;
+    constructor(eventManager: EventManager, emitter?: Emitter);
     /**
      * Starts tracking JavaScript errors and promise rejections.
      *
      * - Registers global error event listener
      * - Registers unhandledrejection event listener
+     * - Registers pagehide listener to reset the per-pageview signature counter
+     * - Subscribes to emitter SESSION_START + PAGE_VIEW to reset the counter on new
+     *   sessions and SPA route changes (the only signal `pagehide` does not cover)
      */
     startTracking(): void;
     /**
      * Stops tracking errors and cleans up resources.
      *
      * - Removes error event listeners
-     * - Clears recent errors map
+     * - Removes pagehide listener and unsubscribes from emitter
+     * - Clears recent errors and pageview signature counters
      * - Resets burst detection counters
      */
     stopTracking(): void;
+    /**
+     * Clears the per-pageview signature counter.
+     *
+     * Public so `App` or tests can drive a reset explicitly; the handler itself wires
+     * `pagehide` and emitter `SESSION_START` / `PAGE_VIEW` in `startTracking()`.
+     */
+    resetPageviewCounter(): void;
     /**
      * Checks sampling rate and burst detection
      * Returns false if in cooldown period after burst detection
      */
     private shouldSample;
+    /**
+     * Returns true when the per-pageview signature cap has been hit for this error.
+     * Dropped errors do not increment the counter — the 5s suppression window already
+     * silences identical repeats, and double-counting here would skew the cap for any
+     * later signature that recycles the same map key after a counter reset.
+     */
+    private shouldThrottleBySignature;
     private readonly handleError;
     private readonly handleRejection;
     private extractRejectionMessage;
     private sanitize;
-    private sanitizePii;
     private shouldSuppressError;
     private static readonly TRUNCATION_SUFFIX;
     private truncateStack;
@@ -2136,128 +1806,36 @@ declare class ClickHandler extends StateManager {
     private getElementPath;
     private findTrackingElement;
     private getRelevantClickElement;
-    /**
-     * Clamps relative coordinate values to [0, 1] range with 3 decimal precision.
-     *
-     * @param value - Raw relative coordinate value
-     * @returns Clamped value between 0 and 1 with 3 decimal places (e.g., 0.123)
-     *
-     * @example
-     * clamp(1.234)   // returns 1.000
-     * clamp(0.12345) // returns 0.123
-     * clamp(-0.5)    // returns 0.000
-     */
-    private clamp;
     private calculateClickCoordinates;
     private extractTrackingData;
     private generateClickData;
-    /**
-     * Sanitizes text by replacing PII patterns with [REDACTED].
-     *
-     * Protects against:
-     * - Email addresses
-     * - Phone numbers (US format)
-     * - Credit card numbers
-     * - IBAN numbers
-     * - API keys/tokens
-     * - Bearer tokens
-     *
-     * @param text - Raw text content from element
-     * @returns Sanitized text with PII replaced by [REDACTED]
-     *
-     * @example
-     * sanitizeText('Email: user@example.com')      // returns 'Email: [REDACTED]'
-     * sanitizeText('Card: 1234-5678-9012-3456')    // returns 'Card: [REDACTED]'
-     * sanitizeText('Bearer token123')              // returns '[REDACTED]'
-     */
-    private sanitizeText;
     private getRelevantText;
-    private extractElementAttributes;
     private createCustomEventData;
 }
 
 /**
- * Tracks scroll depth, direction, velocity, and container identification across multiple scrollable elements.
+ * Tracks scroll depth and direction across the window and any detected scrollable containers.
  *
- * **Features**:
- * - Automatic container detection with intelligent retry (5 attempts @ 200ms intervals)
- * - Manual override via primaryScrollSelector config
- * - Smart filtering with multiple guardrails:
- *   - Visibility check (element must be connected to DOM with dimensions)
- *   - Scrollability check (content must overflow container)
- *   - Significant movement (minimum 10px position delta)
- *   - Depth change (minimum 5% depth change between events)
- *   - Rate limiting (minimum 500ms interval between events per container)
- *   - Session cap (maximum 120 events per session with single warning)
- * - Multi-container support with per-container debouncing (250ms)
- * - Velocity calculation for engagement analysis
- * - Max depth tracking per session
- * - Primary vs secondary container classification
- *
- * **Events Generated**: `scroll`
- *
- * **Analytics Fields**:
- * - depth: Current scroll depth (0-100%)
- * - direction: 'up' | 'down'
- * - container_selector: CSS selector or 'window'
- * - is_primary: Boolean indicating main scroll container
- * - velocity: Scroll speed in px/s
- * - max_depth_reached: Peak engagement per container
- *
- * **Container Detection**:
- * - Uses TreeWalker for performance
- * - Pre-filters elements with overflow: auto/scroll CSS properties
- * - Validates visibility and scrollability
- * - Retries up to 5 times for dynamically loaded content (SPAs)
- * - Falls back to window-only if no containers found
+ * **Captured fields**: `depth` (0-100), `direction` (up/down), `container_selector`.
  *
- * @example
- * ```typescript
- * const handler = new ScrollHandler(eventManager);
- * handler.startTracking();
- * // Automatically detects and tracks scrollable containers
- * handler.stopTracking();
- * ```
+ * **Guardrails**:
+ * - Significant movement (minimum 10px position delta)
+ * - Depth change (minimum 5% delta between events)
+ * - Rate limiting (minimum 500ms interval between events per container)
+ * - Session cap (maximum 120 events per session)
+ * - Multi-container support with 250ms per-container debouncing
  */
 declare class ScrollHandler extends StateManager {
     private readonly eventManager;
     private readonly containers;
     private limitWarningLogged;
-    private minDepthChange;
-    private minIntervalMs;
-    private maxEventsPerSession;
     private containerDiscoveryTimeoutId;
     constructor(eventManager: EventManager);
-    /**
-     * Starts tracking scroll events across all detected scrollable containers.
-     *
-     * Automatically detects scrollable containers using TreeWalker with retry logic:
-     * - Searches DOM for elements with overflow: auto/scroll
-     * - Validates visibility and scrollability
-     * - Retries up to 5 times with 200ms intervals for dynamic content
-     * - Falls back to window-only tracking if no containers found
-     * - Applies primaryScrollSelector config override if provided
-     *
-     * Attaches debounced scroll listeners (250ms per container) with smart filtering:
-     * - Significant movement (10px minimum)
-     * - Depth change (5% minimum)
-     * - Rate limiting (500ms minimum interval)
-     * - Session cap (120 events maximum)
-     */
     startTracking(): void;
-    /**
-     * Stops tracking scroll events and cleans up resources.
-     *
-     * Removes all scroll event listeners, clears debounce timers, cancels retry attempts,
-     * and resets session state (event counter, warning flags). Prevents memory leaks by
-     * properly cleaning up all containers and timers.
-     */
     stopTracking(): void;
     private tryDetectScrollContainers;
-    private applyPrimaryScrollSelectorIfConfigured;
     private findScrollableElements;
     private getElementSelector;
-    private determineIfPrimary;
     private setupScrollContainer;
     private processScrollEvent;
     private shouldEmitScrollEvent;
@@ -2265,7 +1843,6 @@ declare class ScrollHandler extends StateManager {
     private hasElapsedMinimumInterval;
     private hasSignificantDepthChange;
     private logLimitOnce;
-    private applyConfigOverrides;
     private isWindowScrollable;
     private clearContainerTimer;
     private getScrollDirection;
@@ -2275,101 +1852,7 @@ declare class ScrollHandler extends StateManager {
     private getViewportHeight;
     private getScrollHeight;
     private isElementScrollable;
-    private applyPrimaryScrollSelector;
-    private updateContainerPrimary;
-}
-
-/**
- * Handles viewport visibility tracking using IntersectionObserver API.
- * Fires events when elements become visible for a minimum dwell time.
- */
-declare class ViewportHandler extends StateManager {
-    private readonly eventManager;
-    private readonly trackedElements;
-    private observer;
-    private mutationObserver;
-    private mutationDebounceTimer;
-    private config;
-    constructor(eventManager: EventManager);
-    /**
-     * Starts tracking viewport visibility for configured elements
-     */
-    startTracking(): void;
-    /**
-     * Stops tracking and cleans up resources
-     */
-    stopTracking(): void;
-    /**
-     * Query and observe all elements matching configured elements
-     */
-    private observeElements;
-    /**
-     * Handles intersection events from IntersectionObserver
-     */
-    private readonly handleIntersection;
-    /**
-     * Fires a viewport visible event
-     */
-    private fireViewportEvent;
-    /**
-     * Sets up MutationObserver to detect dynamically added elements
-     */
-    private setupMutationObserver;
-    /**
-     * Cleans up tracking for removed DOM nodes
-     */
-    private cleanupRemovedNodes;
-}
-
-/**
- * Transform individual events before sending to backend.
- * Applied per-event, can filter by returning null.
- *
- * @param event - The event to transform
- * @returns Transformed event or null to filter
- */
-type BeforeSendTransformer = (event: EventData) => EventData | null;
-/**
- * Transform entire batch before sending to backend.
- * Applied per-batch (10s interval or 50 events), can filter by returning null.
- *
- * @param batch - The batch to transform
- * @returns Transformed batch or null to filter
- */
-type BeforeBatchTransformer = (batch: EventsQueue) => EventsQueue | null;
-/**
- * Runtime transformer hooks that can be updated after initialization
- * - 'beforeSend': Transform per-event before sending to backend
- * - 'beforeBatch': Transform entire batch before sending to backend
- */
-type TransformerHook = 'beforeSend' | 'beforeBatch';
-/**
- * Strongly-typed transformer map for internal storage
- */
-interface TransformerMap {
-    beforeSend?: BeforeSendTransformer;
-    beforeBatch?: BeforeBatchTransformer;
 }
-/**
- * Callback function for providing dynamic HTTP headers.
- *
- * Called synchronously before each fetch request to custom backends.
- * Return empty object {} to send no custom headers.
- *
- * **Note**: Only applies to `custom` integration (not TraceLog SaaS).
- * Headers are NOT applied to sendBeacon requests (page unload).
- *
- * @returns Record of header names to values
- *
- * @example
- * ```typescript
- * tracelog.setCustomHeaders(() => ({
- *   'Authorization': `Bearer ${getAuthToken()}`,
- *   'X-Request-ID': crypto.randomUUID()
- * }));
- * ```
- */
-type CustomHeadersProvider = () => Record<string, string>;
 
 /**
  * Testing bridge interface for E2E and integration tests
@@ -2384,25 +1867,16 @@ interface TraceLogTestBridge {
     readonly initialized: boolean;
     init(config?: Config): Promise<InitResult>;
     destroy(force?: boolean): void;
-    sendCustomEvent(name: string, data?: Record<string, unknown> | Record<string, unknown>[]): void;
-    event(name: string, metadata?: Record<string, unknown> | Record<string, unknown>[]): void;
+    sendCustomEvent(name: string, data?: Record<string, unknown> | Record<string, unknown>[], options?: EventOptions): void;
+    event(name: string, metadata?: Record<string, unknown> | Record<string, unknown>[], options?: EventOptions): void;
     on(event: string, callback: (data: any) => void): void;
     off(event: string, callback: (data: any) => void): void;
     get<T extends keyof State>(key: T): State[T];
     getFullState(): Readonly<State>;
     getState(): Readonly<State>;
-    updateGlobalMetadata(metadata: Record<string, unknown>): void;
-    mergeGlobalMetadata(metadata: Record<string, unknown>): void;
     getSessionData(): Record<string, unknown> | null;
     getQueueLength(): number;
     getQueueEvents(): EventData[];
-    setQaMode(enabled: boolean): void;
-    setTransformer(hook: 'beforeSend', fn: BeforeSendTransformer): void;
-    setTransformer(hook: 'beforeBatch', fn: BeforeBatchTransformer): void;
-    setTransformer(hook: TransformerHook, fn: BeforeSendTransformer | BeforeBatchTransformer): void;
-    removeTransformer(hook: TransformerHook): void;
-    setCustomHeaders(provider: CustomHeadersProvider): void;
-    removeCustomHeaders(): void;
     getEventManager(): EventManager | undefined;
     getStorageManager(): StorageManager | null;
     getPerformanceHandler(): PerformanceHandler | null;
@@ -2411,7 +1885,6 @@ interface TraceLogTestBridge {
     getPageViewHandler(): PageViewHandler | null;
     getClickHandler(): ClickHandler | null;
     getScrollHandler(): ScrollHandler | null;
-    getViewportHandler(): ViewportHandler | null;
     getHandlers(): {
         performance: PerformanceHandler | null;
         error: ErrorHandler | null;
@@ -2419,7 +1892,6 @@ interface TraceLogTestBridge {
         pageView: PageViewHandler | null;
         click: ClickHandler | null;
         scroll: ScrollHandler | null;
-        viewport: ViewportHandler | null;
     };
     identify(userId: string, traits?: Record<string, string>): void;
     resetIdentity(): Promise<void>;
@@ -2487,31 +1959,6 @@ declare global {
     }
 }
 
-/**
- * Transforms events at runtime before sending to custom backend.
- *
- * Note: Only applies to custom backend integration. TraceLog SaaS ignores transformers.
- *
- * @param hook - 'beforeSend' (per-event) or 'beforeBatch' (batch-level)
- * @param fn - Transformer function. Return null to filter event/batch.
- * @throws {Error} If called during destroy()
- * @throws {Error} If fn is not a function
- *
- * @example
- * ```typescript
- * tracelog.setTransformer('beforeSend', (data) => {
- *   if ('type' in data) {
- *     return { ...data, appVersion: '1.0.0' };
- *   }
- *   return data;
- * });
- * ```
- *
- * @see {@link https://github.com/tracelog/tracelog-lib/blob/main/API_REFERENCE.md#settransformer} for integration behavior
- */
-declare function setTransformer(hook: 'beforeSend', fn: BeforeSendTransformer): void;
-declare function setTransformer(hook: 'beforeBatch', fn: BeforeBatchTransformer): void;
-
 /**
  * Consolidated configuration constants for TraceLog
  * This file centralizes all timing, limits, browser, and initialization constants
@@ -2526,16 +1973,6 @@ declare const MAX_STRING_LENGTH = 1000;
 declare const MAX_STRING_LENGTH_IN_ARRAY = 500;
 declare const MAX_ARRAY_LENGTH = 1000;
 
-/**
- * Error handling and PII sanitization constants for TraceLog
- * Centralizes patterns and limits for error tracking and data protection
- */
-/**
- * Regular expressions for detecting and sanitizing Personally Identifiable Information (PII)
- * These patterns are used to replace sensitive information with [REDACTED] in error messages
- */
-declare const PII_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp, RegExp];
-
 /**
  * Performance monitoring and web vitals constants for TraceLog
  * Centralizes thresholds and configuration for performance tracking
@@ -2543,20 +1980,15 @@ declare const PII_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp, RegExp, Re
 
 /**
  * Web Vitals "good" thresholds (75th percentile boundaries)
- * Metrics below or equal to these values are considered good performance.
  * Reference: https://web.dev/articles/vitals
  */
 declare const WEB_VITALS_GOOD_THRESHOLDS: Record<WebVitalType, number>;
 /**
  * Web Vitals "needs improvement" thresholds
- * Metrics exceeding these values need attention but aren't critically poor.
- * Reference: https://web.dev/articles/vitals
  */
 declare const WEB_VITALS_NEEDS_IMPROVEMENT_THRESHOLDS: Record<WebVitalType, number>;
 /**
  * Web Vitals "poor" thresholds
- * Metrics exceeding these values indicate poor performance requiring immediate attention.
- * Reference: https://web.dev/articles/vitals
  */
 declare const WEB_VITALS_POOR_THRESHOLDS: Record<WebVitalType, number>;
 /**
@@ -2572,21 +2004,15 @@ declare const getWebVitalsThresholds: (mode?: WebVitalsMode) => Record<WebVitalT
 
 declare const tracelog: {
     init: (config?: Config) => Promise<InitResult>;
-    event: (name: string, metadata?: Record<string, MetadataType> | Record<string, MetadataType>[]) => void;
+    event: (name: string, metadata?: Record<string, MetadataType> | Record<string, MetadataType>[], options?: EventOptions) => void;
     on: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
     off: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
-    setTransformer: typeof setTransformer;
-    removeTransformer: (hook: TransformerHook) => void;
-    setCustomHeaders: (provider: CustomHeadersProvider) => void;
-    removeCustomHeaders: () => void;
     isInitialized: () => boolean;
     getSessionId: () => string | null;
+    getUserId: () => string | null;
     destroy: () => void;
-    setQaMode: (enabled: boolean) => void;
-    updateGlobalMetadata: (metadata: Record<string, MetadataType>) => void;
-    mergeGlobalMetadata: (metadata: Record<string, MetadataType>) => void;
     identify: (userId: string, traits?: Record<string, string>) => void;
     resetIdentity: () => Promise<void>;
 };
 
-export { AppConfigValidationError, type BeforeBatchTransformer, type BeforeSendTransformer, type ClickCoordinates, type ClickData, type ClickTrackingElementData, type Config, type CustomEventData, type CustomHeadersProvider, DEFAULT_SESSION_TIMEOUT, DEFAULT_WEB_VITALS_MODE, type DeviceInfo, DeviceType, type EmitterCallback, EmitterEvent, type EmitterMap, type ErrorData, ErrorType, type EventData, EventType, type EventTypeName, type EventsQueue, type IdentifyData, type InitResult, InitializationTimeoutError, IntegrationValidationError, MAX_ARRAY_LENGTH, MAX_CUSTOM_EVENT_ARRAY_SIZE, MAX_CUSTOM_EVENT_KEYS, MAX_CUSTOM_EVENT_NAME_LENGTH, MAX_CUSTOM_EVENT_STRING_SIZE, MAX_NESTED_OBJECT_KEYS, MAX_STRING_LENGTH, MAX_STRING_LENGTH_IN_ARRAY, type MetadataType, Mode, PII_PATTERNS, type PageViewData, PermanentError, type PersistedEventsQueue, type PrimaryScrollEvent, type QueueMetadata, RateLimitError, SamplingRateValidationError, type ScrollData, ScrollDirection, type SecondaryScrollEvent, type SessionEventCounts, SessionTimeoutValidationError, SpecialApiUrl, type State, TimeoutError, type TraceLogTestBridge, TraceLogValidationError, type TransformerHook, type TransformerMap, type UTM, type ViewportConfig, type ViewportElement, type ViewportEventData, WEB_VITALS_GOOD_THRESHOLDS, WEB_VITALS_NEEDS_IMPROVEMENT_THRESHOLDS, WEB_VITALS_POOR_THRESHOLDS, type WebVitalType, type WebVitalsData, type WebVitalsMode, getWebVitalsThresholds, isPrimaryScrollEvent, isSecondaryScrollEvent, tracelog };
+export { AppConfigValidationError, type ClickCoordinates, type ClickData, type ClickTrackingElementData, type Config, type CustomEventData, DEFAULT_SESSION_TIMEOUT, DEFAULT_WEB_VITALS_MODE, type DeviceInfo, DeviceType, type EmitterCallback, EmitterEvent, type EmitterMap, type ErrorData, ErrorType, type EventData, type EventOptions, EventType, type EventTypeName, type EventsQueue, type IdentifyData, type InitResult, InitializationTimeoutError, IntegrationValidationError, MAX_ARRAY_LENGTH, MAX_CUSTOM_EVENT_ARRAY_SIZE, MAX_CUSTOM_EVENT_KEYS, MAX_CUSTOM_EVENT_NAME_LENGTH, MAX_CUSTOM_EVENT_STRING_SIZE, MAX_NESTED_OBJECT_KEYS, MAX_STRING_LENGTH, MAX_STRING_LENGTH_IN_ARRAY, type MetadataType, Mode, PII_PATTERNS, type PageViewData, PermanentError, type PersistedEventsQueue, type QueueMetadata, type QueuedEvent, RateLimitError, SamplingRateValidationError, type ScrollData, ScrollDirection, type SessionEventCounts, SessionTimeoutValidationError, SpecialApiUrl, type State, TimeoutError, type TraceLogTestBridge, TraceLogValidationError, type UTM, WEB_VITALS_GOOD_THRESHOLDS, WEB_VITALS_NEEDS_IMPROVEMENT_THRESHOLDS, WEB_VITALS_POOR_THRESHOLDS, type WebVitalType, type WebVitalsData, type WebVitalsMode, getWebVitalsThresholds, tracelog };