@tracelog/lib 2.1.1 → 2.1.2-rc.78.4

package/dist/public-api.d.mts

@@ -443,6 +443,12 @@ interface Config {
             collectApiUrl: string;
             /** Allow HTTP URLs (not recommended for production). @default false */
             allowHttp?: boolean;
+            /**
+             * Static HTTP headers to include in every request.
+             * For dynamic headers, use `setCustomHeaders()` instead.
+             * @example { 'X-Brand': 'my-brand', 'X-Tenant-Id': 'tenant-123' }
+             */
+            headers?: Record<string, string>;
         };
     };
 }
@@ -688,6 +694,8 @@ interface State {
     hasStartSession: boolean;
     suppressNextScroll: boolean;
     scrollEventCount?: number;
+    sessionReferrer?: string;
+    sessionUtm?: UTM;
 }
 
 /**
@@ -1236,8 +1244,10 @@ declare class EventManager extends StateManager {
      * @param storeManager - Storage manager for persistence
      * @param emitter - Optional event emitter for local event consumption
      * @param transformers - Optional event transformation hooks
+     * @param staticHeaders - Optional static HTTP headers for custom backend (from config)
+     * @param customHeadersProvider - Optional callback for dynamic headers
      */
-    constructor(storeManager: StorageManager, emitter?: Emitter | null, transformers?: TransformerMap);
+    constructor(storeManager: StorageManager, emitter?: Emitter | null, transformers?: TransformerMap, staticHeaders?: Record<string, string>, customHeadersProvider?: CustomHeadersProvider);
     /**
      * Recovers persisted events from localStorage after a crash or page reload.
      *
@@ -1428,6 +1438,17 @@ declare class EventManager extends StateManager {
      * @see src/managers/README.md (lines 5-75) for flush details
      */
     flushImmediatelySync(): boolean;
+    /**
+     * Sets the custom headers provider callback for the custom integration.
+     * Only affects requests to custom backend (not TraceLog SaaS).
+     *
+     * @param provider - Callback function that returns custom headers
+     */
+    setCustomHeadersProvider(provider: CustomHeadersProvider): void;
+    /**
+     * Removes the custom headers provider callback from the custom integration.
+     */
+    removeCustomHeadersProvider(): void;
     /**
      * Returns the current number of events in the main queue.
      *
@@ -1613,58 +1634,6 @@ declare class EventManager extends StateManager {
      * @internal
      */
     private cleanupExpiredSessionCounts;
-    /**
-     * Returns the referrer if it's external, or 'Direct' if internal/empty.
-     *
-     * **Purpose**: Filter out internal referrers (same domain) to ensure
-     * accurate traffic source attribution. Internal referrers occur when:
-     * - Session expires and user navigates within the same site
-     * - User opens new tab from an internal link
-     * - Page refresh after session timeout
-     *
-     * **Logic**:
-     * - Empty referrer → 'Direct'
-     * - Referrer from same domain or subdomain → 'Direct' (internal navigation)
-     * - External referrer → Returns original referrer
-     *
-     * **Subdomain Detection**:
-     * - `www.example.com` → `example.com` ✓ (internal)
-     * - `blog.example.com` → `example.com` ✓ (internal)
-     * - `example.com` → `www.example.com` ✓ (internal)
-     *
-     * @returns External referrer URL or 'Direct'
-     *
-     * @internal
-     */
-    private getExternalReferrer;
-    /**
-     * Checks if two hostnames belong to the same domain (including subdomains).
-     * Extracts root domain and compares to handle cross-subdomain navigation.
-     *
-     * @example
-     * isSameDomain('www.example.com', 'example.com') // true
-     * isSameDomain('app.example.com', 'www.example.com') // true
-     * isSameDomain('example.co.uk', 'app.example.co.uk') // true
-     *
-     * @param hostname1 - First hostname (e.g., 'www.example.com')
-     * @param hostname2 - Second hostname (e.g., 'app.example.com')
-     * @returns true if same root domain
-     *
-     * @internal
-     */
-    private isSameDomain;
-    /**
-     * Extracts the root (registrable) domain from a hostname.
-     * Handles both standard TLDs (.com, .org) and compound TLDs (.co.uk, .com.br).
-     *
-     * @example
-     * getRootDomain('www.example.com') // 'example.com'
-     * getRootDomain('app.blog.example.com') // 'example.com'
-     * getRootDomain('shop.example.co.uk') // 'example.co.uk'
-     *
-     * @internal
-     */
-    private getRootDomain;
     /**
      * Persists current session event counts to localStorage (debounced).
      *
@@ -2286,6 +2255,26 @@ interface TransformerMap {
     beforeSend?: BeforeSendTransformer;
     beforeBatch?: BeforeBatchTransformer;
 }
+/**
+ * Callback function for providing dynamic HTTP headers.
+ *
+ * Called synchronously before each fetch request to custom backends.
+ * Return empty object {} to send no custom headers.
+ *
+ * **Note**: Only applies to `custom` integration (not TraceLog SaaS).
+ * Headers are NOT applied to sendBeacon requests (page unload).
+ *
+ * @returns Record of header names to values
+ *
+ * @example
+ * ```typescript
+ * tracelog.setCustomHeaders(() => ({
+ *   'Authorization': `Bearer ${getAuthToken()}`,
+ *   'X-Request-ID': crypto.randomUUID()
+ * }));
+ * ```
+ */
+type CustomHeadersProvider = () => Record<string, string>;
 
 /**
  * Testing bridge interface for E2E and integration tests
@@ -2317,6 +2306,8 @@ interface TraceLogTestBridge {
     setTransformer(hook: 'beforeBatch', fn: BeforeBatchTransformer): void;
     setTransformer(hook: TransformerHook, fn: BeforeSendTransformer | BeforeBatchTransformer): void;
     removeTransformer(hook: TransformerHook): void;
+    setCustomHeaders(provider: CustomHeadersProvider): void;
+    removeCustomHeaders(): void;
     getEventManager(): EventManager | undefined;
     getStorageManager(): StorageManager | null;
     getPerformanceHandler(): PerformanceHandler | null;
@@ -2490,6 +2481,8 @@ declare const tracelog: {
     off: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
     setTransformer: typeof setTransformer;
     removeTransformer: (hook: TransformerHook) => void;
+    setCustomHeaders: (provider: CustomHeadersProvider) => void;
+    removeCustomHeaders: () => void;
     isInitialized: () => boolean;
     destroy: () => void;
     setQaMode: (enabled: boolean) => void;
@@ -2497,4 +2490,4 @@ declare const tracelog: {
     mergeGlobalMetadata: (metadata: Record<string, MetadataType>) => void;
 };
 
-export { AppConfigValidationError, type BeforeBatchTransformer, type BeforeSendTransformer, type ClickCoordinates, type ClickData, type ClickTrackingElementData, type Config, type CustomEventData, 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, 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_METADATA_NESTING_DEPTH, MAX_NESTED_OBJECT_KEYS, MAX_STRING_LENGTH, MAX_STRING_LENGTH_IN_ARRAY, type MetadataType, Mode, PII_PATTERNS, type PageViewData, PermanentError, type PersistedEventsQueue, type PrimaryScrollEvent, SamplingRateValidationError, type ScrollData, ScrollDirection, type SecondaryScrollEvent, type SessionEventCounts, SessionTimeoutValidationError, SpecialApiUrl, type State, 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, 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_METADATA_NESTING_DEPTH, MAX_NESTED_OBJECT_KEYS, MAX_STRING_LENGTH, MAX_STRING_LENGTH_IN_ARRAY, type MetadataType, Mode, PII_PATTERNS, type PageViewData, PermanentError, type PersistedEventsQueue, type PrimaryScrollEvent, SamplingRateValidationError, type ScrollData, ScrollDirection, type SecondaryScrollEvent, type SessionEventCounts, SessionTimeoutValidationError, SpecialApiUrl, type State, 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

@@ -443,6 +443,12 @@ interface Config {
             collectApiUrl: string;
             /** Allow HTTP URLs (not recommended for production). @default false */
             allowHttp?: boolean;
+            /**
+             * Static HTTP headers to include in every request.
+             * For dynamic headers, use `setCustomHeaders()` instead.
+             * @example { 'X-Brand': 'my-brand', 'X-Tenant-Id': 'tenant-123' }
+             */
+            headers?: Record<string, string>;
         };
     };
 }
@@ -688,6 +694,8 @@ interface State {
     hasStartSession: boolean;
     suppressNextScroll: boolean;
     scrollEventCount?: number;
+    sessionReferrer?: string;
+    sessionUtm?: UTM;
 }
 
 /**
@@ -1236,8 +1244,10 @@ declare class EventManager extends StateManager {
      * @param storeManager - Storage manager for persistence
      * @param emitter - Optional event emitter for local event consumption
      * @param transformers - Optional event transformation hooks
+     * @param staticHeaders - Optional static HTTP headers for custom backend (from config)
+     * @param customHeadersProvider - Optional callback for dynamic headers
      */
-    constructor(storeManager: StorageManager, emitter?: Emitter | null, transformers?: TransformerMap);
+    constructor(storeManager: StorageManager, emitter?: Emitter | null, transformers?: TransformerMap, staticHeaders?: Record<string, string>, customHeadersProvider?: CustomHeadersProvider);
     /**
      * Recovers persisted events from localStorage after a crash or page reload.
      *
@@ -1428,6 +1438,17 @@ declare class EventManager extends StateManager {
      * @see src/managers/README.md (lines 5-75) for flush details
      */
     flushImmediatelySync(): boolean;
+    /**
+     * Sets the custom headers provider callback for the custom integration.
+     * Only affects requests to custom backend (not TraceLog SaaS).
+     *
+     * @param provider - Callback function that returns custom headers
+     */
+    setCustomHeadersProvider(provider: CustomHeadersProvider): void;
+    /**
+     * Removes the custom headers provider callback from the custom integration.
+     */
+    removeCustomHeadersProvider(): void;
     /**
      * Returns the current number of events in the main queue.
      *
@@ -1613,58 +1634,6 @@ declare class EventManager extends StateManager {
      * @internal
      */
     private cleanupExpiredSessionCounts;
-    /**
-     * Returns the referrer if it's external, or 'Direct' if internal/empty.
-     *
-     * **Purpose**: Filter out internal referrers (same domain) to ensure
-     * accurate traffic source attribution. Internal referrers occur when:
-     * - Session expires and user navigates within the same site
-     * - User opens new tab from an internal link
-     * - Page refresh after session timeout
-     *
-     * **Logic**:
-     * - Empty referrer → 'Direct'
-     * - Referrer from same domain or subdomain → 'Direct' (internal navigation)
-     * - External referrer → Returns original referrer
-     *
-     * **Subdomain Detection**:
-     * - `www.example.com` → `example.com` ✓ (internal)
-     * - `blog.example.com` → `example.com` ✓ (internal)
-     * - `example.com` → `www.example.com` ✓ (internal)
-     *
-     * @returns External referrer URL or 'Direct'
-     *
-     * @internal
-     */
-    private getExternalReferrer;
-    /**
-     * Checks if two hostnames belong to the same domain (including subdomains).
-     * Extracts root domain and compares to handle cross-subdomain navigation.
-     *
-     * @example
-     * isSameDomain('www.example.com', 'example.com') // true
-     * isSameDomain('app.example.com', 'www.example.com') // true
-     * isSameDomain('example.co.uk', 'app.example.co.uk') // true
-     *
-     * @param hostname1 - First hostname (e.g., 'www.example.com')
-     * @param hostname2 - Second hostname (e.g., 'app.example.com')
-     * @returns true if same root domain
-     *
-     * @internal
-     */
-    private isSameDomain;
-    /**
-     * Extracts the root (registrable) domain from a hostname.
-     * Handles both standard TLDs (.com, .org) and compound TLDs (.co.uk, .com.br).
-     *
-     * @example
-     * getRootDomain('www.example.com') // 'example.com'
-     * getRootDomain('app.blog.example.com') // 'example.com'
-     * getRootDomain('shop.example.co.uk') // 'example.co.uk'
-     *
-     * @internal
-     */
-    private getRootDomain;
     /**
      * Persists current session event counts to localStorage (debounced).
      *
@@ -2286,6 +2255,26 @@ interface TransformerMap {
     beforeSend?: BeforeSendTransformer;
     beforeBatch?: BeforeBatchTransformer;
 }
+/**
+ * Callback function for providing dynamic HTTP headers.
+ *
+ * Called synchronously before each fetch request to custom backends.
+ * Return empty object {} to send no custom headers.
+ *
+ * **Note**: Only applies to `custom` integration (not TraceLog SaaS).
+ * Headers are NOT applied to sendBeacon requests (page unload).
+ *
+ * @returns Record of header names to values
+ *
+ * @example
+ * ```typescript
+ * tracelog.setCustomHeaders(() => ({
+ *   'Authorization': `Bearer ${getAuthToken()}`,
+ *   'X-Request-ID': crypto.randomUUID()
+ * }));
+ * ```
+ */
+type CustomHeadersProvider = () => Record<string, string>;
 
 /**
  * Testing bridge interface for E2E and integration tests
@@ -2317,6 +2306,8 @@ interface TraceLogTestBridge {
     setTransformer(hook: 'beforeBatch', fn: BeforeBatchTransformer): void;
     setTransformer(hook: TransformerHook, fn: BeforeSendTransformer | BeforeBatchTransformer): void;
     removeTransformer(hook: TransformerHook): void;
+    setCustomHeaders(provider: CustomHeadersProvider): void;
+    removeCustomHeaders(): void;
     getEventManager(): EventManager | undefined;
     getStorageManager(): StorageManager | null;
     getPerformanceHandler(): PerformanceHandler | null;
@@ -2490,6 +2481,8 @@ declare const tracelog: {
     off: <K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>) => void;
     setTransformer: typeof setTransformer;
     removeTransformer: (hook: TransformerHook) => void;
+    setCustomHeaders: (provider: CustomHeadersProvider) => void;
+    removeCustomHeaders: () => void;
     isInitialized: () => boolean;
     destroy: () => void;
     setQaMode: (enabled: boolean) => void;
@@ -2497,4 +2490,4 @@ declare const tracelog: {
     mergeGlobalMetadata: (metadata: Record<string, MetadataType>) => void;
 };
 
-export { AppConfigValidationError, type BeforeBatchTransformer, type BeforeSendTransformer, type ClickCoordinates, type ClickData, type ClickTrackingElementData, type Config, type CustomEventData, 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, 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_METADATA_NESTING_DEPTH, MAX_NESTED_OBJECT_KEYS, MAX_STRING_LENGTH, MAX_STRING_LENGTH_IN_ARRAY, type MetadataType, Mode, PII_PATTERNS, type PageViewData, PermanentError, type PersistedEventsQueue, type PrimaryScrollEvent, SamplingRateValidationError, type ScrollData, ScrollDirection, type SecondaryScrollEvent, type SessionEventCounts, SessionTimeoutValidationError, SpecialApiUrl, type State, 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, 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_METADATA_NESTING_DEPTH, MAX_NESTED_OBJECT_KEYS, MAX_STRING_LENGTH, MAX_STRING_LENGTH_IN_ARRAY, type MetadataType, Mode, PII_PATTERNS, type PageViewData, PermanentError, type PersistedEventsQueue, type PrimaryScrollEvent, SamplingRateValidationError, type ScrollData, ScrollDirection, type SecondaryScrollEvent, type SessionEventCounts, SessionTimeoutValidationError, SpecialApiUrl, type State, 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 };