@tracelog/lib 2.9.0-rc.107.4 → 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 */
@@ -465,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. */
@@ -1336,6 +1379,7 @@ declare class EventManager extends StateManager {
     private rateLimitCounter;
     private rateLimitWindowStart;
     private lastSessionId;
+    private pendingSyncFlush;
     private sessionEventCounts;
     private readonly saveSessionCountsDebounced;
     /**
@@ -1543,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).
@@ -1664,6 +1746,16 @@ declare class EventManager extends StateManager {
      */
     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
@@ -2453,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];
@@ -2641,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;
@@ -2656,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, 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 };
+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 */
@@ -465,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. */
@@ -1336,6 +1379,7 @@ declare class EventManager extends StateManager {
     private rateLimitCounter;
     private rateLimitWindowStart;
     private lastSessionId;
+    private pendingSyncFlush;
     private sessionEventCounts;
     private readonly saveSessionCountsDebounced;
     /**
@@ -1543,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).
@@ -1664,6 +1746,16 @@ declare class EventManager extends StateManager {
      */
     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
@@ -2453,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];
@@ -2641,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;
@@ -2656,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, 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 };
+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 };