@tracelog/lib 2.8.5 → 2.9.0-rc.108.13

package/dist/public-api.d.mts

@@ -301,6 +301,33 @@ 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
+     * (e.g., `window.location.href = '/thanks'` right after tracking a
+     * purchase). Async fetch would be cancelled by the navigation;
+     * sendBeacon survives.
+     *
+     * Use for high-value events where loss is unacceptable (Purchase, Signup,
+     * AddPaymentInfo). The critical event plus any previously queued events
+     * are sent in a single request — this does not bypass the queue.
+     *
+     * **Limitations** (inherited from `sendBeacon`):
+     * - 64KB payload cap. If the combined queue + critical event exceeds it,
+     *   the failed batch is persisted to localStorage and recovered on next
+     *   `init()` via its idempotency token.
+     * - No retry on failure (fire-and-forget).
+     * - Custom headers are not applied (browser API limitation).
+     *
+     * @default false
+     */
+    critical?: boolean;
+}
 /**
  * Web performance metrics data
  */
@@ -318,6 +345,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 */
@@ -406,6 +435,22 @@ interface EventData {
     /** 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.
+ *
+ * **Internal only.** The leading underscore mirrors `EventsQueue._metadata` —
+ * this field is stripped from `events[]` at batch construction time, since the
+ * backend's `EventDto` uses `forbidNonWhitelisted: true` and the wrapper
+ * `EventsQueue.session_id` is the contract.
+ */
+interface QueuedEvent extends EventData {
+    _session_id: string;
+}
 
 /**
  * Web Vitals filtering mode
@@ -449,6 +494,20 @@ interface Config {
     webVitalsThresholds?: Partial<Record<WebVitalType, number>>;
     /** Interval in milliseconds between event batch sends. @default 10000 (10 seconds) */
     sendIntervalMs?: number;
+    /**
+     * If true, the event queue is flushed automatically after every SPA navigation
+     * (`pushState`, `replaceState`, `popstate`, `hashchange`). Prevents batch loss when the
+     * user closes the tab mid-buffer between SPA route changes. No-op for MPAs (no SPA nav).
+     * @default true
+     */
+    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;
     /** Optional configuration for third-party integrations. */
     integrations?: {
         /** TraceLog integration options. */
@@ -1320,6 +1379,7 @@ declare class EventManager extends StateManager {
     private rateLimitCounter;
     private rateLimitWindowStart;
     private lastSessionId;
+    private pendingSyncFlush;
     private sessionEventCounts;
     private readonly saveSessionCountsDebounced;
     /**
@@ -1527,6 +1587,44 @@ declare class EventManager extends StateManager {
      * @see src/managers/README.md (lines 5-75) for flush details
      */
     flushImmediatelySync(): boolean;
+    /**
+     * Sends ONLY the most recently queued event via `navigator.sendBeacon()` in
+     * a dedicated single-event batch.
+     *
+     * **Purpose**: Guarantee delivery of an event that *must* survive an
+     * imminent page unload (purchase confirmation, signup completion, etc.),
+     * independent of the main queue's size or in-flight async send state.
+     *
+     * **Why a dedicated batch**: `flushImmediatelySync()` serialises the entire
+     * queue into one `sendBeacon` call. If the queue is heavy (>64KB) the
+     * beacon fails and the batch is persisted to `localStorage`, which is only
+     * recovered on the next `init()` — useless for one-shot conversion events
+     * where the user never returns.
+     *
+     * **Behaviour**:
+     * - Reads the last entry of `eventsQueue` (the just-tracked event).
+     * - Wraps it in its own `EventsQueue` and dispatches synchronously through
+     *   every `SenderManager` via `sendEventsQueueSync()`.
+     * - Leaves the main queue untouched; the same event will be re-delivered by
+     *   the next periodic / unload flush. Idempotency is the caller-side
+     *   contract: the backend MUST deduplicate by `event.id` (e.g. unique index
+     *   on the ingestion collection) — same guarantee the library already
+     *   relies on for the persisted-events recovery path.
+     *
+     * **Use it after** `track()` so the event is in the queue. Caller is
+     * responsible for verifying that `track()` actually queued the event
+     * (it can be dropped by rate limiting / sampling / `beforeSend`).
+     *
+     * **Standalone mode** (no senders configured): returns `false` without
+     * emitting. The subsequent main-queue drain (`flushImmediatelySync()`) is
+     * responsible for delivering the event to local listeners — emitting here
+     * too would surface the same event twice to a `tracelog.on('queue', ...)`
+     * subscriber.
+     *
+     * @returns `true` if at least one sender delivered the beacon successfully,
+     * `false` otherwise (including standalone mode — the drain handles it).
+     */
+    flushLastEventSync(): boolean;
     /**
      * Sets the custom headers provider callback for the custom integration.
      * Only affects requests to custom backend (not TraceLog SaaS).
@@ -1628,9 +1726,67 @@ 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;
+    /**
+     * 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;
@@ -2333,6 +2489,11 @@ 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.
  *
+ * **Multi-batch flushes**: when the queue spans more than one session (e.g.
+ * after an idle-timeout renewal), one flush produces one batch per session,
+ * and this transformer is invoked **once per session-batch**. Avoid stateful
+ * transformers that assume a single invocation per flush.
+ *
  * @param batch - The batch to transform
  * @returns Transformed batch or null to filter
  */
@@ -2384,8 +2545,8 @@ 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];
@@ -2572,7 +2733,7 @@ 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;
@@ -2587,6 +2748,8 @@ declare const tracelog: {
     mergeGlobalMetadata: (metadata: Record<string, MetadataType>) => void;
     identify: (userId: string, traits?: Record<string, string>) => void;
     resetIdentity: () => Promise<void>;
+    flushImmediately: () => Promise<boolean>;
+    flushImmediatelySync: () => boolean;
 };
 
-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 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, 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 PrimaryScrollEvent, type QueueMetadata, type QueuedEvent, 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 };

package/dist/public-api.d.ts

@@ -301,6 +301,33 @@ 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
+     * (e.g., `window.location.href = '/thanks'` right after tracking a
+     * purchase). Async fetch would be cancelled by the navigation;
+     * sendBeacon survives.
+     *
+     * Use for high-value events where loss is unacceptable (Purchase, Signup,
+     * AddPaymentInfo). The critical event plus any previously queued events
+     * are sent in a single request — this does not bypass the queue.
+     *
+     * **Limitations** (inherited from `sendBeacon`):
+     * - 64KB payload cap. If the combined queue + critical event exceeds it,
+     *   the failed batch is persisted to localStorage and recovered on next
+     *   `init()` via its idempotency token.
+     * - No retry on failure (fire-and-forget).
+     * - Custom headers are not applied (browser API limitation).
+     *
+     * @default false
+     */
+    critical?: boolean;
+}
 /**
  * Web performance metrics data
  */
@@ -318,6 +345,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 */
@@ -406,6 +435,22 @@ interface EventData {
     /** 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.
+ *
+ * **Internal only.** The leading underscore mirrors `EventsQueue._metadata` —
+ * this field is stripped from `events[]` at batch construction time, since the
+ * backend's `EventDto` uses `forbidNonWhitelisted: true` and the wrapper
+ * `EventsQueue.session_id` is the contract.
+ */
+interface QueuedEvent extends EventData {
+    _session_id: string;
+}
 
 /**
  * Web Vitals filtering mode
@@ -449,6 +494,20 @@ interface Config {
     webVitalsThresholds?: Partial<Record<WebVitalType, number>>;
     /** Interval in milliseconds between event batch sends. @default 10000 (10 seconds) */
     sendIntervalMs?: number;
+    /**
+     * If true, the event queue is flushed automatically after every SPA navigation
+     * (`pushState`, `replaceState`, `popstate`, `hashchange`). Prevents batch loss when the
+     * user closes the tab mid-buffer between SPA route changes. No-op for MPAs (no SPA nav).
+     * @default true
+     */
+    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;
     /** Optional configuration for third-party integrations. */
     integrations?: {
         /** TraceLog integration options. */
@@ -1320,6 +1379,7 @@ declare class EventManager extends StateManager {
     private rateLimitCounter;
     private rateLimitWindowStart;
     private lastSessionId;
+    private pendingSyncFlush;
     private sessionEventCounts;
     private readonly saveSessionCountsDebounced;
     /**
@@ -1527,6 +1587,44 @@ declare class EventManager extends StateManager {
      * @see src/managers/README.md (lines 5-75) for flush details
      */
     flushImmediatelySync(): boolean;
+    /**
+     * Sends ONLY the most recently queued event via `navigator.sendBeacon()` in
+     * a dedicated single-event batch.
+     *
+     * **Purpose**: Guarantee delivery of an event that *must* survive an
+     * imminent page unload (purchase confirmation, signup completion, etc.),
+     * independent of the main queue's size or in-flight async send state.
+     *
+     * **Why a dedicated batch**: `flushImmediatelySync()` serialises the entire
+     * queue into one `sendBeacon` call. If the queue is heavy (>64KB) the
+     * beacon fails and the batch is persisted to `localStorage`, which is only
+     * recovered on the next `init()` — useless for one-shot conversion events
+     * where the user never returns.
+     *
+     * **Behaviour**:
+     * - Reads the last entry of `eventsQueue` (the just-tracked event).
+     * - Wraps it in its own `EventsQueue` and dispatches synchronously through
+     *   every `SenderManager` via `sendEventsQueueSync()`.
+     * - Leaves the main queue untouched; the same event will be re-delivered by
+     *   the next periodic / unload flush. Idempotency is the caller-side
+     *   contract: the backend MUST deduplicate by `event.id` (e.g. unique index
+     *   on the ingestion collection) — same guarantee the library already
+     *   relies on for the persisted-events recovery path.
+     *
+     * **Use it after** `track()` so the event is in the queue. Caller is
+     * responsible for verifying that `track()` actually queued the event
+     * (it can be dropped by rate limiting / sampling / `beforeSend`).
+     *
+     * **Standalone mode** (no senders configured): returns `false` without
+     * emitting. The subsequent main-queue drain (`flushImmediatelySync()`) is
+     * responsible for delivering the event to local listeners — emitting here
+     * too would surface the same event twice to a `tracelog.on('queue', ...)`
+     * subscriber.
+     *
+     * @returns `true` if at least one sender delivered the beacon successfully,
+     * `false` otherwise (including standalone mode — the drain handles it).
+     */
+    flushLastEventSync(): boolean;
     /**
      * Sets the custom headers provider callback for the custom integration.
      * Only affects requests to custom backend (not TraceLog SaaS).
@@ -1628,9 +1726,67 @@ 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;
+    /**
+     * 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;
@@ -2333,6 +2489,11 @@ 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.
  *
+ * **Multi-batch flushes**: when the queue spans more than one session (e.g.
+ * after an idle-timeout renewal), one flush produces one batch per session,
+ * and this transformer is invoked **once per session-batch**. Avoid stateful
+ * transformers that assume a single invocation per flush.
+ *
  * @param batch - The batch to transform
  * @returns Transformed batch or null to filter
  */
@@ -2384,8 +2545,8 @@ 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];
@@ -2572,7 +2733,7 @@ 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;
@@ -2587,6 +2748,8 @@ declare const tracelog: {
     mergeGlobalMetadata: (metadata: Record<string, MetadataType>) => void;
     identify: (userId: string, traits?: Record<string, string>) => void;
     resetIdentity: () => Promise<void>;
+    flushImmediately: () => Promise<boolean>;
+    flushImmediatelySync: () => boolean;
 };
 
-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 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, 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 PrimaryScrollEvent, type QueueMetadata, type QueuedEvent, 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 };