@v-tilt/browser 1.0.9 → 1.0.11

package/dist/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/dist/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/dist/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/constants.d.ts

@@ -7,5 +7,6 @@ export declare const DISTINCT_ID_KEY = "vt_distinct_id";
 export declare const DEVICE_ID_KEY = "vt_device_id";
 export declare const USER_PROPERTIES_KEY = "vt_user_properties";
 export declare const USER_STATE_KEY = "vt_user_state";
+export declare const INITIAL_PERSON_INFO = "$initial_person_info";
 export declare const STORAGE_METHODS: StorageMethods;
 export declare const TIMEZONES: Record<string, string>;

package/lib/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TIMEZONES = exports.STORAGE_METHODS = exports.USER_STATE_KEY = exports.USER_PROPERTIES_KEY = exports.DEVICE_ID_KEY = exports.DISTINCT_ID_KEY = exports.ANONYMOUS_ID_KEY = exports.PRIMARY_WINDOW_EXISTS_KEY = exports.WINDOW_ID_KEY = exports.STORAGE_KEY = void 0;
+exports.TIMEZONES = exports.STORAGE_METHODS = exports.INITIAL_PERSON_INFO = exports.USER_STATE_KEY = exports.USER_PROPERTIES_KEY = exports.DEVICE_ID_KEY = exports.DISTINCT_ID_KEY = exports.ANONYMOUS_ID_KEY = exports.PRIMARY_WINDOW_EXISTS_KEY = exports.WINDOW_ID_KEY = exports.STORAGE_KEY = void 0;
 exports.STORAGE_KEY = "vt_session_id";
 exports.WINDOW_ID_KEY = "vt_window_id";
 exports.PRIMARY_WINDOW_EXISTS_KEY = "vt_primary_window_exists";
@@ -9,6 +9,7 @@ exports.DISTINCT_ID_KEY = "vt_distinct_id";
 exports.DEVICE_ID_KEY = "vt_device_id";
 exports.USER_PROPERTIES_KEY = "vt_user_properties";
 exports.USER_STATE_KEY = "vt_user_state";
+exports.INITIAL_PERSON_INFO = "$initial_person_info";
 exports.STORAGE_METHODS = {
     cookie: "cookie",
     localStorage: "localStorage",

package/lib/types.d.ts

@@ -36,7 +36,7 @@ export interface EventPayload {
 export interface TrackingEvent {
     timestamp: string;
     event: string;
-    tenant_id: string;
+    project_id: string;
     domain: string;
     payload: EventPayload;
     distinct_id?: string;

package/lib/user-manager.d.ts

@@ -159,4 +159,25 @@ export declare class UserManager {
      * Remove cookie value
      */
     private removeCookieValue;
+    /**
+     * Register a value once (only if not already set)
+     * Stores properties in localStorage only if they don't already exist
+     */
+    private register_once;
+    /**
+     * Set initial person info
+     * Stores referrer and URL info on first visit for generating $initial_* properties
+     */
+    set_initial_person_info(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): void;
+    /**
+     * Get initial props
+     * Generates $initial_* properties from stored initial person info
+     * These are sent with events as $set_once to preserve first values
+     */
+    get_initial_props(): Record<string, any>;
+    /**
+     * Update referrer info
+     * Stores current referrer information if not already stored
+     */
+    update_referrer_info(): void;
 }

package/lib/user-manager.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.UserManager = void 0;
 const constants_1 = require("./constants");
 const utils_1 = require("./utils");
+const event_utils_1 = require("./utils/event-utils");
 class UserManager {
     constructor(storageMethod = "localStorage", domain) {
         this._cachedPersonProperties = null; // Cache for deduplication
@@ -64,8 +65,6 @@ class UserManager {
             return;
         }
         const previousDistinctId = this.userIdentity.distinct_id;
-        const anonymousId = this.userIdentity.anonymous_id;
-        const deviceId = this.userIdentity.device_id;
         // Register user ID
         this.userIdentity.distinct_id = newDistinctId;
         // Handle device ID if not already set
@@ -572,5 +571,70 @@ class UserManager {
         }
         document.cookie = cookieValue;
     }
+    /**
+     * Register a value once (only if not already set)
+     * Stores properties in localStorage only if they don't already exist
+     */
+    register_once(props, defaultValues) {
+        const stored = this.getStoredUserProperties();
+        let changed = false;
+        for (const key in props) {
+            if (Object.prototype.hasOwnProperty.call(props, key)) {
+                if (!(key in stored)) {
+                    stored[key] = props[key];
+                    changed = true;
+                }
+            }
+        }
+        if (defaultValues) {
+            for (const key in defaultValues) {
+                if (Object.prototype.hasOwnProperty.call(defaultValues, key)) {
+                    if (!(key in stored)) {
+                        stored[key] = defaultValues[key];
+                        changed = true;
+                    }
+                }
+            }
+        }
+        if (changed) {
+            this.setStoredUserProperties(stored);
+        }
+    }
+    /**
+     * Set initial person info
+     * Stores referrer and URL info on first visit for generating $initial_* properties
+     */
+    set_initial_person_info(maskPersonalDataProperties, customPersonalDataProperties) {
+        const stored = this.getStoredUserProperties();
+        // Check if already set (backwards compatibility check)
+        if (stored[constants_1.INITIAL_PERSON_INFO]) {
+            return;
+        }
+        const personInfo = (0, event_utils_1.getPersonInfo)(maskPersonalDataProperties, customPersonalDataProperties);
+        this.register_once({
+            [constants_1.INITIAL_PERSON_INFO]: personInfo,
+        }, undefined);
+    }
+    /**
+     * Get initial props
+     * Generates $initial_* properties from stored initial person info
+     * These are sent with events as $set_once to preserve first values
+     */
+    get_initial_props() {
+        const stored = this.getStoredUserProperties();
+        const initialPersonInfo = stored[constants_1.INITIAL_PERSON_INFO];
+        if (!initialPersonInfo) {
+            return {};
+        }
+        return (0, event_utils_1.getInitialPersonPropsFromInfo)(initialPersonInfo);
+    }
+    /**
+     * Update referrer info
+     * Stores current referrer information if not already stored
+     */
+    update_referrer_info() {
+        const referrerInfo = (0, event_utils_1.getReferrerInfo)();
+        this.register_once(referrerInfo, undefined);
+    }
 }
 exports.UserManager = UserManager;

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

@@ -1,34 +1,52 @@
 /**
- * Get browser language
- * Returns the browser's language setting (e.g., "en-US")
+ * Event utilities
+ * Functions for extracting event properties, campaign parameters, and person info
  */
-export declare function getBrowserLanguage(): string | undefined;
+export declare const PERSONAL_DATA_CAMPAIGN_PARAMS: string[];
+export declare const CAMPAIGN_PARAMS: string[];
+export declare const EVENT_TO_PERSON_PROPERTIES: string[];
+export declare const MASKED = "<masked>";
+export declare const COOKIE_CAMPAIGN_PARAMS: string[];
 /**
- * Get browser language prefix
- * Returns the language code without region (e.g., "en" from "en-US")
+ * Get campaign parameters from URL
+ * Extracts UTM and other campaign tracking parameters from current page URL
+ * Masks personal data parameters if configured
  */
+export declare function getCampaignParams(customTrackedParams?: string[], maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[] | undefined): Record<string, string>;
+export declare function getSearchInfo(): Record<string, any>;
+export declare function getBrowserLanguage(): string | undefined;
 export declare function getBrowserLanguagePrefix(): string | undefined;
+export declare function getReferrer(): string;
+export declare function getReferringDomain(): string;
 /**
- * Get referrer
- * Returns document.referrer or '$direct' if no referrer
+ * Get referrer information
+ * Returns current referrer and referring domain
  */
-export declare function getReferrer(): string;
+export declare function getReferrerInfo(): Record<string, any>;
 /**
- * Get referring domain
- * Returns the hostname of the referrer URL or '$direct' if no referrer
+ * Get person info for initial storage
+ * Extracts referrer and URL info, masks personal data if configured
+ * Returns compact format (r: referrer, u: url) for storage efficiency
  */
-export declare function getReferringDomain(): string;
+export declare function getPersonInfo(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): {
+    r: string;
+    u: string | undefined;
+};
 /**
- * Get timezone
- * Returns the timezone (e.g., "America/New_York")
+ * Convert person info to person properties
+ * Extracts referrer, URL, campaign params, and search info from stored person info
  */
-export declare function getTimezone(): string | undefined;
+export declare function getPersonPropsFromInfo(info: Record<string, any>): Record<string, any>;
 /**
- * Get timezone offset
- * Returns the timezone offset in minutes
+ * Convert person info to initial person properties
+ * Generates $initial_* properties from person info (preserves first values)
  */
+export declare function getInitialPersonPropsFromInfo(info: Record<string, any>): Record<string, any>;
+export declare function getTimezone(): string | undefined;
 export declare function getTimezoneOffset(): number | undefined;
 /**
  * Get event properties that should be added to all events
+ * Returns all event context properties (browser, device, URL, etc.) plus event metadata
+ * Note: Only properties in EVENT_TO_PERSON_PROPERTIES are copied to person properties
  */
-export declare function getEventProperties(): Record<string, any>;
+export declare function getEventProperties(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): Record<string, any>;