@journium/js 1.1.1 → 1.2.1

package/dist/index.mjs

@@ -1,7 +1,7 @@
 /**
  * uuidv7: A JavaScript implementation of UUID version 7
  *
- * Copyright 2021-2024 LiosK
+ * Copyright 2021-2025 LiosK
  *
  * @license Apache-2.0
  * @packageDocumentation
@@ -230,7 +230,10 @@ class V7Generator {
      * number generator should be cryptographically strong and securely seeded.
      */
     constructor(randomNumberGenerator) {
-        this.timestamp = 0;
+        /**
+         * Biased by one to distinguish zero (uninitialized) and zero (UNIX epoch).
+         */
+        this.timestamp_biased = 0;
         this.counter = 0;
         this.random = randomNumberGenerator !== null && randomNumberGenerator !== void 0 ? randomNumberGenerator : getDefaultRandom();
     }
@@ -276,13 +279,13 @@ class V7Generator {
      *
      * @param rollbackAllowance - The amount of `unixTsMs` rollback that is
      * considered significant. A suggested value is `10_000` (milliseconds).
-     * @throws RangeError if `unixTsMs` is not a 48-bit positive integer.
+     * @throws RangeError if `unixTsMs` is not a 48-bit unsigned integer.
      */
     generateOrResetCore(unixTsMs, rollbackAllowance) {
         let value = this.generateOrAbortCore(unixTsMs, rollbackAllowance);
         if (value === undefined) {
             // reset state and resume
-            this.timestamp = 0;
+            this.timestamp_biased = 0;
             value = this.generateOrAbortCore(unixTsMs, rollbackAllowance);
         }
         return value;
@@ -296,28 +299,29 @@ class V7Generator {
      *
      * @param rollbackAllowance - The amount of `unixTsMs` rollback that is
      * considered significant. A suggested value is `10_000` (milliseconds).
-     * @throws RangeError if `unixTsMs` is not a 48-bit positive integer.
+     * @throws RangeError if `unixTsMs` is not a 48-bit unsigned integer.
      */
     generateOrAbortCore(unixTsMs, rollbackAllowance) {
         const MAX_COUNTER = 4398046511103;
         if (!Number.isInteger(unixTsMs) ||
-            unixTsMs < 1 ||
+            unixTsMs < 0 ||
             unixTsMs > 281474976710655) {
-            throw new RangeError("`unixTsMs` must be a 48-bit positive integer");
+            throw new RangeError("`unixTsMs` must be a 48-bit unsigned integer");
         }
         else if (rollbackAllowance < 0 || rollbackAllowance > 281474976710655) {
             throw new RangeError("`rollbackAllowance` out of reasonable range");
         }
-        if (unixTsMs > this.timestamp) {
-            this.timestamp = unixTsMs;
+        unixTsMs++;
+        if (unixTsMs > this.timestamp_biased) {
+            this.timestamp_biased = unixTsMs;
             this.resetCounter();
         }
-        else if (unixTsMs + rollbackAllowance >= this.timestamp) {
+        else if (unixTsMs + rollbackAllowance >= this.timestamp_biased) {
             // go on with previous timestamp if new one is not much smaller
             this.counter++;
             if (this.counter > MAX_COUNTER) {
                 // increment timestamp at counter overflow
-                this.timestamp++;
+                this.timestamp_biased++;
                 this.resetCounter();
             }
         }
@@ -325,7 +329,7 @@ class V7Generator {
             // abort if clock went backwards to unbearable extent
             return undefined;
         }
-        return UUID.fromFieldsV7(this.timestamp, Math.trunc(this.counter / 2 ** 30), this.counter & (2 ** 30 - 1), this.random.nextUint32());
+        return UUID.fromFieldsV7(this.timestamp_biased - 1, Math.trunc(this.counter / 2 ** 30), this.counter & (2 ** 30 - 1), this.random.nextUint32());
     }
     /** Initializes the counter at a 42-bit random integer. */
     resetCounter() {
@@ -701,6 +705,9 @@ class JourniumClient {
         this.queue = [];
         this.stagedEvents = [];
         this.flushTimer = null;
+        this.remoteOptionsRefreshTimer = null;
+        this.isRefreshing = false;
+        this.lastRemoteOptions = null;
         this.initializationComplete = false;
         this.initializationFailed = false;
         this.optionsChangeCallbacks = new Set();
@@ -754,61 +761,24 @@ class JourniumClient {
         }
     }
     async initializeAsync() {
-        var _a;
         try {
             Logger.log('Journium: Starting initialization - fetching fresh remote config...');
-            // Step 1: Try to fetch fresh remote config with timeout and retry
             const remoteOptions = await this.fetchRemoteOptionsWithRetry();
-            if (remoteOptions) {
-                // Step 2: Cache the fresh remote config
-                this.saveCachedOptions(remoteOptions);
-                // Step 3: Merge local options over remote config (local overrides remote)
-                if (this.config.options) {
-                    this.effectiveOptions = mergeOptions(this.config.options, remoteOptions);
-                    Logger.log('Journium: Using fresh remote config merged with local options:', this.effectiveOptions);
-                }
-                else {
-                    this.effectiveOptions = remoteOptions;
-                    Logger.log('Journium: Using fresh remote config:', this.effectiveOptions);
-                }
-            }
-            else {
-                // Step 4: Fallback to cached config if fresh fetch failed
-                /* const cachedRemoteOptions = this.loadCachedOptions();
-                
-                if (cachedRemoteOptions) {
-                  if (this.config.options) {
-                    this.effectiveOptions = mergeOptions(this.config.options, cachedRemoteOptions);
-                    Logger.log('Journium: Fresh config failed, using cached remote config merged with local options:', this.effectiveOptions);
-                  } else {
-                    this.effectiveOptions = cachedRemoteOptions;
-                    Logger.log('Journium: Fresh config failed, using cached remote config:', this.effectiveOptions);
-                  }
-                } else {
-                  // Step 5: No remote config and no cached config - initialization fails
-                  Logger.error('Journium: Initialization failed - no remote config available and no cached config found');
-                  this.initializationFailed = true;
-                  this.initializationComplete = false;
-                  return;
-                } */
-            }
-            // Step 6: Update identity manager session timeout if provided
-            if (this.effectiveOptions.sessionTimeout) {
-                this.identityManager.updateSessionTimeout(this.effectiveOptions.sessionTimeout);
+            if (!remoteOptions) {
+                Logger.error('Journium: Initialization failed - no remote config available');
+                this.initializationFailed = true;
+                return;
             }
-            // Step 7: Update Logger debug setting
-            Logger.setDebug((_a = this.effectiveOptions.debug) !== null && _a !== void 0 ? _a : false);
-            // Step 8: Mark initialization as complete
+            this.applyRemoteOptions(remoteOptions);
+            Logger.log('Journium: Effective options after init:', this.effectiveOptions);
             this.initializationComplete = true;
             this.initializationFailed = false;
-            // Step 9: Process any staged events
             this.processStagedEvents();
-            // Step 10: Start flush timer
             if (this.effectiveOptions.flushInterval && this.effectiveOptions.flushInterval > 0) {
                 this.startFlushTimer();
             }
-            Logger.log('Journium: Initialization complete with options:', this.effectiveOptions);
-            // Step 11: Notify callbacks about options
+            this.startRemoteOptionsRefreshTimer();
+            Logger.log('Journium: Initialization complete');
             this.notifyOptionsChange();
         }
         catch (error) {
@@ -879,35 +849,21 @@ class JourniumClient {
     processStagedEvents() {
         if (this.stagedEvents.length === 0)
             return;
+        if (this.ingestionPaused) {
+            Logger.warn(`Journium: Ingestion is paused — discarding ${this.stagedEvents.length} staged events`);
+            this.stagedEvents = [];
+            return;
+        }
         Logger.log(`Journium: Processing ${this.stagedEvents.length} staged events`);
-        // Move staged events to main queue, adding identity properties now
-        const identity = this.identityManager.getIdentity();
-        const userAgentInfo = this.identityManager.getUserAgentInfo();
         for (const stagedEvent of this.stagedEvents) {
-            // Add identity properties that weren't available during staging
-            const eventWithIdentity = {
+            this.queue.push({
                 ...stagedEvent,
-                properties: {
-                    $device_id: identity === null || identity === void 0 ? void 0 : identity.$device_id,
-                    distinct_id: identity === null || identity === void 0 ? void 0 : identity.distinct_id,
-                    $session_id: identity === null || identity === void 0 ? void 0 : identity.$session_id,
-                    $is_identified: (identity === null || identity === void 0 ? void 0 : identity.$user_state) === 'identified',
-                    $current_url: typeof window !== 'undefined' ? window.location.href : '',
-                    $pathname: typeof window !== 'undefined' ? window.location.pathname : '',
-                    ...userAgentInfo,
-                    $lib_version: '0.1.0', // TODO: Get from package.json
-                    $platform: 'web',
-                    ...stagedEvent.properties, // Original properties override system properties
-                },
-            };
-            this.queue.push(eventWithIdentity);
+                properties: this.buildIdentityProperties(stagedEvent.properties),
+            });
         }
-        // Clear staged events
         this.stagedEvents = [];
         Logger.log('Journium: Staged events processed and moved to main queue');
-        // Check if we should flush immediately
         if (this.queue.length >= this.effectiveOptions.flushAt) {
-            // console.log('1 Journium: Flushing events...'+JSON.stringify(this.effectiveOptions));
             this.flush();
         }
     }
@@ -915,12 +871,88 @@ class JourniumClient {
         if (this.flushTimer) {
             clearInterval(this.flushTimer);
         }
-        // Use universal setInterval (works in both browser and Node.js)
         this.flushTimer = setInterval(() => {
-            // console.log('2 Journium: Flushing events...'+JSON.stringify(this.effectiveOptions));
             this.flush();
         }, this.effectiveOptions.flushInterval);
     }
+    startRemoteOptionsRefreshTimer() {
+        // Clear any existing timer to prevent duplicate intervals
+        if (this.remoteOptionsRefreshTimer) {
+            clearInterval(this.remoteOptionsRefreshTimer);
+            this.remoteOptionsRefreshTimer = null;
+        }
+        this.remoteOptionsRefreshTimer = setInterval(() => {
+            this.refreshRemoteOptions();
+        }, JourniumClient.REMOTE_OPTIONS_REFRESH_INTERVAL);
+        Logger.log(`Journium: Scheduling remote options refresh every ${JourniumClient.REMOTE_OPTIONS_REFRESH_INTERVAL}ms`);
+    }
+    async refreshRemoteOptions() {
+        if (this.isRefreshing) {
+            Logger.log('Journium: Remote options refresh already in progress, skipping');
+            return;
+        }
+        this.isRefreshing = true;
+        Logger.log('Journium: Periodic remote options refresh triggered');
+        try {
+            const remoteOptions = await this.fetchRemoteOptionsWithRetry();
+            if (!remoteOptions) {
+                Logger.warn('Journium: Periodic remote options refresh failed, keeping current options');
+                return;
+            }
+            const prevRemoteSnapshot = JSON.stringify(this.lastRemoteOptions);
+            const prevFlushInterval = this.effectiveOptions.flushInterval;
+            this.applyRemoteOptions(remoteOptions);
+            if (prevRemoteSnapshot === JSON.stringify(this.lastRemoteOptions)) {
+                Logger.log('Journium: Remote options unchanged after refresh, no update needed');
+                return;
+            }
+            Logger.log('Journium: Remote options updated after refresh:', this.effectiveOptions);
+            if (this.effectiveOptions.flushInterval !== prevFlushInterval) {
+                if (this.effectiveOptions.flushInterval && this.effectiveOptions.flushInterval > 0) {
+                    this.startFlushTimer();
+                }
+                else if (this.flushTimer) {
+                    clearInterval(this.flushTimer);
+                    this.flushTimer = null;
+                }
+            }
+            this.notifyOptionsChange();
+        }
+        catch (error) {
+            Logger.error('Journium: Periodic remote options refresh encountered an error:', error);
+        }
+        finally {
+            this.isRefreshing = false;
+        }
+    }
+    applyRemoteOptions(remoteOptions) {
+        var _a;
+        this.lastRemoteOptions = remoteOptions;
+        this.effectiveOptions = this.config.options
+            ? mergeOptions(this.config.options, remoteOptions)
+            : remoteOptions;
+        this.saveCachedOptions(remoteOptions);
+        if (this.effectiveOptions.sessionTimeout) {
+            this.identityManager.updateSessionTimeout(this.effectiveOptions.sessionTimeout);
+        }
+        Logger.setDebug((_a = this.effectiveOptions.debug) !== null && _a !== void 0 ? _a : false);
+    }
+    buildIdentityProperties(userProperties = {}) {
+        const identity = this.identityManager.getIdentity();
+        const userAgentInfo = this.identityManager.getUserAgentInfo();
+        return {
+            $device_id: identity === null || identity === void 0 ? void 0 : identity.$device_id,
+            distinct_id: identity === null || identity === void 0 ? void 0 : identity.distinct_id,
+            $session_id: identity === null || identity === void 0 ? void 0 : identity.$session_id,
+            $is_identified: (identity === null || identity === void 0 ? void 0 : identity.$user_state) === 'identified',
+            $current_url: typeof window !== 'undefined' ? window.location.href : '',
+            $pathname: typeof window !== 'undefined' ? window.location.pathname : '',
+            ...userAgentInfo,
+            $lib_version: '0.1.0', // TODO: Get from package.json
+            $platform: 'web',
+            ...userProperties,
+        };
+    }
     async sendEvents(events) {
         if (!events.length)
             return;
@@ -980,9 +1012,7 @@ class JourniumClient {
             event,
             properties: { ...properties }, // Only user properties for now
         };
-        // Stage events during initialization, add to queue after initialization
         if (!this.initializationComplete) {
-            // If initialization failed, reject events
             if (this.initializationFailed) {
                 Logger.warn('Journium: track() call rejected - initialization failed');
                 return;
@@ -991,34 +1021,17 @@ class JourniumClient {
             Logger.log('Journium: Event staged during initialization', journiumEvent);
             return;
         }
-        // If initialization failed, reject events
-        if (this.initializationFailed) {
-            Logger.warn('Journium: track() call rejected - initialization failed');
+        if (this.ingestionPaused) {
+            Logger.warn('Journium: Ingestion is paused — event dropped:', journiumEvent.event);
             return;
         }
-        // Add identity properties for immediate events (after initialization)
-        const identity = this.identityManager.getIdentity();
-        const userAgentInfo = this.identityManager.getUserAgentInfo();
         const eventWithIdentity = {
             ...journiumEvent,
-            properties: {
-                $device_id: identity === null || identity === void 0 ? void 0 : identity.$device_id,
-                distinct_id: identity === null || identity === void 0 ? void 0 : identity.distinct_id,
-                $session_id: identity === null || identity === void 0 ? void 0 : identity.$session_id,
-                $is_identified: (identity === null || identity === void 0 ? void 0 : identity.$user_state) === 'identified',
-                $current_url: typeof window !== 'undefined' ? window.location.href : '',
-                $pathname: typeof window !== 'undefined' ? window.location.pathname : '',
-                ...userAgentInfo,
-                $lib_version: '0.1.0', // TODO: Get from package.json
-                $platform: 'web',
-                ...properties, // User-provided properties override system properties
-            },
+            properties: this.buildIdentityProperties(properties),
         };
         this.queue.push(eventWithIdentity);
         Logger.log('Journium: Event tracked', eventWithIdentity);
-        // Only flush if we have effective options (after initialization)
         if (this.effectiveOptions.flushAt && this.queue.length >= this.effectiveOptions.flushAt) {
-            // console.log('3 Journium: Flushing events...'+JSON.stringify(this.effectiveOptions));
             this.flush();
         }
     }
@@ -1045,12 +1058,20 @@ class JourniumClient {
             clearInterval(this.flushTimer);
             this.flushTimer = null;
         }
+        if (this.remoteOptionsRefreshTimer) {
+            clearInterval(this.remoteOptionsRefreshTimer);
+            this.remoteOptionsRefreshTimer = null;
+        }
         this.flush();
     }
     getEffectiveOptions() {
         return this.effectiveOptions;
     }
+    get ingestionPaused() {
+        return this.effectiveOptions['ingestionPaused'] === true;
+    }
 }
+JourniumClient.REMOTE_OPTIONS_REFRESH_INTERVAL = 15 * 60 * 1000; // 15 minutes
 
 class PageviewTracker {
     constructor(client) {
@@ -1077,10 +1098,13 @@ class PageviewTracker {
     }
     /**
      * Start automatic autocapture for pageviews
-     * @returns void
+     * @param captureInitialPageview - whether to fire a $pageview immediately on start (default: true).
+     *   Pass false when restarting after a remote options update to avoid a spurious pageview.
      */
-    startAutoPageviewTracking() {
-        this.capturePageview();
+    startAutoPageviewTracking(captureInitialPageview = true) {
+        if (captureInitialPageview) {
+            this.capturePageview();
+        }
         if (typeof window !== 'undefined') {
             // Store original methods for cleanup
             this.originalPushState = window.history.pushState;
@@ -1599,21 +1623,22 @@ class JourniumAnalytics {
      * Handle effective options change (e.g., when remote options are fetched)
      */
     handleOptionsChange(effectiveOptions) {
-        // Stop current autocapture if it was already started
+        // If autocapture was never started before, this is the initial options application
+        // (async init completed) — treat it like a page load and capture a pageview.
+        // If it was already started, this is a periodic remote options update — only
+        // re-register listeners without emitting a spurious pageview.
+        const isFirstStart = !this.autocaptureStarted;
         if (this.autocaptureStarted) {
             this.pageviewTracker.stopAutocapture();
             this.autocaptureTracker.stop();
             this.autocaptureStarted = false;
         }
-        // Evaluate if autocapture should be enabled with new options
         const autoTrackPageviews = effectiveOptions.autoTrackPageviews !== false;
         const autocaptureEnabled = effectiveOptions.autocapture !== false;
-        // Update autocapture tracker options
         const autocaptureOptions = this.resolveAutocaptureOptions(effectiveOptions.autocapture);
         this.autocaptureTracker.updateOptions(autocaptureOptions);
-        // Start autocapture based on new options (even if it wasn't started before)
         if (autoTrackPageviews) {
-            this.pageviewTracker.startAutoPageviewTracking();
+            this.pageviewTracker.startAutoPageviewTracking(isFirstStart);
         }
         if (autocaptureEnabled) {
             this.autocaptureTracker.start();