@tracelog/lib 2.1.2 → 2.2.0-rc.80.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>;
         };
     };
 }
@@ -1238,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.
      *
@@ -1430,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.
      *
@@ -2236,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
@@ -2267,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;
@@ -2384,7 +2425,6 @@ declare const MAX_CUSTOM_EVENT_STRING_SIZE: number;
 declare const MAX_CUSTOM_EVENT_KEYS = 10;
 declare const MAX_CUSTOM_EVENT_ARRAY_SIZE = 10;
 declare const MAX_NESTED_OBJECT_KEYS = 20;
-declare const MAX_METADATA_NESTING_DEPTH = 1;
 declare const MAX_STRING_LENGTH = 1000;
 declare const MAX_STRING_LENGTH_IN_ARRAY = 500;
 declare const MAX_ARRAY_LENGTH = 100;
@@ -2440,6 +2480,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;
@@ -2447,4 +2489,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_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>;
         };
     };
 }
@@ -1238,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.
      *
@@ -1430,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.
      *
@@ -2236,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
@@ -2267,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;
@@ -2384,7 +2425,6 @@ declare const MAX_CUSTOM_EVENT_STRING_SIZE: number;
 declare const MAX_CUSTOM_EVENT_KEYS = 10;
 declare const MAX_CUSTOM_EVENT_ARRAY_SIZE = 10;
 declare const MAX_NESTED_OBJECT_KEYS = 20;
-declare const MAX_METADATA_NESTING_DEPTH = 1;
 declare const MAX_STRING_LENGTH = 1000;
 declare const MAX_STRING_LENGTH_IN_ARRAY = 500;
 declare const MAX_ARRAY_LENGTH = 100;
@@ -2440,6 +2480,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;
@@ -2447,4 +2489,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_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.js

@@ -39,12 +39,11 @@ var MAX_CUSTOM_EVENT_STRING_SIZE = 8 * 1024;
 var MAX_CUSTOM_EVENT_KEYS = 10;
 var MAX_CUSTOM_EVENT_ARRAY_SIZE = 10;
 var MAX_NESTED_OBJECT_KEYS = 20;
-var MAX_METADATA_NESTING_DEPTH = 1;
 var MAX_TEXT_LENGTH = 255;
 var MAX_STRING_LENGTH = 1e3;
 var MAX_STRING_LENGTH_IN_ARRAY = 500;
 var MAX_ARRAY_LENGTH = 100;
-var MAX_OBJECT_DEPTH = 3;
+var MAX_OBJECT_DEPTH = 10;
 var PRECISION_TWO_DECIMALS = 2;
 var MAX_BEACON_PAYLOAD_SIZE = 64 * 1024;
 var MAX_FINGERPRINTS = 1500;
@@ -556,7 +555,7 @@ var LONG_TASK_THROTTLE_MS = 1e3;
 var MAX_NAVIGATION_HISTORY = 50;
 
 // package.json
-var version = "2.1.1";
+var version = "2.2.0";
 
 // src/constants/version.constants.ts
 var LIB_VERSION = version;
@@ -852,9 +851,6 @@ var sanitizeString = (value) => {
   return result;
 };
 var sanitizeValue = (value, depth = 0) => {
-  if (depth > MAX_OBJECT_DEPTH) {
-    return null;
-  }
   if (value === null || value === void 0) {
     return null;
   }
@@ -870,6 +866,9 @@ var sanitizeValue = (value, depth = 0) => {
   if (typeof value === "boolean") {
     return value;
   }
+  if (depth > MAX_OBJECT_DEPTH) {
+    return null;
+  }
   if (Array.isArray(value)) {
     const limitedArray = value.slice(0, MAX_ARRAY_LENGTH);
     const sanitizedArray = limitedArray.map((item) => sanitizeValue(item, depth + 1)).filter((item) => item !== null);
@@ -1128,69 +1127,34 @@ var validateAndNormalizeConfig = (config) => {
 };
 
 // src/utils/validations/type-guards.utils.ts
-var isValidArrayItem = (item) => {
-  if (typeof item === "string") {
+var isSerializable = (value, seen = /* @__PURE__ */ new Set()) => {
+  if (value === null || value === void 0) {
     return true;
   }
-  if (typeof item === "object" && item !== null && !Array.isArray(item)) {
-    const entries = Object.entries(item);
-    if (entries.length > MAX_NESTED_OBJECT_KEYS) {
-      return false;
-    }
-    for (const [, value] of entries) {
-      if (value === null || value === void 0) {
-        continue;
-      }
-      const type = typeof value;
-      if (type !== "string" && type !== "number" && type !== "boolean") {
-        return false;
-      }
-    }
+  const type = typeof value;
+  if (type === "string" || type === "number" || type === "boolean") {
     return true;
   }
-  return false;
-};
-var isOnlyPrimitiveFields = (object, depth = 0) => {
-  if (typeof object !== "object" || object === null) {
+  if (type === "function" || type === "symbol" || type === "bigint") {
     return false;
   }
-  if (depth > MAX_METADATA_NESTING_DEPTH) {
+  if (seen.has(value)) {
     return false;
   }
-  for (const value of Object.values(object)) {
-    if (value === null || value === void 0) {
-      continue;
-    }
-    const type = typeof value;
-    if (type === "string" || type === "number" || type === "boolean") {
-      continue;
-    }
-    if (Array.isArray(value)) {
-      if (value.length === 0) {
-        continue;
-      }
-      const firstItem = value[0];
-      const isStringArray = typeof firstItem === "string";
-      if (isStringArray) {
-        if (!value.every((item) => typeof item === "string")) {
-          return false;
-        }
-      } else {
-        if (!value.every((item) => isValidArrayItem(item))) {
-          return false;
-        }
-      }
-      continue;
-    }
-    if (type === "object" && depth === 0) {
-      if (!isOnlyPrimitiveFields(value, depth + 1)) {
-        return false;
-      }
-      continue;
-    }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.every((item) => isSerializable(item, seen));
+  }
+  if (type === "object") {
+    return Object.values(value).every((v) => isSerializable(v, seen));
+  }
+  return false;
+};
+var isOnlyPrimitiveFields = (object) => {
+  if (typeof object !== "object" || object === null) {
     return false;
   }
-  return true;
+  return isSerializable(object);
 };
 
 // src/utils/validations/metadata-validations.utils.ts
@@ -1585,6 +1549,8 @@ var SenderManager = class extends StateManager {
   integrationId;
   apiUrl;
   transformers;
+  staticHeaders;
+  customHeadersProvider;
   lastPermanentErrorLog = null;
   recoveryInProgress = false;
   lastMetadataTimestamp = 0;
@@ -1599,9 +1565,11 @@ var SenderManager = class extends StateManager {
    * @param integrationId - Optional integration identifier ('saas' or 'custom')
    * @param apiUrl - Optional API endpoint URL
    * @param transformers - Optional event transformation hooks
+   * @param staticHeaders - Optional static HTTP headers (from config)
+   * @param customHeadersProvider - Optional callback for dynamic headers
    * @throws Error if integrationId and apiUrl are not both provided or both undefined
    */
-  constructor(storeManager, integrationId, apiUrl, transformers = {}) {
+  constructor(storeManager, integrationId, apiUrl, transformers = {}, staticHeaders = {}, customHeadersProvider) {
     super();
     if (integrationId && !apiUrl || !integrationId && apiUrl) {
       throw new Error("SenderManager: integrationId and apiUrl must either both be provided or both be undefined");
@@ -1610,6 +1578,8 @@ var SenderManager = class extends StateManager {
     this.integrationId = integrationId;
     this.apiUrl = apiUrl;
     this.transformers = transformers;
+    this.staticHeaders = staticHeaders;
+    this.customHeadersProvider = customHeadersProvider;
   }
   /**
    * Get the integration ID for this sender
@@ -1618,6 +1588,49 @@ var SenderManager = class extends StateManager {
   getIntegrationId() {
     return this.integrationId;
   }
+  /**
+   * Sets the custom headers provider callback.
+   * Only applies to 'custom' integration (ignored for 'saas').
+   *
+   * @param provider - Callback function that returns custom headers
+   */
+  setCustomHeadersProvider(provider) {
+    this.customHeadersProvider = provider;
+  }
+  /**
+   * Removes the custom headers provider callback.
+   */
+  removeCustomHeadersProvider() {
+    this.customHeadersProvider = void 0;
+  }
+  /**
+   * Builds custom headers by merging static headers with dynamic headers from provider.
+   * Only applies to 'custom' integration (returns empty object for 'saas').
+   *
+   * @returns Merged custom headers object (dynamic headers override static)
+   * @private
+   */
+  getCustomHeaders() {
+    if (this.integrationId !== "custom") {
+      return {};
+    }
+    let dynamicHeaders = {};
+    if (this.customHeadersProvider) {
+      try {
+        const result = this.customHeadersProvider();
+        if (typeof result === "object" && result !== null && !Array.isArray(result)) {
+          dynamicHeaders = result;
+        } else {
+          log("warn", "Custom headers provider returned invalid value, expected object", {
+            data: { received: typeof result }
+          });
+        }
+      } catch (error) {
+        log("warn", "Custom headers provider threw an error, using static headers only", { error });
+      }
+    }
+    return { ...this.staticHeaders, ...dynamicHeaders };
+  }
   getQueueStorageKey() {
     const userId = this.get("userId") || "anonymous";
     const baseKey = QUEUE_KEY(userId);
@@ -1645,6 +1658,11 @@ var SenderManager = class extends StateManager {
    *
    * **Important**: No retry mechanism for failures. Events are NOT persisted.
    *
+   * **Custom Headers Limitation**: Custom headers set via `setCustomHeaders()` are NOT applied
+   * to sendBeacon requests due to browser API limitations. The sendBeacon API only supports
+   * Content-Type header via Blob. For scenarios requiring custom headers, ensure async
+   * sends complete before page unload.
+   *
    * @param body - Event queue to send
    * @returns `true` if send succeeded or was skipped, `false` if failed
    *
@@ -2067,6 +2085,7 @@ var SenderManager = class extends StateManager {
       controller.abort();
     }, REQUEST_TIMEOUT_MS);
     try {
+      const customHeaders = this.getCustomHeaders();
       const response = await fetch(url, {
         method: "POST",
         body: payload,
@@ -2074,6 +2093,7 @@ var SenderManager = class extends StateManager {
         credentials: "include",
         signal: controller.signal,
         headers: {
+          ...customHeaders,
           "Content-Type": "application/json"
         }
       });
@@ -2536,8 +2556,10 @@ var EventManager = class 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, emitter = null, transformers = {}) {
+  constructor(storeManager, emitter = null, transformers = {}, staticHeaders = {}, customHeadersProvider) {
     super();
     this.emitter = emitter;
     this.transformers = transformers;
@@ -2548,7 +2570,16 @@ var EventManager = class extends StateManager {
       this.dataSenders.push(new SenderManager(storeManager, "saas", collectApiUrls.saas, transformers));
     }
     if (collectApiUrls?.custom) {
-      this.dataSenders.push(new SenderManager(storeManager, "custom", collectApiUrls.custom, transformers));
+      this.dataSenders.push(
+        new SenderManager(
+          storeManager,
+          "custom",
+          collectApiUrls.custom,
+          transformers,
+          staticHeaders,
+          customHeadersProvider
+        )
+      );
     }
     this.saveSessionCountsDebounced = this.debounce((sessionId) => {
       this.saveSessionCounts(sessionId);
@@ -2955,6 +2986,29 @@ var EventManager = class extends StateManager {
   flushImmediatelySync() {
     return this.flushEvents(true);
   }
+  /**
+   * 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) {
+    for (const sender of this.dataSenders) {
+      if (sender.getIntegrationId() === "custom") {
+        sender.setCustomHeadersProvider(provider);
+      }
+    }
+  }
+  /**
+   * Removes the custom headers provider callback from the custom integration.
+   */
+  removeCustomHeadersProvider() {
+    for (const sender of this.dataSenders) {
+      if (sender.getIntegrationId() === "custom") {
+        sender.removeCustomHeadersProvider();
+      }
+    }
+  }
   /**
    * Returns the current number of events in the main queue.
    *
@@ -6051,6 +6105,7 @@ var App = class extends StateManager {
   suppressNextScrollTimer = null;
   emitter = new Emitter();
   transformers = {};
+  customHeadersProvider;
   managers = {};
   handlers = {};
   get initialized() {
@@ -6070,7 +6125,14 @@ var App = class extends StateManager {
     this.managers.storage = new StorageManager();
     try {
       this.setupState(config);
-      this.managers.event = new EventManager(this.managers.storage, this.emitter, this.transformers);
+      const staticHeaders = config.integrations?.custom?.headers ?? {};
+      this.managers.event = new EventManager(
+        this.managers.storage,
+        this.emitter,
+        this.transformers,
+        staticHeaders,
+        this.customHeadersProvider
+      );
       this.initializeHandlers();
       await this.managers.event.recoverPersistedEvents().catch((error) => {
         log("warn", "Failed to recover persisted events", { error });
@@ -6133,6 +6195,34 @@ var App = class extends StateManager {
   getTransformer(hook) {
     return this.transformers[hook];
   }
+  /**
+   * Sets a callback to provide custom HTTP headers for requests to custom backends.
+   * Only applies to custom backend integration (not TraceLog SaaS).
+   *
+   * @param provider - Callback function that returns custom headers
+   * @throws {Error} If provider is not a function
+   * @internal Called from api.setCustomHeaders()
+   */
+  setCustomHeaders(provider) {
+    if (typeof provider !== "function") {
+      throw new Error(`[TraceLog] Custom headers provider must be a function, received: ${typeof provider}`);
+    }
+    this.customHeadersProvider = provider;
+    if (this.managers.event) {
+      this.managers.event.setCustomHeadersProvider(provider);
+    }
+  }
+  /**
+   * Removes the custom headers provider callback.
+   *
+   * @internal Called from api.removeCustomHeaders()
+   */
+  removeCustomHeaders() {
+    this.customHeadersProvider = void 0;
+    if (this.managers.event) {
+      this.managers.event.removeCustomHeadersProvider();
+    }
+  }
   /**
    * Destroys the TraceLog instance and cleans up all resources.
    *
@@ -6158,6 +6248,7 @@ var App = class extends StateManager {
     this.emitter.removeAllListeners();
     this.transformers.beforeSend = void 0;
     this.transformers.beforeBatch = void 0;
+    this.customHeadersProvider = void 0;
     this.set("suppressNextScroll", false);
     this.set("sessionId", null);
     this.isInitialized = false;
@@ -6312,6 +6403,7 @@ var App = class extends StateManager {
 // src/api.ts
 var pendingListeners = [];
 var pendingTransformers = [];
+var pendingCustomHeadersProvider = null;
 var app = null;
 var isInitializing = false;
 var isDestroying = false;
@@ -6346,6 +6438,10 @@ var init = async (config) => {
         }
       });
       pendingTransformers.length = 0;
+      if (pendingCustomHeadersProvider) {
+        instance.setCustomHeaders(pendingCustomHeadersProvider);
+        pendingCustomHeadersProvider = null;
+      }
       const initPromise = instance.init(validatedConfig);
       const timeoutPromise = new Promise((_, reject) => {
         setTimeout(() => {
@@ -6444,6 +6540,35 @@ var removeTransformer = (hook) => {
   }
   app.removeTransformer(hook);
 };
+var setCustomHeaders = (provider) => {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return;
+  }
+  if (typeof provider !== "function") {
+    throw new Error(`[TraceLog] Custom headers provider must be a function, received: ${typeof provider}`);
+  }
+  if (!app || isInitializing) {
+    pendingCustomHeadersProvider = provider;
+    return;
+  }
+  if (isDestroying) {
+    throw new Error("[TraceLog] Cannot set custom headers while TraceLog is being destroyed");
+  }
+  app.setCustomHeaders(provider);
+};
+var removeCustomHeaders = () => {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return;
+  }
+  if (!app) {
+    pendingCustomHeadersProvider = null;
+    return;
+  }
+  if (isDestroying) {
+    throw new Error("[TraceLog] Cannot remove custom headers while TraceLog is being destroyed");
+  }
+  app.removeCustomHeaders();
+};
 var isInitialized = () => {
   if (typeof window === "undefined" || typeof document === "undefined") {
     return false;
@@ -6468,6 +6593,7 @@ var destroy = () => {
     isInitializing = false;
     pendingListeners.length = 0;
     pendingTransformers.length = 0;
+    pendingCustomHeadersProvider = null;
     if (false) ;
     isDestroying = false;
   } catch (error) {
@@ -6475,6 +6601,7 @@ var destroy = () => {
     isInitializing = false;
     pendingListeners.length = 0;
     pendingTransformers.length = 0;
+    pendingCustomHeadersProvider = null;
     isDestroying = false;
     log("warn", "Error during destroy, forced cleanup completed", { error });
   }
@@ -6518,6 +6645,8 @@ var tracelog = {
   off,
   setTransformer,
   removeTransformer,
+  setCustomHeaders,
+  removeCustomHeaders,
   isInitialized,
   destroy,
   setQaMode: setQaMode2,
@@ -6525,6 +6654,6 @@ var tracelog = {
   mergeGlobalMetadata
 };
 
-export { AppConfigValidationError, DEFAULT_SESSION_TIMEOUT, DEFAULT_WEB_VITALS_MODE, DeviceType, EmitterEvent, ErrorType, EventType, 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, Mode, PII_PATTERNS, PermanentError, SamplingRateValidationError, ScrollDirection, SessionTimeoutValidationError, SpecialApiUrl, TraceLogValidationError, WEB_VITALS_GOOD_THRESHOLDS, WEB_VITALS_NEEDS_IMPROVEMENT_THRESHOLDS, WEB_VITALS_POOR_THRESHOLDS, getWebVitalsThresholds, isPrimaryScrollEvent, isSecondaryScrollEvent, tracelog };
+export { AppConfigValidationError, DEFAULT_SESSION_TIMEOUT, DEFAULT_WEB_VITALS_MODE, DeviceType, EmitterEvent, ErrorType, EventType, 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, Mode, PII_PATTERNS, PermanentError, SamplingRateValidationError, ScrollDirection, SessionTimeoutValidationError, SpecialApiUrl, TraceLogValidationError, WEB_VITALS_GOOD_THRESHOLDS, WEB_VITALS_NEEDS_IMPROVEMENT_THRESHOLDS, WEB_VITALS_POOR_THRESHOLDS, getWebVitalsThresholds, isPrimaryScrollEvent, isSecondaryScrollEvent, tracelog };
 //# sourceMappingURL=public-api.js.map
 //# sourceMappingURL=public-api.js.map