@journium/js 1.2.2 → 1.3.0

package/dist/journium.js

@@ -2,6 +2,9 @@
 (function (exports) {
     'use strict';
 
+    // @journium/js@1.3.0 is replaced at build time by @rollup/plugin-replace
+    const SDK_VERSION = '@journium/js@1.3.0';
+
     /**
      * uuidv7: A JavaScript implementation of UUID version 7
      *
@@ -938,6 +941,7 @@
             Logger.setDebug((_a = this.effectiveOptions.debug) !== null && _a !== void 0 ? _a : false);
         }
         buildIdentityProperties(userProperties = {}) {
+            var _a, _b;
             const identity = this.identityManager.getIdentity();
             const userAgentInfo = this.identityManager.getUserAgentInfo();
             return {
@@ -948,7 +952,7 @@
                 $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
+                $sdk_version: (_b = (_a = this.config.options) === null || _a === void 0 ? void 0 : _a._sdkVersion) !== null && _b !== void 0 ? _b : 'unknown',
                 $platform: 'web',
                 ...userProperties,
             };
@@ -1089,7 +1093,7 @@
                 $host: url.host,
                 $pathname: url.pathname,
                 $search: url.search,
-                $title: getPageTitle(),
+                $page_title: getPageTitle(),
                 $referrer: getReferrer(),
                 ...customProperties,
             };
@@ -1100,28 +1104,31 @@
          * 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
@@ -1162,6 +1169,8 @@
                 ignoreClasses: ['journium-ignore'],
                 ignoreElements: ['script', 'style', 'noscript'],
                 captureContentText: true,
+                dataAttributePrefixes: ['jrnm-'],
+                dataAttributeNames: ['data-testid', 'data-track'],
                 ...options,
             };
         }
@@ -1183,6 +1192,8 @@
                 ignoreClasses: ['journium-ignore'],
                 ignoreElements: ['script', 'style', 'noscript'],
                 captureContentText: true,
+                dataAttributePrefixes: ['jrnm-'],
+                dataAttributeNames: ['data-testid', 'data-track'],
                 ...options,
             };
             // Restart if it was active before
@@ -1225,10 +1236,7 @@
                     return;
                 }
                 const properties = this.getElementProperties(target, 'click');
-                this.client.track('$autocapture', {
-                    $event_type: 'click',
-                    ...properties,
-                });
+                this.client.track('$autocapture', properties);
             };
             document.addEventListener('click', clickListener, true);
             this.listeners.set('click', clickListener);
@@ -1240,10 +1248,7 @@
                     return;
                 }
                 const properties = this.getFormProperties(target, 'submit');
-                this.client.track('$autocapture', {
-                    $event_type: 'submit',
-                    ...properties,
-                });
+                this.client.track('$autocapture', properties);
             };
             document.addEventListener('submit', submitListener, true);
             this.listeners.set('submit', submitListener);
@@ -1255,10 +1260,7 @@
                     return;
                 }
                 const properties = this.getInputProperties(target, 'change');
-                this.client.track('$autocapture', {
-                    $event_type: 'change',
-                    ...properties,
-                });
+                this.client.track('$autocapture', properties);
             };
             document.addEventListener('change', changeListener, true);
             this.listeners.set('change', changeListener);
@@ -1311,6 +1313,7 @@
         }
         getElementProperties(element, eventType) {
             const properties = {
+                $event_type: eventType,
                 $element_tag: element.tagName.toLowerCase(),
                 $element_type: this.getElementType(element),
             };
@@ -1320,6 +1323,7 @@
             }
             if (element.className) {
                 properties.$element_classes = Array.from(element.classList);
+                properties.$element_semantic_classes = this.extractSemanticClasses(element.classList);
             }
             // Element attributes
             const relevantAttributes = ['name', 'role', 'aria-label', 'data-testid', 'data-track'];
@@ -1329,6 +1333,33 @@
                     properties[`$element_${attr.replace('-', '_')}`] = value;
                 }
             });
+            // Configurable data-* attribute capture
+            const prefixes = this.options.dataAttributePrefixes || ['jrnm-'];
+            const exactNames = new Set(this.options.dataAttributeNames || ['data-testid', 'data-track']);
+            const relevantSet = new Set(relevantAttributes);
+            let dataAttrCount = 0;
+            for (let i = 0; i < element.attributes.length && dataAttrCount < 10; i++) {
+                const attr = element.attributes.item(i);
+                if (!attr || !attr.name.startsWith('data-'))
+                    continue;
+                if (relevantSet.has(attr.name))
+                    continue;
+                const suffix = attr.name.slice(5); // strip 'data-'
+                const matchesPrefix = prefixes.some(p => suffix.startsWith(p));
+                const matchesName = exactNames.has(attr.name);
+                if (matchesPrefix || matchesName) {
+                    const propName = `$attr_${attr.name.replace(/-/g, '_')}`;
+                    properties[propName] = attr.value;
+                    dataAttrCount++;
+                }
+            }
+            // Link href as first-class property
+            if (element.tagName.toLowerCase() === 'a') {
+                const href = element.getAttribute('href');
+                if (href) {
+                    properties.$element_href = href;
+                }
+            }
             // Element content
             if (this.options.captureContentText) {
                 const text = this.getElementText(element);
@@ -1358,10 +1389,13 @@
                     properties.$parent_id = element.parentElement.id;
                 }
             }
-            // URL information
+            // URL and page context
             properties.$current_url = window.location.href;
             properties.$host = window.location.host;
             properties.$pathname = window.location.pathname;
+            properties.$search = window.location.search;
+            properties.$page_title = document.title;
+            properties.$referrer = document.referrer;
             return properties;
         }
         getFormProperties(form, eventType) {
@@ -1510,6 +1544,38 @@
                 ids: ids.reverse()
             };
         }
+        extractSemanticClasses(classList) {
+            const results = new Set();
+            for (let i = 0; i < classList.length; i++) {
+                const cls = classList.item(i);
+                if (!cls)
+                    continue;
+                const parts = cls.split('__');
+                if (parts.length >= 3) {
+                    // CSS module pattern: Module__hash__name → take last segment
+                    const last = parts[parts.length - 1];
+                    if (last)
+                        results.add(last);
+                }
+                else if (parts.length === 2) {
+                    // 2-part __ class (e.g., Module__hash) → drop, no semantic name
+                    continue;
+                }
+                else {
+                    // Single-part class — keep unless it looks like a hash
+                    if (!this.isHashLike(cls)) {
+                        results.add(cls);
+                    }
+                }
+            }
+            return Array.from(results);
+        }
+        isHashLike(value) {
+            // Hash-like: alphanumeric, 5-10 chars, contains both letters and digits
+            return /^[a-zA-Z0-9]{5,10}$/.test(value)
+                && /[a-zA-Z]/.test(value)
+                && /[0-9]/.test(value);
+        }
         isSafeInputType(type) {
             // Don't capture values for sensitive input types
             const sensitiveTypes = ['password', 'email', 'tel', 'credit-card-number'];
@@ -1536,6 +1602,20 @@
             // This handles cached remote options or local options with autocapture enabled
             this.startAutocaptureIfEnabled(initialEffectiveOptions);
         }
+        resolvePageviewOptions(autoTrackPageviews, frameworkHandlesPageviews) {
+            if (autoTrackPageviews === false || frameworkHandlesPageviews) {
+                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 {
@@ -1550,39 +1630,50 @@
             }
             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, effectiveOptions._frameworkHandlesPageviews)
+                : { 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();
@@ -1602,13 +1693,13 @@
             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, effectiveOptions._frameworkHandlesPageviews);
                 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();
@@ -1633,21 +1724,23 @@
                 this.autocaptureTracker.stop();
                 this.autocaptureStarted = false;
             }
-            const autoTrackPageviews = effectiveOptions.autoTrackPageviews !== false;
+            const { enabled: autoTrackPageviews, trackSpaPageviews, captureInitialPageview } = this.resolvePageviewOptions(effectiveOptions.autoTrackPageviews, effectiveOptions._frameworkHandlesPageviews);
             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();
         }
@@ -1657,6 +1750,7 @@
         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();
@@ -1666,7 +1760,16 @@
             this.client.destroy();
         }
     }
+    /** Create and return a new JourniumAnalytics instance for the given config. */
     const init = (config) => {
+        var _a;
+        // Set SDK version if not already set by a framework SDK (React, Next.js, Angular)
+        if (!((_a = config.options) === null || _a === void 0 ? void 0 : _a._sdkVersion)) {
+            config = {
+                ...config,
+                options: { ...config.options, _sdkVersion: SDK_VERSION },
+            };
+        }
         return new JourniumAnalytics(config);
     };