@journium/react 1.1.4 → 1.2.0

package/dist/context.d.ts

@@ -11,7 +11,16 @@ interface JourniumProviderProps {
     children: ReactNode;
     config: JourniumConfig;
 }
+/**
+ * Provides the Journium analytics instance to the React tree.
+ * Initializes the SDK on mount and tears it down on unmount.
+ * Re-initializes if `config` changes.
+ */
 export declare const JourniumProvider: React.FC<JourniumProviderProps>;
+/**
+ * Access the Journium analytics instance and effective options from any component
+ * inside `JourniumProvider`. Throws if called outside the provider.
+ */
 export declare const useJournium: () => JourniumContextValue;
 export {};
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAkD,SAAS,EAAE,MAAM,OAAO,CAAC;AACzF,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtE,KAAK,yBAAyB,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;AAEzD,UAAU,oBAAoB;IAC5B,SAAS,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC5C,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/C;AAID,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAuC5D,CAAC;AAEF,eAAO,MAAM,WAAW,QAAO,oBAM9B,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAkD,SAAS,EAAE,MAAM,OAAO,CAAC;AACzF,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEtE,KAAK,yBAAyB,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;AAEzD,UAAU,oBAAoB;IAC5B,SAAS,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAC5C,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/C;AAID,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAuC5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,QAAO,oBAM9B,CAAC"}

package/dist/hooks.d.ts

@@ -1,8 +1,22 @@
+/** Returns a stable callback for tracking custom events. */
 export declare const useTrackEvent: () => (event: string, properties?: Record<string, unknown>) => void;
+/** Returns a stable callback for identifying the current user. */
 export declare const useIdentify: () => (distinctId: string, attributes?: Record<string, unknown>) => void;
+/** Returns a stable callback for resetting the current identity and starting a new anonymous session. */
 export declare const useReset: () => () => void;
+/** Returns a stable callback for manually capturing a $pageview event. */
 export declare const useTrackPageview: () => (properties?: Record<string, unknown>) => void;
+/**
+ * Automatically captures a $pageview whenever the given dependencies change.
+ * Also fires once on mount. Useful for manual SPA route tracking when automatic
+ * tracking is disabled.
+ */
 export declare const useAutoTrackPageview: (dependencies?: React.DependencyList, properties?: Record<string, unknown>) => void;
+/**
+ * Returns `stopAutocapture` to pause DOM event capture and pageview tracking.
+ * `startAutocapture` is also exposed for restarting after an explicit stop,
+ * but under normal usage autocapture starts automatically on SDK init.
+ */
 export declare const useAutocapture: () => {
     startAutocapture: () => void;
     stopAutocapture: () => void;

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa,gBAId,MAAM,eAAe,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAOvD,CAAC;AAEF,eAAO,MAAM,WAAW,qBAIP,MAAM,eAAe,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAO5D,CAAC;AAEF,eAAO,MAAM,QAAQ,kBAQpB,CAAC;AAEF,eAAO,MAAM,gBAAgB,sBAIX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAOxC,CAAC;AAEF,eAAO,MAAM,oBAAoB,kBACjB,KAAK,CAAC,cAAc,eACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAOrC,CAAC;AAEF,eAAO,MAAM,cAAc;;;CAgB1B,CAAC"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAGA,4DAA4D;AAC5D,eAAO,MAAM,aAAa,gBAId,MAAM,eAAe,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAOvD,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,WAAW,qBAIP,MAAM,eAAe,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAO5D,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,QAAQ,kBAQpB,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,sBAIX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAOxC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,eAAc,KAAK,CAAC,cAAmB,EACvC,aAAa,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAOrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;CAgB1B,CAAC"}

package/dist/index.cjs

@@ -1104,28 +1104,31 @@ class PageviewTracker {
      * Start automatic autocapture for pageviews
      * @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.
+     * @param patchHistory - whether to monkey-patch pushState/replaceState/popstate (default: true).
+     *   Pass false when a framework-native router tracker (e.g. Next.js) owns SPA pageviews.
      */
-    startAutoPageviewTracking(captureInitialPageview = true) {
+    startAutoPageviewTracking(captureInitialPageview = true, patchHistory = true) {
         if (captureInitialPageview) {
             this.capturePageview();
         }
-        if (typeof window !== 'undefined') {
-            // Store original methods for cleanup
-            this.originalPushState = window.history.pushState;
-            this.originalReplaceState = window.history.replaceState;
-            window.history.pushState = (...args) => {
-                this.originalPushState.apply(window.history, args);
-                setTimeout(() => this.capturePageview(), 0);
-            };
-            window.history.replaceState = (...args) => {
-                this.originalReplaceState.apply(window.history, args);
-                setTimeout(() => this.capturePageview(), 0);
-            };
-            this.popStateHandler = () => {
-                setTimeout(() => this.capturePageview(), 0);
-            };
-            window.addEventListener('popstate', this.popStateHandler);
+        if (!patchHistory || typeof window === 'undefined') {
+            return;
         }
+        // Store original methods for cleanup
+        this.originalPushState = window.history.pushState;
+        this.originalReplaceState = window.history.replaceState;
+        window.history.pushState = (...args) => {
+            this.originalPushState.apply(window.history, args);
+            setTimeout(() => this.capturePageview(), 0);
+        };
+        window.history.replaceState = (...args) => {
+            this.originalReplaceState.apply(window.history, args);
+            setTimeout(() => this.capturePageview(), 0);
+        };
+        this.popStateHandler = () => {
+            setTimeout(() => this.capturePageview(), 0);
+        };
+        window.addEventListener('popstate', this.popStateHandler);
     }
     /**
      * Stop automatic autocapture for pageviews
@@ -1540,6 +1543,20 @@ class JourniumAnalytics {
         // This handles cached remote options or local options with autocapture enabled
         this.startAutocaptureIfEnabled(initialEffectiveOptions);
     }
+    resolvePageviewOptions(autoTrackPageviews) {
+        if (autoTrackPageviews === false) {
+            return { enabled: false, trackSpaPageviews: false, captureInitialPageview: false };
+        }
+        if (autoTrackPageviews === true || autoTrackPageviews === undefined) {
+            return { enabled: true, trackSpaPageviews: true, captureInitialPageview: true };
+        }
+        // object form implies enabled
+        return {
+            enabled: true,
+            trackSpaPageviews: autoTrackPageviews.trackSpaPageviews !== false,
+            captureInitialPageview: autoTrackPageviews.trackInitialPageview !== false,
+        };
+    }
     resolveAutocaptureOptions(autocapture) {
         if (autocapture === false) {
             return {
@@ -1554,39 +1571,50 @@ class JourniumAnalytics {
         }
         return autocapture;
     }
+    /** Track a custom event with optional properties. */
     track(event, properties) {
         this.client.track(event, properties);
     }
+    /** Associate the current session with a known user identity and optional attributes. */
     identify(distinctId, attributes) {
         this.client.identify(distinctId, attributes);
     }
+    /** Clear the current identity, starting a new anonymous session. */
     reset() {
         this.client.reset();
     }
+    /** Manually capture a $pageview event with optional custom properties. */
     capturePageview(properties) {
         this.pageviewTracker.capturePageview(properties);
     }
+    /**
+     * Manually start autocapture (pageview tracking + DOM event capture).
+     * Under normal usage this is not needed — the SDK starts automatically on init.
+     * Useful only if autocapture was explicitly stopped and needs to be restarted.
+     */
     startAutocapture() {
         // Always check effective options (which may include remote options)
         const effectiveOptions = this.client.getEffectiveOptions();
-        // Only enable if effectiveOptions are loaded and autoTrackPageviews is not explicitly false
-        const autoTrackPageviews = effectiveOptions && Object.keys(effectiveOptions).length > 0
-            ? effectiveOptions.autoTrackPageviews !== false
-            : false;
-        const autocaptureEnabled = effectiveOptions && Object.keys(effectiveOptions).length > 0
+        // Only start if effectiveOptions are actually loaded (non-empty)
+        const hasOptions = effectiveOptions && Object.keys(effectiveOptions).length > 0;
+        const { enabled: autoTrackPageviews, trackSpaPageviews, captureInitialPageview } = hasOptions
+            ? this.resolvePageviewOptions(effectiveOptions.autoTrackPageviews)
+            : { enabled: false, trackSpaPageviews: false, captureInitialPageview: false };
+        const autocaptureEnabled = hasOptions
             ? effectiveOptions.autocapture !== false
             : false;
         // Update autocapture tracker options if they've changed
         const autocaptureOptions = this.resolveAutocaptureOptions(effectiveOptions.autocapture);
         this.autocaptureTracker.updateOptions(autocaptureOptions);
         if (autoTrackPageviews) {
-            this.pageviewTracker.startAutoPageviewTracking();
+            this.pageviewTracker.startAutoPageviewTracking(captureInitialPageview, trackSpaPageviews);
         }
         if (autocaptureEnabled) {
             this.autocaptureTracker.start();
         }
         this.autocaptureStarted = true;
     }
+    /** Stop autocapture — pauses pageview tracking and DOM event capture. */
     stopAutocapture() {
         this.pageviewTracker.stopAutocapture();
         this.autocaptureTracker.stop();
@@ -1606,13 +1634,13 @@ class JourniumAnalytics {
         const hasActualOptions = effectiveOptions && Object.keys(effectiveOptions).length > 0;
         if (hasActualOptions) {
             // Use same logic as manual startAutocapture() but only start automatically
-            const autoTrackPageviews = effectiveOptions.autoTrackPageviews !== false;
+            const { enabled: autoTrackPageviews, trackSpaPageviews, captureInitialPageview } = this.resolvePageviewOptions(effectiveOptions.autoTrackPageviews);
             const autocaptureEnabled = effectiveOptions.autocapture !== false;
             // Update autocapture tracker options
             const autocaptureOptions = this.resolveAutocaptureOptions(effectiveOptions.autocapture);
             this.autocaptureTracker.updateOptions(autocaptureOptions);
             if (autoTrackPageviews) {
-                this.pageviewTracker.startAutoPageviewTracking();
+                this.pageviewTracker.startAutoPageviewTracking(captureInitialPageview, trackSpaPageviews);
             }
             if (autocaptureEnabled) {
                 this.autocaptureTracker.start();
@@ -1637,21 +1665,23 @@ class JourniumAnalytics {
             this.autocaptureTracker.stop();
             this.autocaptureStarted = false;
         }
-        const autoTrackPageviews = effectiveOptions.autoTrackPageviews !== false;
+        const { enabled: autoTrackPageviews, trackSpaPageviews, captureInitialPageview } = this.resolvePageviewOptions(effectiveOptions.autoTrackPageviews);
         const autocaptureEnabled = effectiveOptions.autocapture !== false;
         const autocaptureOptions = this.resolveAutocaptureOptions(effectiveOptions.autocapture);
         this.autocaptureTracker.updateOptions(autocaptureOptions);
         if (autoTrackPageviews) {
-            this.pageviewTracker.startAutoPageviewTracking(isFirstStart);
+            this.pageviewTracker.startAutoPageviewTracking(isFirstStart && captureInitialPageview, trackSpaPageviews);
         }
         if (autocaptureEnabled) {
             this.autocaptureTracker.start();
         }
         this.autocaptureStarted = autoTrackPageviews || autocaptureEnabled;
     }
+    /** Flush all queued events to the ingestion endpoint immediately. */
     async flush() {
         return this.client.flush();
     }
+    /** Return the currently active options (merged local + remote config). */
     getEffectiveOptions() {
         return this.client.getEffectiveOptions();
     }
@@ -1661,6 +1691,7 @@ class JourniumAnalytics {
     onOptionsChange(callback) {
         return this.client.onOptionsChange(callback);
     }
+    /** Tear down the analytics instance: stop all tracking, flush pending events, and release resources. */
     destroy() {
         this.pageviewTracker.stopAutocapture();
         this.autocaptureTracker.stop();
@@ -1670,11 +1701,17 @@ class JourniumAnalytics {
         this.client.destroy();
     }
 }
+/** Create and return a new JourniumAnalytics instance for the given config. */
 const init = (config) => {
     return new JourniumAnalytics(config);
 };
 
 const JourniumContext = React.createContext(undefined);
+/**
+ * Provides the Journium analytics instance to the React tree.
+ * Initializes the SDK on mount and tears it down on unmount.
+ * Re-initializes if `config` changes.
+ */
 const JourniumProvider = ({ children, config, }) => {
     const [analytics, setAnalytics] = React.useState(null);
     const [effectiveOptions, setEffectiveOptions] = React.useState(null);
@@ -1702,6 +1739,10 @@ const JourniumProvider = ({ children, config, }) => {
     }, [config]);
     return (React.createElement(JourniumContext.Provider, { value: { analytics, config, effectiveOptions } }, children));
 };
+/**
+ * Access the Journium analytics instance and effective options from any component
+ * inside `JourniumProvider`. Throws if called outside the provider.
+ */
 const useJournium = () => {
     const context = React.useContext(JourniumContext);
     if (!context) {
@@ -1710,6 +1751,7 @@ const useJournium = () => {
     return context;
 };
 
+/** Returns a stable callback for tracking custom events. */
 const useTrackEvent = () => {
     const { analytics } = useJournium();
     return React.useCallback((event, properties) => {
@@ -1718,6 +1760,7 @@ const useTrackEvent = () => {
         }
     }, [analytics]);
 };
+/** Returns a stable callback for identifying the current user. */
 const useIdentify = () => {
     const { analytics } = useJournium();
     return React.useCallback((distinctId, attributes) => {
@@ -1726,6 +1769,7 @@ const useIdentify = () => {
         }
     }, [analytics]);
 };
+/** Returns a stable callback for resetting the current identity and starting a new anonymous session. */
 const useReset = () => {
     const { analytics } = useJournium();
     return React.useCallback(() => {
@@ -1734,6 +1778,7 @@ const useReset = () => {
         }
     }, [analytics]);
 };
+/** Returns a stable callback for manually capturing a $pageview event. */
 const useTrackPageview = () => {
     const { analytics } = useJournium();
     return React.useCallback((properties) => {
@@ -1742,12 +1787,22 @@ const useTrackPageview = () => {
         }
     }, [analytics]);
 };
+/**
+ * Automatically captures a $pageview whenever the given dependencies change.
+ * Also fires once on mount. Useful for manual SPA route tracking when automatic
+ * tracking is disabled.
+ */
 const useAutoTrackPageview = (dependencies = [], properties) => {
     const trackPageview = useTrackPageview();
     React.useEffect(() => {
         trackPageview(properties);
     }, [trackPageview, properties, ...dependencies]);
 };
+/**
+ * Returns `stopAutocapture` to pause DOM event capture and pageview tracking.
+ * `startAutocapture` is also exposed for restarting after an explicit stop,
+ * but under normal usage autocapture starts automatically on SDK init.
+ */
 const useAutocapture = () => {
     const { analytics } = useJournium();
     const startAutocapture = React.useCallback(() => {