@v-tilt/browser 1.0.5 → 1.0.7

package/lib/vtilt.js

@@ -6,31 +6,104 @@ 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 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.__loaded = false; // Matches snippet's window.vt.__loaded check
+        this._initialPageviewCaptured = false;
+        this._visibilityStateListener = null;
         this.configManager = new config_1.ConfigManager(config);
         this.trackingManager = new tracking_1.TrackingManager(this.configManager.getConfig());
         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;
+        }
+    }
+    /**
+     * 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;
         }
-        this.setupPageTracking();
-        this.initialized = true;
+        return name;
     }
     /**
      * Track a custom event
@@ -139,85 +212,47 @@ class VTilt {
         this.trackingManager.createAlias(alias, original);
     }
     /**
-     * Setup page tracking with history API support
+     * Capture initial pageview with visibility check
+     * Based on PostHog's _captureInitialPageview implementation
      */
-    setupPageTracking() {
-        // Only setup page tracking in browser environment (not SSR)
-        if (!globals_1.window || !globals_1.document) {
+    _captureInitialPageview() {
+        if (!globals_1.document) {
             return;
         }
-        // Track initial page load
-        this.trackPageHit();
-        // Track hash changes
-        globals_1.window.addEventListener("hashchange", () => this.trackPageHit());
-        // Track history API changes
-        const history = globals_1.window.history;
-        if (history.pushState) {
-            // Store original functions WITHOUT binding - we'll use .call() with proper context
-            const originalPushState = history.pushState;
-            const originalReplaceState = history.replaceState;
-            const vtiltInstance = this; // Capture VTilt instance for use in closures
-            // Override pushState - use explicit parameters and .call() to preserve 'this' context
-            Object.defineProperty(history, "pushState", {
-                value: function (state, title, url) {
-                    // Call original with proper 'this' context using .call()
-                    originalPushState.call(this, state, title, url);
-                    // Use setTimeout to ensure the page navigation completes before tracking
-                    setTimeout(() => {
-                        vtiltInstance.trackPageHit();
-                    }, 0);
-                },
-                writable: true,
-                configurable: true,
-            });
-            // Also override replaceState if it exists (Next.js uses this too)
-            if (originalReplaceState) {
-                Object.defineProperty(history, "replaceState", {
-                    value: function (state, title, url) {
-                        // Call original with proper 'this' context using .call()
-                        originalReplaceState.call(this, state, title, url);
-                        // Use setTimeout to ensure the page navigation completes before tracking
-                        setTimeout(() => {
-                            vtiltInstance.trackPageHit();
-                        }, 0);
-                    },
-                    writable: true,
-                    configurable: true,
-                });
+        // If page is not visible, add a listener to detect when the page becomes visible
+        // and trigger the pageview only then
+        // This is useful to avoid `prerender` calls from Chrome/Wordpress/SPAs
+        // that are not visible to the user
+        if (globals_1.document.visibilityState !== "visible") {
+            if (!this._visibilityStateListener) {
+                this._visibilityStateListener = () => {
+                    this._captureInitialPageview();
+                };
+                (0, utils_1.addEventListener)(globals_1.document, "visibilitychange", this._visibilityStateListener);
             }
-            globals_1.window.addEventListener("popstate", () => this.trackPageHit());
-        }
-        // Handle visibility changes for prerendered pages
-        this.setupVisibilityTracking();
-    }
-    /**
-     * Track page hit
-     */
-    trackPageHit() {
-        if ((0, utils_1.isTestEnvironment)()) {
             return;
         }
-        this.trackingManager.trackPageHit();
-    }
-    /**
-     * Setup visibility change tracking for prerendered pages
-     */
-    setupVisibilityTracking() {
-        // Only setup visibility tracking in browser environment (not SSR)
-        if (!globals_1.document) {
-            return;
-        }
-        const lastPage = null;
-        const doc = globals_1.document; // Capture document for use in callback
-        const handleVisibilityChange = () => {
-            if (!lastPage && doc.visibilityState === "visible") {
-                this.trackPageHit();
+        // Extra check here to guarantee we only ever trigger a single initial pageview event
+        if (!this._initialPageviewCaptured) {
+            this._initialPageviewCaptured = true;
+            // 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);
+                this._visibilityStateListener = null;
             }
-        };
-        // Only track if page was prerendered and is now becoming visible
-        // For normal page loads, trackPageHit() is already called in setupPageTracking()
-        if (doc.visibilityState === "prerender") {
-            doc.addEventListener("visibilitychange", handleVisibilityChange);
         }
     }
     /**
@@ -242,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.
      *
@@ -265,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);
                     }
                 }
             }
@@ -287,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
@@ -338,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());
@@ -354,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)
@@ -384,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,6 +1,6 @@
 {
   "name": "@v-tilt/browser",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "vTilt browser tracking library",
   "main": "dist/main.js",
   "module": "dist/module.js",
@@ -12,15 +12,6 @@
   "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",
@@ -38,14 +29,14 @@
     "@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"
+    "typescript": "^5.3.3",
+    "@v-tilt/eslint-config": "1.0.0"
   },
   "dependencies": {
     "web-vitals": "^3.5.0"
@@ -57,5 +48,13 @@
     "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));
-}