@v-tilt/browser 1.0.1

package/lib/utils.d.ts

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,57 @@
+"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));
+}

package/lib/vtilt.d.ts

@@ -0,0 +1,178 @@
+import { VTiltConfig, EventPayload } from "./types";
+export declare class VTilt {
+    private configManager;
+    private trackingManager;
+    private webVitalsManager;
+    private initialized;
+    constructor(config?: Partial<VTiltConfig>);
+    /**
+     * Initialize VTilt tracking
+     */
+    init(): void;
+    /**
+     * Track a custom event
+     */
+    trackEvent(name: string, payload?: EventPayload): void;
+    /**
+     * Identify a user with PostHog-style property operations
+     * Copied from PostHog's identify method signature
+     *
+     * @example
+     * ```js
+     * // Basic identify with properties
+     * vTilt.identify('user_123',
+     *   { name: 'John Doe', email: 'john@example.com' },  // $set properties
+     *   { first_login: new Date().toISOString() }         // $set_once properties
+     * )
+     * ```
+     *
+     * @example
+     * ```js
+     * // If no $set is provided, all properties are treated as $set
+     * vTilt.identify('user_123', { name: 'John Doe', email: 'john@example.com' })
+     * ```
+     */
+    identify(distinctId?: string, userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
+    /**
+     * Set user properties with PostHog-style operations
+     * Sets properties on the person profile associated with the current distinct_id
+     *
+     * @example
+     * ```js
+     * // Set properties that can be updated
+     * vTilt.setUserProperties({ name: 'John Doe', email: 'john@example.com' })
+     * ```
+     *
+     * @example
+     * ```js
+     * // Set properties with $set and $set_once operations
+     * vTilt.setUserProperties(
+     *   { name: 'John Doe', last_login: new Date().toISOString() },  // $set properties
+     *   { first_login: new Date().toISOString() }                     // $set_once properties
+     * )
+     * ```
+     *
+     * @param userPropertiesToSet Optional: Properties to set (can be updated)
+     * @param userPropertiesToSetOnce Optional: Properties to set once (preserves first value)
+     */
+    setUserProperties(userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
+    /**
+     * Reset user identity (logout)
+     * PostHog behavior: Clears all user data, generates new anonymous ID
+     *
+     * @param reset_device_id - If true, also resets device_id. Default: false
+     *
+     * @example
+     * // Reset on user logout
+     * vtilt.resetUser()
+     *
+     * @example
+     * // Reset and generate new device ID
+     * vtilt.resetUser(true)
+     */
+    resetUser(reset_device_id?: boolean): void;
+    /**
+     * Get current user identity
+     */
+    getUserIdentity(): import("./types").UserIdentity;
+    /**
+     * Get current device ID
+     */
+    getDeviceId(): string;
+    /**
+     * Get current user state
+     */
+    getUserState(): "anonymous" | "identified";
+    /**
+     * Create an alias to link two distinct IDs
+     * PostHog behavior: Links anonymous session to account on signup
+     *
+     * @param alias - A unique identifier that you want to use for this user in the future
+     * @param original - The current identifier being used for this user (optional, defaults to current distinct_id)
+     *
+     * @example
+     * // Link anonymous user to account on signup
+     * vtilt.createAlias('user_12345')
+     *
+     * @example
+     * // Explicit alias with original ID
+     * vtilt.createAlias('user_12345', 'anonymous_abc123')
+     */
+    createAlias(alias: string, original?: string): void;
+    /**
+     * Setup page tracking with history API support
+     */
+    private setupPageTracking;
+    /**
+     * Track page hit
+     */
+    private trackPageHit;
+    /**
+     * Setup visibility change tracking for prerendered pages
+     */
+    private setupVisibilityTracking;
+    /**
+     * Get current configuration
+     */
+    getConfig(): VTiltConfig;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<VTiltConfig>): void;
+    /**
+     * _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
+     * tracking calls. This is so identify/setUserProperties/updateConfig calls
+     * can properly modify early tracking calls.
+     *
+     * @param {Array} array Array of queued calls in format [methodName, ...args]
+     */
+    _execute_array(array: any[]): void;
+    /**
+     * Called when DOM is loaded - processes queued requests
+     */
+    _dom_loaded(): void;
+}
+/**
+ * Initialize VTilt as a module (similar to PostHog's init_as_module)
+ * Returns an uninitialized VTilt instance that the user must call init() on
+ */
+export declare function init_as_module(): VTilt;
+/**
+ * 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)
+ *
+ * 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"}]
+ * ]
+ */
+export declare function init_from_snippet(): void;

package/lib/vtilt.js

@@ -0,0 +1,403 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VTilt = void 0;
+exports.init_as_module = init_as_module;
+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 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.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
+     */
+    init() {
+        if (this.initialized) {
+            return;
+        }
+        this.setupPageTracking();
+        this.initialized = true;
+    }
+    /**
+     * Track a custom event
+     */
+    trackEvent(name, payload = {}) {
+        this.trackingManager.sendEvent(name, payload);
+    }
+    /**
+     * Identify a user with PostHog-style property operations
+     * Copied from PostHog's identify method signature
+     *
+     * @example
+     * ```js
+     * // Basic identify with properties
+     * vTilt.identify('user_123',
+     *   { name: 'John Doe', email: 'john@example.com' },  // $set properties
+     *   { first_login: new Date().toISOString() }         // $set_once properties
+     * )
+     * ```
+     *
+     * @example
+     * ```js
+     * // If no $set is provided, all properties are treated as $set
+     * vTilt.identify('user_123', { name: 'John Doe', email: 'john@example.com' })
+     * ```
+     */
+    identify(distinctId, userPropertiesToSet, userPropertiesToSetOnce) {
+        this.trackingManager.identify(distinctId, userPropertiesToSet, userPropertiesToSetOnce);
+    }
+    /**
+     * Set user properties with PostHog-style operations
+     * Sets properties on the person profile associated with the current distinct_id
+     *
+     * @example
+     * ```js
+     * // Set properties that can be updated
+     * vTilt.setUserProperties({ name: 'John Doe', email: 'john@example.com' })
+     * ```
+     *
+     * @example
+     * ```js
+     * // Set properties with $set and $set_once operations
+     * vTilt.setUserProperties(
+     *   { name: 'John Doe', last_login: new Date().toISOString() },  // $set properties
+     *   { first_login: new Date().toISOString() }                     // $set_once properties
+     * )
+     * ```
+     *
+     * @param userPropertiesToSet Optional: Properties to set (can be updated)
+     * @param userPropertiesToSetOnce Optional: Properties to set once (preserves first value)
+     */
+    setUserProperties(userPropertiesToSet, userPropertiesToSetOnce) {
+        this.trackingManager.setUserProperties(userPropertiesToSet, userPropertiesToSetOnce);
+    }
+    /**
+     * Reset user identity (logout)
+     * PostHog behavior: Clears all user data, generates new anonymous ID
+     *
+     * @param reset_device_id - If true, also resets device_id. Default: false
+     *
+     * @example
+     * // Reset on user logout
+     * vtilt.resetUser()
+     *
+     * @example
+     * // Reset and generate new device ID
+     * vtilt.resetUser(true)
+     */
+    resetUser(reset_device_id) {
+        this.trackingManager.resetUser(reset_device_id);
+    }
+    /**
+     * Get current user identity
+     */
+    getUserIdentity() {
+        return this.trackingManager.getUserIdentity();
+    }
+    /**
+     * Get current device ID
+     */
+    getDeviceId() {
+        return this.trackingManager.getDeviceId();
+    }
+    /**
+     * Get current user state
+     */
+    getUserState() {
+        return this.trackingManager.getUserState();
+    }
+    /**
+     * Create an alias to link two distinct IDs
+     * PostHog behavior: Links anonymous session to account on signup
+     *
+     * @param alias - A unique identifier that you want to use for this user in the future
+     * @param original - The current identifier being used for this user (optional, defaults to current distinct_id)
+     *
+     * @example
+     * // Link anonymous user to account on signup
+     * vtilt.createAlias('user_12345')
+     *
+     * @example
+     * // Explicit alias with original ID
+     * vtilt.createAlias('user_12345', 'anonymous_abc123')
+     */
+    createAlias(alias, original) {
+        this.trackingManager.createAlias(alias, original);
+    }
+    /**
+     * Setup page tracking with history API support
+     */
+    setupPageTracking() {
+        // Track initial page load
+        this.trackPageHit();
+        // Track hash changes
+        window.addEventListener("hashchange", () => this.trackPageHit());
+        // Track history API changes
+        const history = window.history;
+        if (history.pushState) {
+            const originalPushState = history.pushState;
+            history.pushState = (...args) => {
+                originalPushState.apply(this, args);
+                this.trackPageHit();
+            };
+            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() {
+        const lastPage = null;
+        const handleVisibilityChange = () => {
+            if (!lastPage && document.visibilityState === "visible") {
+                this.trackPageHit();
+            }
+        };
+        // Only track if page was prerendered and is now becoming visible
+        // For normal page loads, trackPageHit() is already called in setupPageTracking()
+        if (document.visibilityState === "prerender") {
+            document.addEventListener("visibilitychange", handleVisibilityChange);
+        }
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return this.configManager.getConfig();
+    }
+    /**
+     * Get current session ID
+     */
+    getSessionId() {
+        return this.trackingManager.getSessionId();
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(config) {
+        this.configManager.updateConfig(config);
+        // Recreate managers with new config
+        this.trackingManager = new tracking_1.TrackingManager(this.configManager.getConfig());
+        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
+     * (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
+     * tracking calls. This is so identify/setUserProperties/updateConfig calls
+     * can properly modify early tracking calls.
+     *
+     * @param {Array} array Array of queued calls in format [methodName, ...args]
+     */
+    _execute_array(array) {
+        if (!Array.isArray(array)) {
+            return;
+        }
+        array.forEach((item) => {
+            if (item && Array.isArray(item) && item.length > 0) {
+                const methodName = item[0];
+                const args = item.slice(1);
+                if (typeof this[methodName] === "function") {
+                    try {
+                        this[methodName](...args);
+                    }
+                    catch (error) {
+                        console.error(`VTilt: Error executing queued call ${methodName}:`, error);
+                    }
+                }
+            }
+        });
+    }
+    /**
+     * Called when DOM is loaded - processes queued requests
+     */
+    _dom_loaded() {
+        if (this.trackingManager) {
+            // Process all queued requests
+            this.trackingManager.__request_queue.forEach((item) => {
+                this.trackingManager._send_retriable_request(item);
+            });
+            // Clear the queue
+            this.trackingManager.__request_queue = [];
+        }
+    }
+}
+exports.VTilt = VTilt;
+const instances = {};
+const PRIMARY_INSTANCE_NAME = "vTilt";
+// 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
+// should only be true for Opera<12
+const SUPPORTS_REQUEST = typeof XMLHttpRequest !== "undefined" || typeof fetch !== "undefined";
+const userAgent = typeof window !== "undefined" ? (_a = window.navigator) === null || _a === void 0 ? void 0 : _a.userAgent : undefined;
+let ENQUEUE_REQUESTS = !SUPPORTS_REQUEST &&
+    (userAgent === null || userAgent === void 0 ? void 0 : userAgent.indexOf("MSIE")) === -1 &&
+    (userAgent === null || userAgent === void 0 ? void 0 : userAgent.indexOf("Mozilla")) === -1;
+// Expose ENQUEUE_REQUESTS to window for TrackingManager to access
+if (typeof window !== "undefined") {
+    window.__VTILT_ENQUEUE_REQUESTS = ENQUEUE_REQUESTS;
+}
+/**
+ * Add DOM loaded handler to process queued requests
+ * Similar to PostHog's add_dom_loaded_handler
+ */
+const add_dom_loaded_handler = function () {
+    // Cross browser DOM Loaded support
+    function dom_loaded_handler() {
+        // function flag since we only want to execute this once
+        if (dom_loaded_handler.done) {
+            return;
+        }
+        dom_loaded_handler.done = true;
+        // Disable request queuing now that DOM is loaded
+        ENQUEUE_REQUESTS = false;
+        if (typeof window !== "undefined") {
+            window.__VTILT_ENQUEUE_REQUESTS = false;
+        }
+        // Process queued requests for all instances
+        (0, utils_1.each)(instances, function (inst) {
+            inst._dom_loaded();
+        });
+    }
+    if (typeof document !== "undefined" &&
+        typeof document.addEventListener === "function") {
+        if (document.readyState === "complete") {
+            // Safari 4 can fire the DOMContentLoaded event before loading all
+            // external JS (including this file). you will see some copypasta
+            // on the internet that checks for 'complete' and 'loaded', but
+            // 'loaded' is an IE thing
+            dom_loaded_handler();
+        }
+        else {
+            (0, utils_1.addEventListener)(document, "DOMContentLoaded", dom_loaded_handler, {
+                capture: false,
+            });
+        }
+        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
+    // We're checking for `window` to avoid erroring out on a SSR context
+    if (typeof window !== "undefined") {
+        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
+ */
+function init_as_module() {
+    const vTiltMain = (instances[PRIMARY_INSTANCE_NAME] = new VTilt());
+    add_dom_loaded_handler();
+    return vTiltMain;
+}
+/**
+ * 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)
+ *
+ * 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"}]
+ * ]
+ */
+function init_from_snippet() {
+    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;
+            }
+            // 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];
+    }
+    add_dom_loaded_handler();
+}

package/lib/web-vitals.d.ts

@@ -0,0 +1,11 @@
+import { VTiltConfig } from "./types";
+import { TrackingManager } from "./tracking";
+export declare class WebVitalsManager {
+    private trackingManager;
+    private webVitals;
+    constructor(config: VTiltConfig, trackingManager: TrackingManager);
+    /**
+     * Initialize web vitals tracking
+     */
+    private initializeWebVitals;
+}