@v-tilt/browser 1.0.6 → 1.0.7

package/lib/vtilt.js

@@ -6,15 +6,14 @@ exports.init_from_snippet = init_from_snippet;
 const config_1 = require("./config");
 const tracking_1 = require("./tracking");
 const web_vitals_1 = require("./web-vitals");
+const history_autocapture_1 = require("./extensions/history-autocapture");
 const utils_1 = require("./utils");
-const patch_1 = require("./utils/patch");
 const globals_1 = require("./utils/globals");
 // Helper to check if value is an array
 const isArray = Array.isArray;
 class VTilt {
     constructor(config = {}) {
-        this.initialized = false;
-        this._lastPathname = "";
+        this.__loaded = false; // Matches snippet's window.vt.__loaded check
         this._initialPageviewCaptured = false;
         this._visibilityStateListener = null;
         this.configManager = new config_1.ConfigManager(config);
@@ -22,19 +21,89 @@ class VTilt {
         this.webVitalsManager = new web_vitals_1.WebVitalsManager(this.configManager.getConfig(), this.trackingManager);
     }
     /**
-     * Initialize VTilt tracking
+     * Initializes a new instance of the VTilt tracking object.
+     *
+     * @remarks
+     * All new instances are added to the main vt object as sub properties (such as
+     * `vt.library_name`) and also returned by this function.
+     *
+     * @example
+     * ```js
+     * // basic initialization
+     * vt.init('<project_id>', {
+     *     api_host: '<client_api_host>'
+     * })
+     * ```
+     *
+     * @example
+     * ```js
+     * // multiple instances
+     * vt.init('<project_id>', {}, 'project1')
+     * vt.init('<project_id>', {}, 'project2')
+     * ```
+     *
+     * @public
+     *
+     * @param projectId - Your VTilt project ID
+     * @param config - A dictionary of config options to override
+     * @param name - The name for the new VTilt instance that you want created
+     *
+     * @returns The newly initialized VTilt instance
      */
-    init() {
-        if (this.initialized) {
-            return;
+    init(projectId, config, name) {
+        var _a;
+        if (!name || name === PRIMARY_INSTANCE_NAME) {
+            // This means we are initializing the primary instance (i.e. this)
+            return this._init(projectId, config, name);
         }
-        // Only initialize in browser environment (not SSR)
-        // This prevents errors when init() is called during Next.js server-side rendering
-        if (!globals_1.window || !globals_1.document) {
-            return;
+        else {
+            const namedVTilt = (_a = instances[name]) !== null && _a !== void 0 ? _a : new VTilt();
+            namedVTilt._init(projectId, config, name);
+            instances[name] = namedVTilt;
+            // Add as a property to the primary instance (this isn't type-safe but its how it was always done)
+            instances[PRIMARY_INSTANCE_NAME][name] = namedVTilt;
+            return namedVTilt;
         }
-        this.setupPageTracking();
-        this.initialized = true;
+    }
+    /**
+     * Handles the actual initialization logic for a VTilt instance.
+     * This internal method should only be called by `init()`.
+     * Follows the PostHog convention of using a private `_init()` method for instance setup.
+     */
+    _init(projectId, config = {}, name) {
+        // Guard: prevent re-initialization (matches snippet's __loaded check)
+        if (this.__loaded) {
+            console.warn("vTilt: You have already initialized vTilt! Re-initializing is a no-op");
+            return this;
+        }
+        // Update config with projectId, token, and name (PostHog-style)
+        this.updateConfig({
+            ...config,
+            projectId: projectId || config.projectId,
+            name: name,
+        });
+        this.__loaded = true;
+        // Initialize history autocapture (PostHog-style)
+        this.historyAutocapture = new history_autocapture_1.HistoryAutocapture(this);
+        this.historyAutocapture.startIfEnabled();
+        // Capture initial pageview (with visibility check)
+        this._captureInitialPageview();
+        return this;
+    }
+    /**
+     * Returns a string representation of the instance name (PostHog-style)
+     * Used for debugging and logging
+     *
+     * @internal
+     */
+    toString() {
+        var _a;
+        const config = this.configManager.getConfig();
+        let name = (_a = config.name) !== null && _a !== void 0 ? _a : PRIMARY_INSTANCE_NAME;
+        if (name !== PRIMARY_INSTANCE_NAME) {
+            name = PRIMARY_INSTANCE_NAME + "." + name;
+        }
+        return name;
     }
     /**
      * Track a custom event
@@ -142,51 +211,6 @@ class VTilt {
     createAlias(alias, original) {
         this.trackingManager.createAlias(alias, original);
     }
-    /**
-     * Setup page tracking with history API support
-     * Based on PostHog's setupHistoryEventTracking implementation
-     */
-    setupPageTracking() {
-        var _a, _b;
-        // Only setup page tracking in browser environment (not SSR)
-        if (!globals_1.window || !globals_1.document || !globals_1.location) {
-            return;
-        }
-        // Initialize last pathname
-        this._lastPathname = globals_1.location.pathname || "";
-        // Capture initial pageview (with visibility check)
-        this._captureInitialPageview();
-        // Track hash changes
-        (0, utils_1.addEventListener)(globals_1.window, "hashchange", () => {
-            this._capturePageview("hashchange");
-        });
-        // Track history API changes using patch (PostHog-style)
-        if (globals_1.window.history) {
-            // Old fashioned, we could also use arrow functions but I think the closure for a patch is more reliable
-            // eslint-disable-next-line @typescript-eslint/no-this-alias
-            const self = this;
-            // Only patch if not already wrapped
-            if (!((_a = globals_1.window.history.pushState) === null || _a === void 0 ? void 0 : _a.__vtilt_wrapped__)) {
-                (0, patch_1.patch)(globals_1.window.history, "pushState", (originalPushState) => {
-                    return function patchedPushState(state, title, url) {
-                        originalPushState.call(this, state, title, url);
-                        self._capturePageview("pushState");
-                    };
-                });
-            }
-            // Only patch if not already wrapped
-            if (!((_b = globals_1.window.history.replaceState) === null || _b === void 0 ? void 0 : _b.__vtilt_wrapped__)) {
-                (0, patch_1.patch)(globals_1.window.history, "replaceState", (originalReplaceState) => {
-                    return function patchedReplaceState(state, title, url) {
-                        originalReplaceState.call(this, state, title, url);
-                        self._capturePageview("replaceState");
-                    };
-                });
-            }
-            // For popstate we need to listen to the event instead of overriding a method
-            this._setupPopstateListener();
-        }
-    }
     /**
      * Capture initial pageview with visibility check
      * Based on PostHog's _captureInitialPageview implementation
@@ -211,7 +235,19 @@ class VTilt {
         // Extra check here to guarantee we only ever trigger a single initial pageview event
         if (!this._initialPageviewCaptured) {
             this._initialPageviewCaptured = true;
-            this._capturePageview("initial_load");
+            // Wait a bit for SPA routers (PostHog-style delay)
+            setTimeout(() => {
+                // Double-check we're still in browser environment (defensive check)
+                if (!globals_1.document || !globals_1.location) {
+                    return;
+                }
+                // Note: $current_url, $host, $pathname, $referrer, $referring_domain, title
+                // are automatically added by sendEvent() for all events (title only for $pageview)
+                const payload = {
+                    navigation_type: "initial_load",
+                };
+                this.trackingManager.sendEvent("$pageview", payload);
+            }, 300);
             // After we've captured the initial pageview, we can remove the listener
             if (this._visibilityStateListener) {
                 globals_1.document.removeEventListener("visibilitychange", this._visibilityStateListener);
@@ -219,39 +255,6 @@ class VTilt {
             }
         }
     }
-    /**
-     * Capture pageview event for navigation changes
-     * Based on PostHog's captureNavigationEvent implementation
-     */
-    _capturePageview(navigationType) {
-        if (!globals_1.window || !globals_1.location) {
-            return;
-        }
-        const currentPathname = globals_1.location.pathname || "";
-        // Only capture pageview if the pathname has changed (or it's the initial load)
-        if (navigationType === "initial_load" ||
-            currentPathname !== this._lastPathname) {
-            this.trackingManager.trackPageHit(navigationType);
-            this._lastPathname = currentPathname;
-        }
-    }
-    /**
-     * Setup popstate listener for browser back/forward navigation
-     */
-    _setupPopstateListener() {
-        if (this._popstateListener || !globals_1.window) {
-            return;
-        }
-        const handler = () => {
-            this._capturePageview("popstate");
-        };
-        (0, utils_1.addEventListener)(globals_1.window, "popstate", handler);
-        this._popstateListener = () => {
-            if (globals_1.window) {
-                globals_1.window.removeEventListener("popstate", handler);
-            }
-        };
-    }
     /**
      * Get current configuration
      */
@@ -274,11 +277,11 @@ class VTilt {
         this.webVitalsManager = new web_vitals_1.WebVitalsManager(this.configManager.getConfig(), this.trackingManager);
     }
     /**
-     * _execute_array() deals with processing any VTilt function
-     * calls that were called before the VTilt library was loaded
+     * _execute_array() deals with processing any vTilt function
+     * calls that were called before the vTilt library was loaded
      * (and are thus stored in an array so they can be called later)
      *
-     * Note: we fire off all the VTilt function calls BEFORE we fire off
+     * Note: we fire off all the vTilt function calls BEFORE we fire off
      * tracking calls. This is so identify/setUserProperties/updateConfig calls
      * can properly modify early tracking calls.
      *
@@ -297,7 +300,7 @@ class VTilt {
                         this[methodName](...args);
                     }
                     catch (error) {
-                        console.error(`VTilt: Error executing queued call ${methodName}:`, error);
+                        console.error(`vTilt: Error executing queued call ${methodName}:`, error);
                     }
                 }
             }
@@ -319,7 +322,7 @@ class VTilt {
 }
 exports.VTilt = VTilt;
 const instances = {};
-const PRIMARY_INSTANCE_NAME = "vTilt";
+const PRIMARY_INSTANCE_NAME = "vt";
 // Browser support detection for request queuing
 // IE<10 does not support cross-origin XHR's but script tags
 // with defer won't block window.onload; ENQUEUE_REQUESTS
@@ -370,15 +373,15 @@ const add_dom_loaded_handler = function () {
         return;
     }
     // Only IE6-8 don't support `document.addEventListener` and we don't support them
-    // so let's simply log an error stating VTilt couldn't be initialized
+    // so let's simply log an error stating vTilt couldn't be initialized
     // We're checking for `window` to avoid erroring out on a SSR context
     if (globals_1.window) {
-        console.error("Browser doesn't support `document.addEventListener` so VTilt couldn't be initialized");
+        console.error("Browser doesn't support `document.addEventListener` so vTilt couldn't be initialized");
     }
 };
 /**
- * Initialize VTilt as a module (similar to PostHog's init_as_module)
- * Returns an uninitialized VTilt instance that the user must call init() on
+ * Initialize vTilt as a module (similar to PostHog's init_as_module)
+ * Returns an uninitialized vTilt instance that the user must call init() on
  */
 function init_as_module() {
     const vTiltMain = (instances[PRIMARY_INSTANCE_NAME] = new VTilt());
@@ -386,7 +389,7 @@ function init_as_module() {
     return vTiltMain;
 }
 /**
- * Initialize VTilt from snippet (similar to PostHog's init_from_snippet)
+ * Initialize vTilt from snippet (similar to PostHog's init_from_snippet)
  * Processes queued calls from the snippet stub and replaces it with real instance
  *
  * The snippet uses some clever tricks to allow deferred loading of array.js (this code)
@@ -416,58 +419,49 @@ function init_as_module() {
  * ]
  */
 function init_from_snippet() {
+    const vTiltMain = (instances[PRIMARY_INSTANCE_NAME] = new VTilt());
     const snippetVT = globals_1.assignableWindow["vt"];
-    if (!snippetVT || !isArray(snippetVT)) {
-        add_dom_loaded_handler();
-        return;
-    }
-    // Process all init calls from the queue
-    const initQueue = snippetVT._i;
-    if (isArray(initQueue) && initQueue.length > 0) {
-        (0, utils_1.each)(initQueue, function (item) {
-            if (!item || !isArray(item)) {
-                return;
-            }
-            const projectId = item[0];
-            const config = item[1] || {};
-            const name = item[2] || "vt";
-            // Build init config with projectId and token
-            const initConfig = {
-                ...config,
-                projectId: projectId || config.projectId,
-                token: config.token,
-            };
-            // Warn if required fields are missing (but allow instance creation like PostHog)
-            if (!initConfig.projectId || !initConfig.token) {
-                console.warn("VTilt: init() called without required projectId or token. " +
-                    "Tracking will be disabled until these are provided via updateConfig().", {
-                    projectId: initConfig.projectId || "missing",
-                    token: initConfig.token ? "present" : "missing",
-                });
-            }
-            // Create and initialize instance (even if config is incomplete)
-            // Validation will happen in tracking methods when events are sent
-            const instance = new VTilt(initConfig);
-            instance.init();
-            // Store instance
-            instances[name] = instance;
-            // Set as primary instance if it's the default name
-            if (name === "vt" || name === PRIMARY_INSTANCE_NAME) {
-                instances[PRIMARY_INSTANCE_NAME] = instance;
-            }
-            // Add named instance as property to primary instance (for PostHog compatibility)
-            if (name !== PRIMARY_INSTANCE_NAME && instances[PRIMARY_INSTANCE_NAME]) {
-                instances[PRIMARY_INSTANCE_NAME][name] = instance;
+    if (snippetVT) {
+        /**
+         * The snippet uses some clever tricks to allow deferred loading of array.js (this code)
+         *
+         * window.vt is an array which the queue of calls made before the lib is loaded
+         * It has methods attached to it to simulate the vt object so for instance
+         *
+         * window.vt.init("projectId", {token: "token", host: "host"})
+         * window.vt.trackEvent("my-event", {foo: "bar"})
+         *
+         * ... will mean that window.vt will look like this:
+         * window.vt == [
+         *   ["trackEvent", "my-event", {foo: "bar"}]
+         * ]
+         *
+         * window.vt._i == [
+         *   ["projectId", {token: "token", host: "host"}, "vt"]
+         * ]
+         *
+         * If a name is given to the init function then the same as above is true but as a sub-property on the object:
+         *
+         * window.vt.init("projectId", {token: "token"}, "vt2")
+         * window.vt.vt2.trackEvent("my-event", {foo: "bar"})
+         *
+         * window.vt.vt2 == [
+         *   ["trackEvent", "my-event", {foo: "bar"}]
+         * ]
+         *
+         */
+        // Call all pre-loaded init calls properly
+        (0, utils_1.each)(snippetVT["_i"], function (item) {
+            if (item && isArray(item)) {
+                const instance = vTiltMain.init(item[0], item[1], item[2]);
+                const instanceSnippet = snippetVT[item[2] || "vt"] || snippetVT;
+                if (instance) {
+                    // Execute all queued calls for this instance
+                    instance._execute_array(instanceSnippet);
+                }
             }
-            // Get the snippet queue for this instance name
-            const instanceSnippet = snippetVT[name] || snippetVT;
-            // Execute all queued calls for this instance
-            instance._execute_array(instanceSnippet);
         });
     }
-    // Replace stub with main instance (if initialized)
-    if (instances[PRIMARY_INSTANCE_NAME] && globals_1.assignableWindow) {
-        globals_1.assignableWindow["vt"] = instances[PRIMARY_INSTANCE_NAME];
-    }
+    globals_1.assignableWindow["vt"] = vTiltMain;
     add_dom_loaded_handler();
 }

package/package.json

@@ -1,61 +1,60 @@
-{
-  "name": "@v-tilt/browser",
-  "version": "1.0.6",
-  "description": "vTilt browser tracking library",
-  "main": "dist/main.js",
-  "module": "dist/module.js",
-  "types": "dist/module.d.ts",
-  "files": [
-    "lib/*",
-    "dist/*"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -b && rollup -c",
-    "dev": "rollup -c -w",
-    "type-check": "tsc --noEmit",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
-    "clean": "rimraf lib dist",
-    "prepublishOnly": "pnpm run build"
-  },
-  "keywords": [
-    "analytics",
-    "tracking",
-    "web-vitals",
-    "performance"
-  ],
-  "author": "vTilt",
-  "license": "MIT",
-  "devDependencies": {
-    "@babel/preset-env": "^7.28.3",
-    "@rollup/plugin-babel": "^6.0.4",
-    "@rollup/plugin-commonjs": "^25.0.8",
-    "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^15.3.1",
-    "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^11.1.6",
-    "@types/node": "^20.10.5",
-    "@v-tilt/eslint-config": "workspace:*",
-    "eslint": "^9.0.0",
-    "rimraf": "^5.0.5",
-    "rollup": "^4.9.1",
-    "rollup-plugin-dts": "^6.2.3",
-    "rollup-plugin-terser": "^7.0.2",
-    "rollup-plugin-visualizer": "^6.0.3",
-    "typescript": "^5.3.3"
-  },
-  "dependencies": {
-    "web-vitals": "^3.5.0"
-  },
-  "peerDependencies": {
-    "web-vitals": "^3.0.0"
-  },
-  "peerDependenciesMeta": {
-    "web-vitals": {
-      "optional": true
-    }
-  }
-}
+{
+  "name": "@v-tilt/browser",
+  "version": "1.0.7",
+  "description": "vTilt browser tracking library",
+  "main": "dist/main.js",
+  "module": "dist/module.js",
+  "types": "dist/module.d.ts",
+  "files": [
+    "lib/*",
+    "dist/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "analytics",
+    "tracking",
+    "web-vitals",
+    "performance"
+  ],
+  "author": "vTilt",
+  "license": "MIT",
+  "devDependencies": {
+    "@babel/preset-env": "^7.28.3",
+    "@rollup/plugin-babel": "^6.0.4",
+    "@rollup/plugin-commonjs": "^25.0.8",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.3.1",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/node": "^20.10.5",
+    "eslint": "^9.0.0",
+    "rimraf": "^5.0.5",
+    "rollup": "^4.9.1",
+    "rollup-plugin-dts": "^6.2.3",
+    "rollup-plugin-terser": "^7.0.2",
+    "rollup-plugin-visualizer": "^6.0.3",
+    "typescript": "^5.3.3",
+    "@v-tilt/eslint-config": "1.0.0"
+  },
+  "dependencies": {
+    "web-vitals": "^3.5.0"
+  },
+  "peerDependencies": {
+    "web-vitals": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "web-vitals": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -b && rollup -c",
+    "dev": "rollup -c -w",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "clean": "rimraf lib dist"
+  }
+}

package/dist/utils.d.ts

@@ -1,21 +0,0 @@
-import { EventPayload } from './types';
-/**
- * Generate uuid to identify the session. Random, not data-derived
- */
-export declare function uuidv4(): string;
-/**
- * Validate user agent string
- */
-export declare function isValidUserAgent(userAgent: string): boolean;
-/**
- * Validate payload string
- */
-export declare function isValidPayload(payloadStr: string): boolean;
-/**
- * Try to mask PPI and potential sensible attributes
- */
-export declare function maskSuspiciousAttributes(payload: EventPayload): string;
-/**
- * Check if current environment is a test environment
- */
-export declare function isTestEnvironment(): boolean;

package/lib/utils.d.ts

@@ -1,21 +0,0 @@
-import { EventPayload } from './types';
-/**
- * Generate uuid to identify the session. Random, not data-derived
- */
-export declare function uuidv4(): string;
-/**
- * Validate user agent string
- */
-export declare function isValidUserAgent(userAgent: string): boolean;
-/**
- * Validate payload string
- */
-export declare function isValidPayload(payloadStr: string): boolean;
-/**
- * Try to mask PPI and potential sensible attributes
- */
-export declare function maskSuspiciousAttributes(payload: EventPayload): string;
-/**
- * Check if current environment is a test environment
- */
-export declare function isTestEnvironment(): boolean;

package/lib/utils.js

@@ -1,57 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.uuidv4 = uuidv4;
-exports.isValidUserAgent = isValidUserAgent;
-exports.isValidPayload = isValidPayload;
-exports.maskSuspiciousAttributes = maskSuspiciousAttributes;
-exports.isTestEnvironment = isTestEnvironment;
-const constants_1 = require("./constants");
-/**
- * Generate uuid to identify the session. Random, not data-derived
- */
-function uuidv4() {
-    return (`${1e7}-${1e3}-${4e3}-${8e3}-${1e11}`).replace(/[018]/g, (c) => (+c ^
-        (crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (+c / 4)))).toString(16));
-}
-/**
- * Validate user agent string
- */
-function isValidUserAgent(userAgent) {
-    // empty is fine
-    if (!userAgent || typeof userAgent !== 'string') {
-        return true;
-    }
-    if (userAgent.length > 500) {
-        return false;
-    }
-    return true;
-}
-/**
- * Validate payload string
- */
-function isValidPayload(payloadStr) {
-    if (!payloadStr || typeof payloadStr !== 'string') {
-        return false;
-    }
-    if (payloadStr.length < 2 || payloadStr.length > 10240) {
-        return false;
-    }
-    return true;
-}
-/**
- * Try to mask PPI and potential sensible attributes
- */
-function maskSuspiciousAttributes(payload) {
-    // Deep copy
-    let _payload = JSON.stringify(payload);
-    constants_1.ATTRIBUTES_TO_MASK.forEach((attr) => {
-        _payload = _payload.replace(new RegExp(`("${attr}"):(".+?"|\\d+)`, 'gmi'), '$1:"********"');
-    });
-    return _payload;
-}
-/**
- * Check if current environment is a test environment
- */
-function isTestEnvironment() {
-    return !!(('__nightmare' in window) || window.navigator.webdriver || ('Cypress' in window));
-}