@tracelog/lib 2.3.1 → 2.4.0

package/dist/public-api.d.mts

@@ -66,7 +66,7 @@ type MetadataType = MetadataPrimitive | string[] | MetadataNestedObject | Metada
  * Result returned by tracelog.init()
  *
  * Contains the session identifier generated during initialization.
- * The sessionId is empty string in edge cases (SSR, disabled, race condition).
+ * The sessionId is empty string in edge cases (SSR, disabled).
  *
  * @example
  * ```typescript
@@ -445,6 +445,8 @@ interface Config {
      * Only applies when webVitalsMode is set. Overrides default thresholds for the selected mode.
      */
     webVitalsThresholds?: Partial<Record<WebVitalType, number>>;
+    /** Interval in milliseconds between event batch sends. @default 10000 (10 seconds) */
+    sendIntervalMs?: number;
     /** Optional configuration for third-party integrations. */
     integrations?: {
         /** TraceLog integration options. */
@@ -1180,7 +1182,7 @@ declare class StorageManager {
  *
  * **Core Functionality**:
  * - **Event Tracking**: Captures all user interactions (clicks, scrolls, page views, custom events, web vitals, errors)
- * - **Queue Management**: Batches events with 10-second intervals to optimize network requests
+ * - **Queue Management**: Batches events with 10-second base intervals (exponential backoff on failure) to optimize network requests
  * - **Deduplication**: LRU cache with 1000-entry fingerprint storage prevents duplicate events
  * - **Rate Limiting**: Client-side limits (50 events/second global, 60/minute per event name)
  * - **Per-Session Caps**: Configurable limits prevent runaway generation (1000 total, type-specific limits)
@@ -1243,8 +1245,9 @@ declare class EventManager extends StateManager {
     private readonly perEventRateLimits;
     private eventsQueue;
     private pendingEventsBuffer;
-    private sendIntervalId;
+    private sendTimeoutId;
     private sendInProgress;
+    private consecutiveSendFailures;
     private rateLimitCounter;
     private rateLimitWindowStart;
     private lastSessionId;
@@ -1356,7 +1359,7 @@ declare class EventManager extends StateManager {
      * and allow subsequent init() → destroy() → init() cycles.
      *
      * **Cleanup Actions**:
-     * 1. **Clear send interval**: Stops periodic 10-second queue flush timer
+     * 1. **Clear send timeout**: Cancels pending queue flush timeout and resets backoff state
      * 2. **Clear all queues and buffers**:
      *    - `eventsQueue`: Discarded (not sent)
      *    - `pendingEventsBuffer`: Discarded (events before session init)
@@ -1366,8 +1369,8 @@ declare class EventManager extends StateManager {
      * 6. **Stop SenderManagers**: Calls `stop()` on all SenderManager instances
      *
      * **Important Behavior**:
-     * - **No final flush**: Events in queue are NOT sent before stopping
-     * - For flush before destroy, call `flushImmediatelySync()` first
+     * - **No final flush**: `stop()` itself does NOT send queued events
+     * - `App.destroy()` calls `flushImmediatelySync()` before `stop()` automatically
      *
      * **Multi-Integration**:
      * - Stops all SenderManager instances (SaaS + Custom)
@@ -1388,7 +1391,7 @@ declare class EventManager extends StateManager {
      * Flushes all events in the queue asynchronously.
      *
      * **Purpose**: Force immediate sending of queued events without waiting for
-     * the 10-second periodic flush timer.
+     * the scheduled queue flush timeout.
      *
      * **Use Cases**:
      * - Manual flush triggered by user action
@@ -1553,7 +1556,7 @@ declare class EventManager extends StateManager {
      * @see src/managers/README.md (lines 5-75) for pending buffer details
      */
     flushPendingEvents(): void;
-    private clearSendInterval;
+    private clearSendTimeout;
     private isSuccessfulResult;
     private flushEvents;
     private sendEventsQueue;
@@ -1564,7 +1567,8 @@ declare class EventManager extends StateManager {
     private createEventFingerprint;
     private createEventSignature;
     private addToQueue;
-    private startSendInterval;
+    private scheduleSendTimeout;
+    private calculateSendDelay;
     private shouldSample;
     private checkRateLimit;
     private checkPerEventRateLimit;

package/dist/public-api.d.ts

@@ -66,7 +66,7 @@ type MetadataType = MetadataPrimitive | string[] | MetadataNestedObject | Metada
  * Result returned by tracelog.init()
  *
  * Contains the session identifier generated during initialization.
- * The sessionId is empty string in edge cases (SSR, disabled, race condition).
+ * The sessionId is empty string in edge cases (SSR, disabled).
  *
  * @example
  * ```typescript
@@ -445,6 +445,8 @@ interface Config {
      * Only applies when webVitalsMode is set. Overrides default thresholds for the selected mode.
      */
     webVitalsThresholds?: Partial<Record<WebVitalType, number>>;
+    /** Interval in milliseconds between event batch sends. @default 10000 (10 seconds) */
+    sendIntervalMs?: number;
     /** Optional configuration for third-party integrations. */
     integrations?: {
         /** TraceLog integration options. */
@@ -1180,7 +1182,7 @@ declare class StorageManager {
  *
  * **Core Functionality**:
  * - **Event Tracking**: Captures all user interactions (clicks, scrolls, page views, custom events, web vitals, errors)
- * - **Queue Management**: Batches events with 10-second intervals to optimize network requests
+ * - **Queue Management**: Batches events with 10-second base intervals (exponential backoff on failure) to optimize network requests
  * - **Deduplication**: LRU cache with 1000-entry fingerprint storage prevents duplicate events
  * - **Rate Limiting**: Client-side limits (50 events/second global, 60/minute per event name)
  * - **Per-Session Caps**: Configurable limits prevent runaway generation (1000 total, type-specific limits)
@@ -1243,8 +1245,9 @@ declare class EventManager extends StateManager {
     private readonly perEventRateLimits;
     private eventsQueue;
     private pendingEventsBuffer;
-    private sendIntervalId;
+    private sendTimeoutId;
     private sendInProgress;
+    private consecutiveSendFailures;
     private rateLimitCounter;
     private rateLimitWindowStart;
     private lastSessionId;
@@ -1356,7 +1359,7 @@ declare class EventManager extends StateManager {
      * and allow subsequent init() → destroy() → init() cycles.
      *
      * **Cleanup Actions**:
-     * 1. **Clear send interval**: Stops periodic 10-second queue flush timer
+     * 1. **Clear send timeout**: Cancels pending queue flush timeout and resets backoff state
      * 2. **Clear all queues and buffers**:
      *    - `eventsQueue`: Discarded (not sent)
      *    - `pendingEventsBuffer`: Discarded (events before session init)
@@ -1366,8 +1369,8 @@ declare class EventManager extends StateManager {
      * 6. **Stop SenderManagers**: Calls `stop()` on all SenderManager instances
      *
      * **Important Behavior**:
-     * - **No final flush**: Events in queue are NOT sent before stopping
-     * - For flush before destroy, call `flushImmediatelySync()` first
+     * - **No final flush**: `stop()` itself does NOT send queued events
+     * - `App.destroy()` calls `flushImmediatelySync()` before `stop()` automatically
      *
      * **Multi-Integration**:
      * - Stops all SenderManager instances (SaaS + Custom)
@@ -1388,7 +1391,7 @@ declare class EventManager extends StateManager {
      * Flushes all events in the queue asynchronously.
      *
      * **Purpose**: Force immediate sending of queued events without waiting for
-     * the 10-second periodic flush timer.
+     * the scheduled queue flush timeout.
      *
      * **Use Cases**:
      * - Manual flush triggered by user action
@@ -1553,7 +1556,7 @@ declare class EventManager extends StateManager {
      * @see src/managers/README.md (lines 5-75) for pending buffer details
      */
     flushPendingEvents(): void;
-    private clearSendInterval;
+    private clearSendTimeout;
     private isSuccessfulResult;
     private flushEvents;
     private sendEventsQueue;
@@ -1564,7 +1567,8 @@ declare class EventManager extends StateManager {
     private createEventFingerprint;
     private createEventSignature;
     private addToQueue;
-    private startSendInterval;
+    private scheduleSendTimeout;
+    private calculateSendDelay;
     private shouldSample;
     private checkRateLimit;
     private checkPerEventRateLimit;