@v-tilt/browser 1.0.10 → 1.1.0

package/lib/utils/event-utils.js

@@ -1,63 +1,251 @@
 "use strict";
+/**
+ * Event utilities
+ * Functions for extracting event properties, campaign parameters, and person info
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.COOKIE_CAMPAIGN_PARAMS = exports.MASKED = exports.EVENT_TO_PERSON_PROPERTIES = exports.CAMPAIGN_PARAMS = exports.PERSONAL_DATA_CAMPAIGN_PARAMS = void 0;
+exports.getCampaignParams = getCampaignParams;
+exports.getSearchInfo = getSearchInfo;
 exports.getBrowserLanguage = getBrowserLanguage;
 exports.getBrowserLanguagePrefix = getBrowserLanguagePrefix;
 exports.getReferrer = getReferrer;
 exports.getReferringDomain = getReferringDomain;
+exports.getReferrerInfo = getReferrerInfo;
+exports.getPersonInfo = getPersonInfo;
+exports.getPersonPropsFromInfo = getPersonPropsFromInfo;
+exports.getInitialPersonPropsFromInfo = getInitialPersonPropsFromInfo;
 exports.getTimezone = getTimezone;
 exports.getTimezoneOffset = getTimezoneOffset;
 exports.getEventProperties = getEventProperties;
+const request_utils_1 = require("./request-utils");
+const index_1 = require("./index");
 const globals_1 = require("./globals");
 const user_agent_utils_1 = require("./user-agent-utils");
+const URL_REGEX_PREFIX = "https?://(.*)";
 // Library version - should match package.json version
 const LIB_VERSION = "1.0.7"; // TODO: Auto-import from package.json
+// Campaign parameters that could be considered personal data (e.g., GDPR)
+// These can be masked in URLs and properties before being sent
+exports.PERSONAL_DATA_CAMPAIGN_PARAMS = [
+    "gclid", // google ads
+    "gclsrc", // google ads 360
+    "dclid", // google display ads
+    "gbraid", // google ads, web to app
+    "wbraid", // google ads, app to web
+    "fbclid", // facebook
+    "msclkid", // microsoft
+    "twclid", // twitter
+    "li_fat_id", // linkedin
+    "igshid", // instagram
+    "ttclid", // tiktok
+    "rdt_cid", // reddit
+    "epik", // pinterest
+    "qclid", // quora
+    "sccid", // snapchat
+    "irclid", // impact
+    "_kx", // klaviyo
+];
+exports.CAMPAIGN_PARAMS = (0, index_1.extendArray)([
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_content",
+    "utm_term",
+    "gad_source", // google ads source
+    "mc_cid", // mailchimp campaign id
+], exports.PERSONAL_DATA_CAMPAIGN_PARAMS);
+// Properties that should be automatically copied from events to person properties
+exports.EVENT_TO_PERSON_PROPERTIES = [
+    // Mobile app properties
+    "$app_build",
+    "$app_name",
+    "$app_namespace",
+    "$app_version",
+    // Web browser properties
+    "$browser",
+    "$browser_version",
+    "$device_type",
+    "$current_url",
+    "$pathname",
+    "$os",
+    "$os_name", // Special case: treated as alias of $os
+    "$os_version",
+    "$referring_domain",
+    "$referrer",
+    "$screen_height",
+    "$screen_width",
+    "$viewport_height",
+    "$viewport_width",
+    "$raw_user_agent",
+];
+exports.MASKED = "<masked>";
+// Campaign params that can be read from cookies (currently not implemented)
+exports.COOKIE_CAMPAIGN_PARAMS = [
+    "li_fat_id", // linkedin
+];
 /**
- * Get browser language
- * Returns the browser's language setting (e.g., "en-US")
+ * Get campaign parameters from URL
+ * Extracts UTM and other campaign tracking parameters from current page URL
+ * Masks personal data parameters if configured
  */
+function getCampaignParams(customTrackedParams, maskPersonalDataProperties, customPersonalDataProperties) {
+    if (!globals_1.document) {
+        return {};
+    }
+    const paramsToMask = maskPersonalDataProperties
+        ? (0, index_1.extendArray)([], exports.PERSONAL_DATA_CAMPAIGN_PARAMS, customPersonalDataProperties || [])
+        : [];
+    // Initially get campaign params from the URL
+    const urlCampaignParams = _getCampaignParamsFromUrl((0, request_utils_1.maskQueryParams)(globals_1.document.URL, paramsToMask, exports.MASKED), customTrackedParams);
+    // But we can also get some of them from the cookie store
+    // For now, we'll skip cookie-based campaign params (would need cookie store implementation)
+    const cookieCampaignParams = {};
+    // Prefer the values found in the urlCampaignParams if possible
+    // `extend` will override the values if found in the second argument
+    return (0, index_1.extend)(cookieCampaignParams, urlCampaignParams);
+}
+function _getCampaignParamsFromUrl(url, customParams) {
+    const campaign_keywords = exports.CAMPAIGN_PARAMS.concat(customParams || []);
+    const params = {};
+    (0, index_1.each)(campaign_keywords, function (kwkey) {
+        const kw = (0, request_utils_1.getQueryParam)(url, kwkey);
+        params[kwkey] = kw ? kw : null;
+    });
+    return params;
+}
+function _getSearchEngine(referrer) {
+    if (!referrer) {
+        return null;
+    }
+    else {
+        if (referrer.search(URL_REGEX_PREFIX + "google.([^/?]*)") === 0) {
+            return "google";
+        }
+        else if (referrer.search(URL_REGEX_PREFIX + "bing.com") === 0) {
+            return "bing";
+        }
+        else if (referrer.search(URL_REGEX_PREFIX + "yahoo.com") === 0) {
+            return "yahoo";
+        }
+        else if (referrer.search(URL_REGEX_PREFIX + "duckduckgo.com") === 0) {
+            return "duckduckgo";
+        }
+        else {
+            return null;
+        }
+    }
+}
+function _getSearchInfoFromReferrer(referrer) {
+    const search = _getSearchEngine(referrer);
+    const param = search !== "yahoo" ? "q" : "p";
+    const ret = {};
+    if (!(0, index_1.isNull)(search)) {
+        ret["$search_engine"] = search;
+        const keyword = globals_1.document ? (0, request_utils_1.getQueryParam)(globals_1.document.referrer, param) : "";
+        if (keyword.length) {
+            ret["ph_keyword"] = keyword;
+        }
+    }
+    return ret;
+}
+function getSearchInfo() {
+    const referrer = globals_1.document === null || globals_1.document === void 0 ? void 0 : globals_1.document.referrer;
+    if (!referrer) {
+        return {};
+    }
+    return _getSearchInfoFromReferrer(referrer);
+}
 function getBrowserLanguage() {
-    if (typeof globals_1.navigator === "undefined") {
+    if (typeof navigator === "undefined") {
         return undefined;
     }
-    return (globals_1.navigator.language || // Any modern browser
-        globals_1.navigator.userLanguage // IE11
+    return (navigator.language || // Any modern browser
+        navigator.userLanguage // IE11
     );
 }
-/**
- * Get browser language prefix
- * Returns the language code without region (e.g., "en" from "en-US")
- */
 function getBrowserLanguagePrefix() {
     const lang = getBrowserLanguage();
     return typeof lang === "string" ? lang.split("-")[0] : undefined;
 }
-/**
- * Get referrer
- * Returns document.referrer or '$direct' if no referrer
- */
 function getReferrer() {
     return (globals_1.document === null || globals_1.document === void 0 ? void 0 : globals_1.document.referrer) || "$direct";
 }
-/**
- * Get referring domain
- * Returns the hostname of the referrer URL or '$direct' if no referrer
- */
 function getReferringDomain() {
+    var _a;
     if (!(globals_1.document === null || globals_1.document === void 0 ? void 0 : globals_1.document.referrer)) {
         return "$direct";
     }
-    try {
-        const url = new URL(globals_1.document.referrer);
-        return url.host || "$direct";
+    return ((_a = (0, request_utils_1.convertToURL)(globals_1.document.referrer)) === null || _a === void 0 ? void 0 : _a.host) || "$direct";
+}
+/**
+ * Get referrer information
+ * Returns current referrer and referring domain
+ */
+function getReferrerInfo() {
+    return {
+        $referrer: getReferrer(),
+        $referring_domain: getReferringDomain(),
+    };
+}
+/**
+ * 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
+ */
+function getPersonInfo(maskPersonalDataProperties, customPersonalDataProperties) {
+    const paramsToMask = maskPersonalDataProperties
+        ? (0, index_1.extendArray)([], exports.PERSONAL_DATA_CAMPAIGN_PARAMS, customPersonalDataProperties || [])
+        : [];
+    const url = globals_1.location === null || globals_1.location === void 0 ? void 0 : globals_1.location.href.substring(0, 1000);
+    // Compact format for storage efficiency (stored in localStorage)
+    return {
+        r: getReferrer().substring(0, 1000),
+        u: url ? (0, request_utils_1.maskQueryParams)(url, paramsToMask, exports.MASKED) : undefined,
+    };
+}
+/**
+ * Convert person info to person properties
+ * Extracts referrer, URL, campaign params, and search info from stored person info
+ */
+function getPersonPropsFromInfo(info) {
+    var _a;
+    const { r: referrer, u: url } = info;
+    const referring_domain = referrer == null
+        ? undefined
+        : referrer === "$direct"
+            ? "$direct"
+            : (_a = (0, request_utils_1.convertToURL)(referrer)) === null || _a === void 0 ? void 0 : _a.host;
+    const props = {
+        $referrer: referrer,
+        $referring_domain: referring_domain,
+    };
+    if (url) {
+        props["$current_url"] = url;
+        const location = (0, request_utils_1.convertToURL)(url);
+        props["$host"] = location === null || location === void 0 ? void 0 : location.host;
+        props["$pathname"] = location === null || location === void 0 ? void 0 : location.pathname;
+        const campaignParams = _getCampaignParamsFromUrl(url);
+        (0, index_1.extend)(props, campaignParams);
     }
-    catch (_a) {
-        return "$direct";
+    if (referrer) {
+        const searchInfo = _getSearchInfoFromReferrer(referrer);
+        (0, index_1.extend)(props, searchInfo);
     }
+    return props;
 }
 /**
- * Get timezone
- * Returns the timezone (e.g., "America/New_York")
+ * Convert person info to initial person properties
+ * Generates $initial_* properties from person info (preserves first values)
  */
+function getInitialPersonPropsFromInfo(info) {
+    const personProps = getPersonPropsFromInfo(info);
+    const props = {};
+    (0, index_1.each)(personProps, function (val, key) {
+        props[`$initial_${(0, index_1.stripLeadingDollar)(String(key))}`] = val;
+    });
+    return props;
+}
 function getTimezone() {
     try {
         return Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -66,10 +254,6 @@ function getTimezone() {
         return undefined;
     }
 }
-/**
- * Get timezone offset
- * Returns the timezone offset in minutes
- */
 function getTimezoneOffset() {
     try {
         return new Date().getTimezoneOffset();
@@ -78,100 +262,45 @@ function getTimezoneOffset() {
         return undefined;
     }
 }
-/**
- * Generate insert ID for deduplication
- */
-function generateInsertId() {
-    return (Math.random().toString(36).substring(2, 10) +
-        Math.random().toString(36).substring(2, 10));
-}
 /**
  * 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
  */
-function getEventProperties() {
-    const props = {};
+function getEventProperties(maskPersonalDataProperties, customPersonalDataProperties) {
     if (!globals_1.userAgent) {
-        return props;
+        return {};
     }
-    // Device/OS properties
+    const paramsToMask = maskPersonalDataProperties
+        ? (0, index_1.extendArray)([], exports.PERSONAL_DATA_CAMPAIGN_PARAMS, customPersonalDataProperties || [])
+        : [];
     const [os_name, os_version] = (0, user_agent_utils_1.detectOS)(globals_1.userAgent);
-    if (os_name) {
-        props.$os = os_name;
-    }
-    if (os_version) {
-        props.$os_version = os_version;
-    }
-    const browser = (0, user_agent_utils_1.detectBrowser)(globals_1.userAgent, globals_1.navigator === null || globals_1.navigator === void 0 ? void 0 : globals_1.navigator.vendor);
-    if (browser) {
-        props.$browser = browser;
-    }
-    const browserVersion = (0, user_agent_utils_1.detectBrowserVersion)(globals_1.userAgent, globals_1.navigator === null || globals_1.navigator === void 0 ? void 0 : globals_1.navigator.vendor);
-    if (browserVersion) {
-        props.$browser_version = browserVersion;
-    }
-    const device = (0, user_agent_utils_1.detectDevice)(globals_1.userAgent);
-    if (device) {
-        props.$device = device;
-    }
-    const deviceType = (0, user_agent_utils_1.detectDeviceType)(globals_1.userAgent);
-    if (deviceType) {
-        props.$device_type = deviceType;
-    }
-    // Timezone properties
-    const timezone = getTimezone();
-    if (timezone) {
-        props.$timezone = timezone;
-    }
-    const timezoneOffset = getTimezoneOffset();
-    if (timezoneOffset !== undefined) {
-        props.$timezone_offset = timezoneOffset;
-    }
-    // URL properties (added to all events)
-    if (globals_1.location) {
-        props.$current_url = globals_1.location.href;
-        props.$host = globals_1.location.host;
-        props.$pathname = globals_1.location.pathname;
-    }
-    // User agent
-    if (globals_1.userAgent) {
-        props.$raw_user_agent =
-            globals_1.userAgent.length > 1000 ? globals_1.userAgent.substring(0, 997) + "..." : globals_1.userAgent;
-    }
-    // Browser language (added to all events)
-    const browserLanguage = getBrowserLanguage();
-    const browserLanguagePrefix = getBrowserLanguagePrefix();
-    if (browserLanguage) {
-        props.$browser_language = browserLanguage;
-    }
-    if (browserLanguagePrefix) {
-        props.$browser_language_prefix = browserLanguagePrefix;
-    }
-    // Screen/viewport properties
-    if (globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.screen) {
-        if (globals_1.window.screen.height) {
-            props.$screen_height = globals_1.window.screen.height;
-        }
-        if (globals_1.window.screen.width) {
-            props.$screen_width = globals_1.window.screen.width;
-        }
-    }
-    if (globals_1.window) {
-        if (globals_1.window.innerHeight) {
-            props.$viewport_height = globals_1.window.innerHeight;
-        }
-        if (globals_1.window.innerWidth) {
-            props.$viewport_width = globals_1.window.innerWidth;
-        }
-    }
-    // Library info
-    props.$lib = "web";
-    props.$lib_version = LIB_VERSION;
-    // Insert ID for deduplication
-    props.$insert_id = generateInsertId();
-    // Timestamp (epoch time in seconds)
-    props.$time = Date.now() / 1000;
-    // Referrer properties (added to all events)
-    props.$referrer = getReferrer();
-    props.$referring_domain = getReferringDomain();
-    return props;
+    return (0, index_1.extend)((0, index_1.stripEmptyProperties)({
+        $os: os_name,
+        $os_version: os_version,
+        $browser: (0, user_agent_utils_1.detectBrowser)(globals_1.userAgent, navigator.vendor),
+        $device: (0, user_agent_utils_1.detectDevice)(globals_1.userAgent),
+        $device_type: (0, user_agent_utils_1.detectDeviceType)(globals_1.userAgent),
+        $timezone: getTimezone(),
+        $timezone_offset: getTimezoneOffset(),
+    }), {
+        $current_url: (0, request_utils_1.maskQueryParams)(globals_1.location === null || globals_1.location === void 0 ? void 0 : globals_1.location.href, paramsToMask, exports.MASKED),
+        $host: globals_1.location === null || globals_1.location === void 0 ? void 0 : globals_1.location.host,
+        $pathname: globals_1.location === null || globals_1.location === void 0 ? void 0 : globals_1.location.pathname,
+        $raw_user_agent: globals_1.userAgent.length > 1000
+            ? globals_1.userAgent.substring(0, 997) + "..."
+            : globals_1.userAgent,
+        $browser_version: (0, user_agent_utils_1.detectBrowserVersion)(globals_1.userAgent, navigator.vendor),
+        $browser_language: getBrowserLanguage(),
+        $browser_language_prefix: getBrowserLanguagePrefix(),
+        $screen_height: globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.screen.height,
+        $screen_width: globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.screen.width,
+        $viewport_height: globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.innerHeight,
+        $viewport_width: globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.innerWidth,
+        $lib: "web",
+        $lib_version: LIB_VERSION,
+        $insert_id: Math.random().toString(36).substring(2, 10) +
+            Math.random().toString(36).substring(2, 10),
+        $time: Date.now() / 1000, // epoch time in seconds
+    });
 }

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,80 @@
+"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;
+}