@v-tilt/browser 1.0.10 → 1.0.11

package/lib/utils/index.d.ts

@@ -23,3 +23,24 @@ export declare function each<T>(obj: T[] | Record<string, T> | null | undefined,
  * This properly implements the default options for passive event listeners
  */
 export declare function addEventListener(element: Window | Document | Element | undefined, event: string, callback: EventListener, options?: AddEventListenerOptions): void;
+/**
+ * Extend object with properties from another object
+ */
+export declare function extend<T extends Record<string, any>>(target: T, source: Record<string, any> | null | undefined): T;
+/**
+ * Extend array with additional items
+ * Mutates the base array and returns it (matches PostHog's behavior)
+ */
+export declare function extendArray<T>(base: T[], ...additional: T[][]): T[];
+/**
+ * Strip properties with empty values (null, undefined, empty string)
+ */
+export declare function stripEmptyProperties<T extends Record<string, any>>(obj: T): Partial<T>;
+/**
+ * Strip leading dollar sign from string
+ */
+export declare function stripLeadingDollar(str: string): string;
+/**
+ * Check if value is null
+ */
+export declare function isNull(value: any): boolean;

package/lib/utils/index.js

@@ -6,6 +6,11 @@ exports.isValidPayload = isValidPayload;
 exports.isTestEnvironment = isTestEnvironment;
 exports.each = each;
 exports.addEventListener = addEventListener;
+exports.extend = extend;
+exports.extendArray = extendArray;
+exports.stripEmptyProperties = stripEmptyProperties;
+exports.stripLeadingDollar = stripLeadingDollar;
+exports.isNull = isNull;
 /**
  * Generate uuid to identify the session. Random, not data-derived
  */
@@ -74,3 +79,56 @@ function addEventListener(element, event, callback, options) {
     const { capture = false, passive = true } = options !== null && options !== void 0 ? options : {};
     element === null || element === void 0 ? void 0 : element.addEventListener(event, callback, { capture, passive });
 }
+/**
+ * Extend object with properties from another object
+ */
+function extend(target, source) {
+    if (!source) {
+        return target;
+    }
+    for (const key in source) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+            target[key] = source[key];
+        }
+    }
+    return target;
+}
+/**
+ * Extend array with additional items
+ * Mutates the base array and returns it (matches PostHog's behavior)
+ */
+function extendArray(base, ...additional) {
+    for (const arr of additional) {
+        for (const item of arr) {
+            base.push(item);
+        }
+    }
+    return base;
+}
+/**
+ * Strip properties with empty values (null, undefined, empty string)
+ */
+function stripEmptyProperties(obj) {
+    const result = {};
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            const value = obj[key];
+            if (value !== null && value !== undefined && value !== '') {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Strip leading dollar sign from string
+ */
+function stripLeadingDollar(str) {
+    return str.startsWith('$') ? str.substring(1) : str;
+}
+/**
+ * Check if value is null
+ */
+function isNull(value) {
+    return value === null;
+}

package/lib/utils/request-utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Request utilities
+ * Functions for parsing URLs, query parameters, and masking sensitive data
+ */
+/**
+ * Convert string URL to HTMLAnchorElement for parsing
+ * IE11 doesn't support `new URL`, so we use anchor element
+ */
+export declare function convertToURL(url: string): HTMLAnchorElement | null;
+/**
+ * Get query parameter from URL
+ */
+export declare function getQueryParam(url: string, param: string): string;
+/**
+ * Mask query parameters in URL
+ */
+export declare function maskQueryParams<T extends string | undefined>(url: T, maskedParams: string[] | undefined, mask: string): T extends string ? string : undefined;

package/lib/utils/request-utils.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Request utilities
+ * Functions for parsing URLs, query parameters, and masking sensitive data
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertToURL = convertToURL;
+exports.getQueryParam = getQueryParam;
+exports.maskQueryParams = maskQueryParams;
+const globals_1 = require("./globals");
+/**
+ * Convert string URL to HTMLAnchorElement for parsing
+ * IE11 doesn't support `new URL`, so we use anchor element
+ */
+function convertToURL(url) {
+    if (!globals_1.document) {
+        return null;
+    }
+    const anchor = globals_1.document.createElement('a');
+    anchor.href = url;
+    return anchor;
+}
+/**
+ * Get query parameter from URL
+ */
+function getQueryParam(url, param) {
+    const withoutHash = url.split('#')[0] || '';
+    const queryParams = withoutHash.split(/\?(.*)/)[1] || '';
+    const cleanedQueryParams = queryParams.replace(/^\?+/g, '');
+    const queryParts = cleanedQueryParams.split('&');
+    for (let i = 0; i < queryParts.length; i++) {
+        const parts = queryParts[i].split('=');
+        if (parts[0] === param) {
+            if (parts.length < 2) {
+                return '';
+            }
+            let result = parts[1];
+            try {
+                result = decodeURIComponent(result);
+            }
+            catch (_a) {
+                // Skip decoding for malformed query param
+            }
+            return result.replace(/\+/g, ' ');
+        }
+    }
+    return '';
+}
+/**
+ * Mask query parameters in URL
+ */
+function maskQueryParams(url, maskedParams, mask) {
+    if (!url || !maskedParams || !maskedParams.length) {
+        return url;
+    }
+    const splitHash = url.split('#');
+    const withoutHash = splitHash[0] || '';
+    const hash = splitHash[1];
+    const splitQuery = withoutHash.split('?');
+    const queryString = splitQuery[1];
+    const urlWithoutQueryAndHash = splitQuery[0];
+    const queryParts = (queryString || '').split('&');
+    const paramStrings = [];
+    for (let i = 0; i < queryParts.length; i++) {
+        const parts = queryParts[i].split('=');
+        const key = parts[0];
+        const value = parts.slice(1).join('=');
+        if (maskedParams.indexOf(key) !== -1) {
+            paramStrings.push(key + '=' + mask);
+        }
+        else if (key) {
+            paramStrings.push(key + (value ? '=' + value : ''));
+        }
+    }
+    const newQueryString = paramStrings.join('&');
+    const newUrl = urlWithoutQueryAndHash + (newQueryString ? '?' + newQueryString : '') + (hash ? '#' + hash : '');
+    return newUrl;
+}

package/lib/vtilt.d.ts

@@ -86,7 +86,8 @@ export declare class VTilt {
     /**
      * Capture an event
      * Automatically adds common properties to all events
-     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser_language, etc.)
+     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser, $os, $device, $timezone, etc.)
+     * Only properties in EVENT_TO_PERSON_PROPERTIES are copied to person properties
      * Also adds title property for $pageview events only
      *
      * @param name - Event name

package/lib/vtilt.js

@@ -93,6 +93,9 @@ class VTilt {
             name: name,
         });
         this.__loaded = true;
+        // Set initial person info: stores referrer and URL on first visit
+        const fullConfig = this.configManager.getConfig();
+        this.userManager.set_initial_person_info(fullConfig.mask_personal_data_properties, fullConfig.custom_personal_data_properties);
         // Initialize history autocapture
         this.historyAutocapture = new history_autocapture_1.HistoryAutocapture(this);
         this.historyAutocapture.startIfEnabled();
@@ -204,7 +207,8 @@ class VTilt {
     /**
      * Capture an event
      * Automatically adds common properties to all events
-     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser_language, etc.)
+     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser, $os, $device, $timezone, etc.)
+     * Only properties in EVENT_TO_PERSON_PROPERTIES are copied to person properties
      * Also adds title property for $pageview events only
      *
      * @param name - Event name
@@ -221,11 +225,14 @@ class VTilt {
         }
         const url = this.buildUrl();
         // Add properties to all events
-        // This includes: $current_url, $host, $pathname, $referrer, $referring_domain, $browser_language, etc.
+        // This includes: $current_url, $host, $pathname, $referrer, $referring_domain, $browser, $os, $device, $timezone, etc.
+        // (Only properties in EVENT_TO_PERSON_PROPERTIES are copied to person properties)
         const eventProperties = (0, event_utils_1.getEventProperties)();
         // Get person properties (includes $device_id and other user properties)
         // These are automatically included in all events
         const personProperties = this.userManager.getUserProperties();
+        // Get initial props: $initial_* properties from stored initial person info
+        const initialProps = this.userManager.get_initial_props();
         // Get session and window IDs
         // Both methods ensure IDs always exist (generate if needed)
         const session_id = this.sessionManager.getSessionId();
@@ -234,6 +241,17 @@ class VTilt {
         // This allows linking events with different distinct_ids that share the same anonymous_id
         // This is especially important for handling race conditions when $identify events arrive
         const anonymousId = this.userManager.getAnonymousId();
+        // Build $set and $set_once from initial props
+        // Initial props are added to $set_once (only first time, preserves first values)
+        // Regular event properties that match EVENT_TO_PERSON_PROPERTIES will be added to $set by server
+        const setOnce = {};
+        if (Object.keys(initialProps).length > 0) {
+            Object.assign(setOnce, initialProps);
+        }
+        // Merge with user-provided $set_once if present
+        if (payload.$set_once) {
+            Object.assign(setOnce, payload.$set_once);
+        }
         const enrichedPayload = {
             ...eventProperties, // Base properties for all events
             ...personProperties, // Person properties (includes $device_id)
@@ -242,6 +260,10 @@ class VTilt {
             // Always include $anon_distinct_id for identity linking (even for identified users)
             // This allows the server to merge identities proactively when events arrive out of order
             ...(anonymousId ? { $anon_distinct_id: anonymousId } : {}),
+            // Add $set_once with initial props
+            ...(Object.keys(setOnce).length > 0 ? { $set_once: setOnce } : {}),
+            // Merge user-provided $set if present
+            ...(payload.$set ? { $set: payload.$set } : {}),
             ...payload, // User-provided payload (can override base and person properties)
         };
         // Add title only to $pageview events

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@v-tilt/browser",
-  "version": "1.0.10",
-  "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.11",
+  "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
+    }
+  }
+}