@tracelog/lib 2.8.5 → 2.9.0-rc.108.6

package/dist/public-api.d.mts

@@ -406,6 +406,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
@@ -1628,9 +1644,57 @@ 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;
+    /**
+     * 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 +2397,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
  */
@@ -2589,4 +2658,4 @@ declare const tracelog: {
     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 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 };

package/dist/public-api.d.ts

@@ -406,6 +406,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
@@ -1628,9 +1644,57 @@ 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;
+    /**
+     * 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 +2397,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
  */
@@ -2589,4 +2658,4 @@ declare const tracelog: {
     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 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 };