@journium/js 1.2.2 → 1.3.0

package/dist/AutocaptureTracker.d.ts

@@ -27,6 +27,8 @@ export declare class AutocaptureTracker {
     private getElementType;
     private getElementText;
     private getElementsChain;
+    private extractSemanticClasses;
+    private isHashLike;
     private isSafeInputType;
 }
 //# sourceMappingURL=AutocaptureTracker.d.ts.map

package/dist/AutocaptureTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AutocaptureTracker.d.ts","sourceRoot":"","sources":["../src/AutocaptureTracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAa,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,QAAQ,CAAkB;gBAEtB,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,kBAAuB;IAcpE;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IA0BhD,KAAK,IAAI,IAAI;IAwBb,IAAI,IAAI,IAAI;IAcZ,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,wBAAwB;IAuBhC,OAAO,CAAC,mBAAmB;IA2B3B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,oBAAoB;IAiE5B,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,gBAAgB;IAqFxB,OAAO,CAAC,eAAe;CAKxB"}
+{"version":3,"file":"AutocaptureTracker.d.ts","sourceRoot":"","sources":["../src/AutocaptureTracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAa,kBAAkB,EAA6B,MAAM,gBAAgB,CAAC;AAE1F;;GAEG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,QAAQ,CAAkB;gBAEtB,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,kBAAuB;IAgBpE;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IA4BhD,KAAK,IAAI,IAAI;IAwBb,IAAI,IAAI,IAAI;IAcZ,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,qBAAqB;IAgB7B,OAAO,CAAC,qBAAqB;IAgB7B,OAAO,CAAC,wBAAwB;IAuBhC,OAAO,CAAC,mBAAmB;IA2B3B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,oBAAoB;IAoG5B,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,gBAAgB;IAqFxB,OAAO,CAAC,sBAAsB;IA0B9B,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,eAAe;CAKxB"}

package/dist/JourniumAnalytics.d.ts

@@ -7,12 +7,23 @@ export declare class JourniumAnalytics {
     private autocaptureStarted;
     private unsubscribeOptionsChange?;
     constructor(config: JourniumConfig);
+    private resolvePageviewOptions;
     private resolveAutocaptureOptions;
+    /** Track a custom event with optional properties. */
     track(event: string, properties?: Record<string, unknown>): void;
+    /** Associate the current session with a known user identity and optional attributes. */
     identify(distinctId: string, attributes?: Record<string, unknown>): void;
+    /** Clear the current identity, starting a new anonymous session. */
     reset(): void;
+    /** Manually capture a $pageview event with optional custom properties. */
     capturePageview(properties?: Record<string, unknown>): void;
+    /**
+     * 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(): void;
+    /** Stop autocapture — pauses pageview tracking and DOM event capture. */
     stopAutocapture(): void;
     /**
      * Automatically start autocapture if enabled in options
@@ -23,14 +34,18 @@ export declare class JourniumAnalytics {
      * Handle effective options change (e.g., when remote options are fetched)
      */
     private handleOptionsChange;
+    /** Flush all queued events to the ingestion endpoint immediately. */
     flush(): Promise<void>;
+    /** Return the currently active options (merged local + remote config). */
     getEffectiveOptions(): JourniumLocalOptions;
     /**
      * Register a callback to be notified when effective options change
      */
     onOptionsChange(callback: (options: JourniumLocalOptions) => void): () => void;
+    /** Tear down the analytics instance: stop all tracking, flush pending events, and release resources. */
     destroy(): void;
 }
+/** Create and return a new JourniumAnalytics instance for the given config. */
 export declare const init: (config: JourniumConfig) => JourniumAnalytics;
 declare const _default: {
     init: (config: JourniumConfig) => JourniumAnalytics;

package/dist/JourniumAnalytics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JourniumAnalytics.d.ts","sourceRoot":"","sources":["../src/JourniumAnalytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAsB,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAK1F,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,wBAAwB,CAAC,CAAa;gBAElC,MAAM,EAAE,cAAc;IAqBlC,OAAO,CAAC,yBAAyB;IAiBjC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIxE,KAAK,IAAI,IAAI;IAIb,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,gBAAgB,IAAI,IAAI;IA4BxB,eAAe,IAAI,IAAI;IAMvB;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAkCjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA+BrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,mBAAmB;IAInB;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IAI9E,OAAO,IAAI,IAAI;CAQhB;AAED,eAAO,MAAM,IAAI,WAAY,cAAc,KAAG,iBAE7C,CAAC;;mBAF2B,cAAc,KAAG,iBAAiB;;AAI/D,wBAAwB"}
+{"version":3,"file":"JourniumAnalytics.d.ts","sourceRoot":"","sources":["../src/JourniumAnalytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAiD,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAMrH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,wBAAwB,CAAC,CAAa;gBAElC,MAAM,EAAE,cAAc;IAqBlC,OAAO,CAAC,sBAAsB;IAsB9B,OAAO,CAAC,yBAAyB;IAiBjC,qDAAqD;IACrD,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhE,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIxE,oEAAoE;IACpE,KAAK,IAAI,IAAI;IAIb,0EAA0E;IAC1E,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D;;;;OAIG;IACH,gBAAgB,IAAI,IAAI;IA6BxB,yEAAyE;IACzE,eAAe,IAAI,IAAI;IAMvB;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAoCjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiC3B,qEAAqE;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,0EAA0E;IAC1E,mBAAmB;IAInB;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IAI9E,wGAAwG;IACxG,OAAO,IAAI,IAAI;CAQhB;AAED,+EAA+E;AAC/E,eAAO,MAAM,IAAI,GAAI,QAAQ,cAAc,KAAG,iBAS7C,CAAC;;mBAT2B,cAAc,KAAG,iBAAiB;;AAW/D,wBAAwB"}

package/dist/PageviewTracker.d.ts

@@ -1,3 +1,4 @@
+import { PageviewProperties } from '@journium/core';
 import { JourniumClient } from './JourniumClient';
 export declare class PageviewTracker {
     private client;
@@ -6,13 +7,15 @@ export declare class PageviewTracker {
     private originalReplaceState;
     private popStateHandler;
     constructor(client: JourniumClient);
-    capturePageview(customProperties?: Record<string, unknown>): void;
+    capturePageview(customProperties?: PageviewProperties): void;
     /**
      * 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?: boolean): void;
+    startAutoPageviewTracking(captureInitialPageview?: boolean, patchHistory?: boolean): void;
     /**
      * Stop automatic autocapture for pageviews
      * @returns void

package/dist/PageviewTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PageviewTracker.d.ts","sourceRoot":"","sources":["../src/PageviewTracker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,iBAAiB,CAAgD;IACzE,OAAO,CAAC,oBAAoB,CAAmD;IAC/E,OAAO,CAAC,eAAe,CAA6B;gBAExC,MAAM,EAAE,cAAc;IAIlC,eAAe,CAAC,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAkBrE;;;;OAIG;IACH,yBAAyB,CAAC,sBAAsB,GAAE,OAAc,GAAG,IAAI;IA4BvE;;;OAGG;IACH,eAAe,IAAI,IAAI;CAmBxB"}
+{"version":3,"file":"PageviewTracker.d.ts","sourceRoot":"","sources":["../src/PageviewTracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA4C,MAAM,gBAAgB,CAAC;AAC9F,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,iBAAiB,CAAgD;IACzE,OAAO,CAAC,oBAAoB,CAAmD;IAC/E,OAAO,CAAC,eAAe,CAA6B;gBAExC,MAAM,EAAE,cAAc;IAIlC,eAAe,CAAC,gBAAgB,GAAE,kBAAuB,GAAG,IAAI;IAkBhE;;;;;;OAMG;IACH,yBAAyB,CAAC,sBAAsB,GAAE,OAAc,EAAE,YAAY,GAAE,OAAc,GAAG,IAAI;IA8BrG;;;OAGG;IACH,eAAe,IAAI,IAAI;CAmBxB"}

package/dist/index.cjs

@@ -1,5 +1,8 @@
 '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
  *
@@ -940,6 +943,7 @@ class JourniumClient {
         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 {
@@ -950,7 +954,7 @@ class JourniumClient {
             $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,
         };
@@ -1091,7 +1095,7 @@ class PageviewTracker {
             $host: url.host,
             $pathname: url.pathname,
             $search: url.search,
-            $title: getPageTitle(),
+            $page_title: getPageTitle(),
             $referrer: getReferrer(),
             ...customProperties,
         };
@@ -1102,28 +1106,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
@@ -1164,6 +1171,8 @@ class AutocaptureTracker {
             ignoreClasses: ['journium-ignore'],
             ignoreElements: ['script', 'style', 'noscript'],
             captureContentText: true,
+            dataAttributePrefixes: ['jrnm-'],
+            dataAttributeNames: ['data-testid', 'data-track'],
             ...options,
         };
     }
@@ -1185,6 +1194,8 @@ class AutocaptureTracker {
             ignoreClasses: ['journium-ignore'],
             ignoreElements: ['script', 'style', 'noscript'],
             captureContentText: true,
+            dataAttributePrefixes: ['jrnm-'],
+            dataAttributeNames: ['data-testid', 'data-track'],
             ...options,
         };
         // Restart if it was active before
@@ -1227,10 +1238,7 @@ class AutocaptureTracker {
                 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);
@@ -1242,10 +1250,7 @@ class AutocaptureTracker {
                 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);
@@ -1257,10 +1262,7 @@ class AutocaptureTracker {
                 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);
@@ -1313,6 +1315,7 @@ class AutocaptureTracker {
     }
     getElementProperties(element, eventType) {
         const properties = {
+            $event_type: eventType,
             $element_tag: element.tagName.toLowerCase(),
             $element_type: this.getElementType(element),
         };
@@ -1322,6 +1325,7 @@ class AutocaptureTracker {
         }
         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'];
@@ -1331,6 +1335,33 @@ class AutocaptureTracker {
                 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);
@@ -1360,10 +1391,13 @@ class AutocaptureTracker {
                 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) {
@@ -1512,6 +1546,38 @@ class AutocaptureTracker {
             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'];
@@ -1538,6 +1604,20 @@ class JourniumAnalytics {
         // 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 {
@@ -1552,39 +1632,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, 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();
@@ -1604,13 +1695,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, 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();
@@ -1635,21 +1726,23 @@ class JourniumAnalytics {
             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();
     }
@@ -1659,6 +1752,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();
@@ -1668,7 +1762,16 @@ class JourniumAnalytics {
         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);
 };