@tracelog/lib 2.3.1 → 2.4.0-rc.85.2

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. */
@@ -464,6 +466,14 @@ interface Config {
              * @example { 'X-Brand': 'my-brand', 'X-Tenant-Id': 'tenant-123' }
              */
             headers?: Record<string, string>;
+            /**
+             * Controls whether cookies and credentials are sent with fetch requests.
+             * - `'include'`: Always send cookies (even cross-origin) — required for cookie-based auth
+             * - `'same-origin'`: Only send cookies for same-origin requests
+             * - `'omit'`: Never send cookies
+             * @default 'include'
+             */
+            fetchCredentials?: RequestCredentials;
         };
     };
 }
@@ -1180,7 +1190,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 +1253,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;
@@ -1262,8 +1273,9 @@ declare class EventManager extends StateManager {
      * @param transformers - Optional event transformation hooks
      * @param staticHeaders - Optional static HTTP headers for custom backend (from config)
      * @param customHeadersProvider - Optional callback for dynamic headers
+     * @param fetchCredentials - Fetch credentials mode for custom backend. @default 'include'
      */
-    constructor(storeManager: StorageManager, emitter?: Emitter | null, transformers?: TransformerMap, staticHeaders?: Record<string, string>, customHeadersProvider?: CustomHeadersProvider);
+    constructor(storeManager: StorageManager, emitter?: Emitter | null, transformers?: TransformerMap, staticHeaders?: Record<string, string>, customHeadersProvider?: CustomHeadersProvider, fetchCredentials?: RequestCredentials);
     /**
      * Recovers persisted events from localStorage after a crash or page reload.
      *
@@ -1356,7 +1368,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 +1378,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 +1400,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 +1565,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 +1576,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. */
@@ -464,6 +466,14 @@ interface Config {
              * @example { 'X-Brand': 'my-brand', 'X-Tenant-Id': 'tenant-123' }
              */
             headers?: Record<string, string>;
+            /**
+             * Controls whether cookies and credentials are sent with fetch requests.
+             * - `'include'`: Always send cookies (even cross-origin) — required for cookie-based auth
+             * - `'same-origin'`: Only send cookies for same-origin requests
+             * - `'omit'`: Never send cookies
+             * @default 'include'
+             */
+            fetchCredentials?: RequestCredentials;
         };
     };
 }
@@ -1180,7 +1190,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 +1253,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;
@@ -1262,8 +1273,9 @@ declare class EventManager extends StateManager {
      * @param transformers - Optional event transformation hooks
      * @param staticHeaders - Optional static HTTP headers for custom backend (from config)
      * @param customHeadersProvider - Optional callback for dynamic headers
+     * @param fetchCredentials - Fetch credentials mode for custom backend. @default 'include'
      */
-    constructor(storeManager: StorageManager, emitter?: Emitter | null, transformers?: TransformerMap, staticHeaders?: Record<string, string>, customHeadersProvider?: CustomHeadersProvider);
+    constructor(storeManager: StorageManager, emitter?: Emitter | null, transformers?: TransformerMap, staticHeaders?: Record<string, string>, customHeadersProvider?: CustomHeadersProvider, fetchCredentials?: RequestCredentials);
     /**
      * Recovers persisted events from localStorage after a crash or page reload.
      *
@@ -1356,7 +1368,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 +1378,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 +1400,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 +1565,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 +1576,8 @@ declare class EventManager extends StateManager {
     private createEventFingerprint;
     private createEventSignature;
     private addToQueue;
-    private startSendInterval;
+    private scheduleSendTimeout;
+    private calculateSendDelay;
     private shouldSample;
     private checkRateLimit;
     private checkPerEventRateLimit;