@tracelog/lib 2.9.0 → 2.10.0

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,24 @@ interface Config {
     webVitalsThresholds?: Partial<Record<WebVitalType, number>>;
     /** Interval in milliseconds between event batch sends. @default 10000 (10 seconds) */
     sendIntervalMs?: number;
+    /**
+     * 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
+     * (one request per route change vs. one per `sendIntervalMs`). Enable only
+     * if you need delivery between route changes that's faster than
+     * `sendIntervalMs`; `flushOnPageHidden` (default `true`) already covers the
+     * common tab-close / app-background case on every stack. No-op for MPAs.
+     * @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;
     /** Optional configuration for third-party integrations. */
     integrations?: {
         /** TraceLog integration options. */
@@ -1320,6 +1383,7 @@ declare class EventManager extends StateManager {
     private rateLimitCounter;
     private rateLimitWindowStart;
     private lastSessionId;
+    private pendingSyncFlush;
     private sessionEventCounts;
     private readonly saveSessionCountsDebounced;
     /**
@@ -1477,7 +1541,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 +1580,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
@@ -1628,9 +1702,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;
@@ -2333,6 +2477,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 +2533,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 +2721,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;
@@ -2581,12 +2730,15 @@ declare const tracelog: {
     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>;
+    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,24 @@ interface Config {
     webVitalsThresholds?: Partial<Record<WebVitalType, number>>;
     /** Interval in milliseconds between event batch sends. @default 10000 (10 seconds) */
     sendIntervalMs?: number;
+    /**
+     * 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
+     * (one request per route change vs. one per `sendIntervalMs`). Enable only
+     * if you need delivery between route changes that's faster than
+     * `sendIntervalMs`; `flushOnPageHidden` (default `true`) already covers the
+     * common tab-close / app-background case on every stack. No-op for MPAs.
+     * @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;
     /** Optional configuration for third-party integrations. */
     integrations?: {
         /** TraceLog integration options. */
@@ -1320,6 +1383,7 @@ declare class EventManager extends StateManager {
     private rateLimitCounter;
     private rateLimitWindowStart;
     private lastSessionId;
+    private pendingSyncFlush;
     private sessionEventCounts;
     private readonly saveSessionCountsDebounced;
     /**
@@ -1477,7 +1541,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 +1580,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
@@ -1628,9 +1702,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;
@@ -2333,6 +2477,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 +2533,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 +2721,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;
@@ -2581,12 +2730,15 @@ declare const tracelog: {
     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>;
+    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 };