@tracelog/lib 2.1.2 → 2.2.0

package/dist/public-api.cjs

@@ -558,7 +558,7 @@ var LONG_TASK_THROTTLE_MS = 1e3;
 var MAX_NAVIGATION_HISTORY = 50;
 
 // package.json
-var version = "2.1.1";
+var version = "2.1.2";
 
 // src/constants/version.constants.ts
 var LIB_VERSION = version;
@@ -1587,6 +1587,8 @@ var SenderManager = class extends StateManager {
   integrationId;
   apiUrl;
   transformers;
+  staticHeaders;
+  customHeadersProvider;
   lastPermanentErrorLog = null;
   recoveryInProgress = false;
   lastMetadataTimestamp = 0;
@@ -1601,9 +1603,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");
@@ -1612,6 +1616,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
@@ -1620,6 +1626,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);
@@ -1647,6 +1696,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
    *
@@ -2069,6 +2123,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,
@@ -2076,6 +2131,7 @@ var SenderManager = class extends StateManager {
         credentials: "include",
         signal: controller.signal,
         headers: {
+          ...customHeaders,
           "Content-Type": "application/json"
         }
       });
@@ -2538,8 +2594,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;
@@ -2550,7 +2608,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);
@@ -2957,6 +3024,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.
    *
@@ -6053,6 +6143,7 @@ var App = class extends StateManager {
   suppressNextScrollTimer = null;
   emitter = new Emitter();
   transformers = {};
+  customHeadersProvider;
   managers = {};
   handlers = {};
   get initialized() {
@@ -6072,7 +6163,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 });
@@ -6135,6 +6233,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.
    *
@@ -6160,6 +6286,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;
@@ -6314,6 +6441,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;
@@ -6348,6 +6476,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(() => {
@@ -6446,6 +6578,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;
@@ -6470,6 +6631,7 @@ var destroy = () => {
     isInitializing = false;
     pendingListeners.length = 0;
     pendingTransformers.length = 0;
+    pendingCustomHeadersProvider = null;
     if (false) ;
     isDestroying = false;
   } catch (error) {
@@ -6477,6 +6639,7 @@ var destroy = () => {
     isInitializing = false;
     pendingListeners.length = 0;
     pendingTransformers.length = 0;
+    pendingCustomHeadersProvider = null;
     isDestroying = false;
     log("warn", "Error during destroy, forced cleanup completed", { error });
   }
@@ -6520,6 +6683,8 @@ var tracelog = {
   off,
   setTransformer,
   removeTransformer,
+  setCustomHeaders,
+  removeCustomHeaders,
   isInitialized,
   destroy,
   setQaMode: setQaMode2,