@v-tilt/browser 1.0.1

package/lib/user-manager.js

@@ -0,0 +1,565 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserManager = void 0;
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+class UserManager {
+    constructor(storageMethod = "localStorage", domain) {
+        this._cachedPersonProperties = null; // PostHog behavior: cache for deduplication
+        this.storageMethod = storageMethod;
+        this.domain = domain;
+        this.userIdentity = this.loadUserIdentity();
+    }
+    /**
+     * Get current user identity
+     */
+    getUserIdentity() {
+        return { ...this.userIdentity };
+    }
+    /**
+     * Get current distinct ID (identified user ID)
+     */
+    getDistinctId() {
+        return this.userIdentity.distinct_id;
+    }
+    /**
+     * Get current anonymous ID
+     */
+    getAnonymousId() {
+        if (!this.userIdentity.anonymous_id) {
+            // Regenerate if somehow undefined
+            this.userIdentity.anonymous_id = this.generateAnonymousId();
+            this.saveUserIdentity();
+        }
+        return this.userIdentity.anonymous_id;
+    }
+    /**
+     * Get current user properties
+     */
+    getUserProperties() {
+        return { ...this.userIdentity.properties };
+    }
+    /**
+     * Identify a user with distinct ID and properties
+     * Copied from PostHog's identify method implementation
+     */
+    identify(newDistinctId, userPropertiesToSet, userPropertiesToSetOnce) {
+        // PostHog validation: Convert number to string
+        if (typeof newDistinctId === "number") {
+            newDistinctId = newDistinctId.toString();
+            console.warn("The first argument to vTilt.identify was a number, but it should be a string. It has been converted to a string.");
+        }
+        // PostHog validation: Check if distinct_id is provided
+        if (!newDistinctId) {
+            console.error("Unique user id has not been set in vTilt.identify");
+            return;
+        }
+        // PostHog validation: Check for hardcoded strings
+        if (this.isDistinctIdStringLike(newDistinctId)) {
+            console.error(`The string "${newDistinctId}" was set in vTilt.identify which indicates an error. This ID should be unique to the user and not a hardcoded string.`);
+            return;
+        }
+        // PostHog validation: Check for cookieless sentinel value
+        if (newDistinctId === "COOKIELESS_SENTINEL_VALUE") {
+            console.error(`The string "${newDistinctId}" was set in vTilt.identify which indicates an error. This ID is only used as a sentinel value.`);
+            return;
+        }
+        const previousDistinctId = this.userIdentity.distinct_id;
+        const anonymousId = this.userIdentity.anonymous_id;
+        const deviceId = this.userIdentity.device_id;
+        // PostHog behavior: Register user ID
+        this.userIdentity.distinct_id = newDistinctId;
+        // PostHog behavior: Handle device ID if not already set
+        if (!this.userIdentity.device_id) {
+            // The persisted distinct id might not actually be a device id at all
+            // it might be a distinct id of the user from before
+            const device_id = previousDistinctId || this.userIdentity.anonymous_id;
+            this.userIdentity.device_id = device_id;
+            this.userIdentity.properties = {
+                ...this.userIdentity.properties,
+                $had_persisted_distinct_id: true,
+                $device_id: device_id,
+            };
+        }
+        // PostHog behavior: Clear alias if distinct_id is changing
+        if (newDistinctId !== previousDistinctId) {
+            // Clear any stored alias (we don't have alias support yet, but keeping PostHog structure)
+            this.userIdentity.distinct_id = newDistinctId;
+        }
+        // PostHog behavior: Check if user was anonymous
+        const isKnownAnonymous = this.userIdentity.user_state === "anonymous";
+        // PostHog behavior: Send $identify event only when distinct_id is changing AND user was anonymous
+        // - logic on the server will determine whether or not to do anything with it.
+        if (newDistinctId !== previousDistinctId && isKnownAnonymous) {
+            // Update user state to identified
+            this.userIdentity.user_state = "identified";
+            // Handle $set properties (update existing)
+            if (userPropertiesToSet) {
+                this.userIdentity.properties = {
+                    ...this.userIdentity.properties,
+                    ...userPropertiesToSet,
+                };
+            }
+            // Handle $set_once properties (preserve first value)
+            if (userPropertiesToSetOnce) {
+                Object.keys(userPropertiesToSetOnce).forEach((key) => {
+                    if (!(key in this.userIdentity.properties)) {
+                        this.userIdentity.properties[key] = userPropertiesToSetOnce[key];
+                    }
+                });
+            }
+            // Save to storage
+            this.saveUserIdentity();
+            // PostHog behavior: Send $identify event for session merging
+            this.sendIdentifyEvent(newDistinctId, anonymousId, deviceId, {
+                $set: userPropertiesToSet || {},
+                $set_once: userPropertiesToSetOnce || {},
+            });
+        }
+        else if (userPropertiesToSet || userPropertiesToSetOnce) {
+            // PostHog behavior: If distinct_id is not changing but we have properties to set
+            // Update user state if not already identified
+            if (this.userIdentity.user_state === "anonymous") {
+                this.userIdentity.user_state = "identified";
+            }
+            // Handle $set properties (update existing)
+            if (userPropertiesToSet) {
+                this.userIdentity.properties = {
+                    ...this.userIdentity.properties,
+                    ...userPropertiesToSet,
+                };
+            }
+            // Handle $set_once properties (preserve first value)
+            if (userPropertiesToSetOnce) {
+                Object.keys(userPropertiesToSetOnce).forEach((key) => {
+                    if (!(key in this.userIdentity.properties)) {
+                        this.userIdentity.properties[key] = userPropertiesToSetOnce[key];
+                    }
+                });
+            }
+            // Save to storage
+            this.saveUserIdentity();
+            // PostHog behavior: Send $set event to notify server of property updates
+            // This allows Tinybird to track property changes when identify() is called with properties
+            // but no $identify event is sent (user was already identified)
+            this.sendSetEvent(userPropertiesToSet || {}, userPropertiesToSetOnce || {});
+        }
+        else {
+            // If distinct_id is changing but user was already identified, just update the distinct_id
+            if (newDistinctId !== previousDistinctId) {
+                this.userIdentity.user_state = "identified";
+                this.saveUserIdentity();
+            }
+        }
+    }
+    /**
+     * Set user properties without changing distinct ID (PostHog-style)
+     * Sets properties on the person profile associated with the current distinct_id
+     *
+     * @example
+     * ```js
+     * // Set properties that can be updated
+     * vt.setUserProperties({ name: 'John Doe', email: 'john@example.com' })
+     * ```
+     *
+     * @example
+     * ```js
+     * // Set properties with $set and $set_once operations
+     * vt.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) {
+        // PostHog behavior: Return early if no properties provided
+        if (!userPropertiesToSet && !userPropertiesToSetOnce) {
+            return;
+        }
+        // PostHog behavior: Create hash for deduplication
+        const distinctId = this.userIdentity.distinct_id || this.userIdentity.anonymous_id;
+        const hash = this.getPersonPropertiesHash(distinctId, userPropertiesToSet, userPropertiesToSetOnce);
+        // PostHog behavior: Skip if exactly this $set call has been sent before
+        if (this._cachedPersonProperties === hash) {
+            console.info("VTilt: A duplicate setUserProperties call was made with the same properties. It has been ignored.");
+            return;
+        }
+        // PostHog behavior: Handle $set properties (update existing)
+        if (userPropertiesToSet) {
+            this.userIdentity.properties = {
+                ...this.userIdentity.properties,
+                ...userPropertiesToSet,
+            };
+        }
+        // PostHog behavior: Handle $set_once properties (preserve first value)
+        if (userPropertiesToSetOnce) {
+            Object.keys(userPropertiesToSetOnce).forEach((key) => {
+                if (!(key in this.userIdentity.properties)) {
+                    this.userIdentity.properties[key] = userPropertiesToSetOnce[key];
+                }
+            });
+        }
+        // Save to storage
+        this.saveUserIdentity();
+        // PostHog behavior: Send $set event to notify server of property updates
+        this.sendSetEvent(userPropertiesToSet || {}, userPropertiesToSetOnce || {});
+        // PostHog behavior: Cache the hash to prevent duplicate sends
+        this._cachedPersonProperties = hash;
+    }
+    /**
+     * Get hash for person properties (PostHog behavior)
+     * Used for deduplication of identical setUserProperties calls
+     */
+    getPersonPropertiesHash(distinctId, userPropertiesToSet, userPropertiesToSetOnce) {
+        // PostHog behavior: Create deterministic hash from distinct_id and properties
+        return JSON.stringify({
+            distinct_id: distinctId,
+            userPropertiesToSet,
+            userPropertiesToSetOnce,
+        });
+    }
+    /**
+     * Send $set event for property updates (PostHog behavior)
+     * This notifies the server when user properties are updated
+     */
+    sendSetEvent(userPropertiesToSet, userPropertiesToSetOnce) {
+        // Emit a custom event that TrackingManager can listen to
+        const setEvent = new CustomEvent("vtilt:set", {
+            detail: {
+                $set: userPropertiesToSet || {},
+                $set_once: userPropertiesToSetOnce || {},
+            },
+        });
+        window.dispatchEvent(setEvent);
+    }
+    /**
+     * Reset user identity (logout)
+     * PostHog behavior: Generates new anonymous ID, clears user data, optionally resets device ID
+     *
+     * @param reset_device_id - If true, also resets device_id. Default: false (preserves device_id)
+     */
+    reset(reset_device_id) {
+        // PostHog behavior: Generate completely new anonymous ID (don't revert to original)
+        const newAnonymousId = this.generateAnonymousId();
+        const device_id = this.userIdentity.device_id;
+        // Generate new device ID if reset_device_id is true
+        const newDeviceId = reset_device_id ? this.generateDeviceId() : device_id;
+        this.userIdentity = {
+            distinct_id: null,
+            anonymous_id: newAnonymousId,
+            device_id: newDeviceId,
+            properties: {},
+            user_state: "anonymous",
+        };
+        // PostHog behavior: Clear cached person properties on reset
+        this._cachedPersonProperties = null;
+        this.saveUserIdentity();
+        // PostHog behavior: Set $last_posthog_reset property
+        // Store it in properties, it will be sent on the next event
+        this.userIdentity.properties = {
+            ...this.userIdentity.properties,
+            $last_posthog_reset: new Date().toISOString(),
+        };
+        this.saveUserIdentity();
+    }
+    /**
+     * Get the effective ID for event tracking
+     */
+    getEffectiveId() {
+        return this.userIdentity.distinct_id || this.getAnonymousId();
+    }
+    /**
+     * Get current device ID
+     */
+    getDeviceId() {
+        return this.userIdentity.device_id;
+    }
+    /**
+     * Get current user state
+     */
+    getUserState() {
+        return this.userIdentity.user_state;
+    }
+    /**
+     * Create an alias to link two distinct IDs
+     * PostHog behavior: If original is not provided, uses current distinct_id
+     * If alias matches original, just calls identify instead
+     *
+     * @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)
+     */
+    createAlias(alias, original) {
+        if (!this.isValidDistinctId(alias)) {
+            console.warn("Invalid alias provided");
+            return;
+        }
+        // PostHog behavior: If original is not provided, use current distinct_id
+        if (original === undefined) {
+            original = this.getDistinctId() || this.getAnonymousId();
+        }
+        if (!this.isValidDistinctId(original)) {
+            console.warn("Invalid original distinct ID");
+            return;
+        }
+        // PostHog behavior: If alias matches original, just call identify instead
+        if (alias === original) {
+            console.warn("alias matches current distinct_id - calling identify instead");
+            this.identify(alias);
+            return;
+        }
+        // { distinct_id: alias, original: original }
+        const aliasEvent = {
+            distinct_id: alias,
+            original,
+        };
+        // Emit alias event
+        const customEvent = new CustomEvent("vtilt:alias", {
+            detail: aliasEvent,
+        });
+        window.dispatchEvent(customEvent);
+    }
+    /**
+     * Validate distinct ID to prevent hardcoded strings
+     * Copied from PostHog's validation logic
+     */
+    isValidDistinctId(distinctId) {
+        if (!distinctId || typeof distinctId !== "string") {
+            return false;
+        }
+        // PostHog's validation patterns
+        const invalidPatterns = [
+            "null",
+            "undefined",
+            "false",
+            "true",
+            "anonymous",
+            "anon",
+            "user",
+            "test",
+            "guest",
+            "visitor",
+            "unknown",
+            "none",
+        ];
+        const lower = distinctId.toLowerCase().trim();
+        if (invalidPatterns.includes(lower)) {
+            return false;
+        }
+        // Check for empty or whitespace-only strings
+        if (distinctId.trim().length === 0) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Check if distinct ID is string-like (hardcoded string)
+     * Copied from PostHog's isDistinctIdStringLike function
+     */
+    isDistinctIdStringLike(distinctId) {
+        if (!distinctId || typeof distinctId !== "string") {
+            return false;
+        }
+        // PostHog's hardcoded string patterns
+        const hardcodedPatterns = [
+            "null",
+            "undefined",
+            "false",
+            "true",
+            "anonymous",
+            "anon",
+            "user",
+            "test",
+            "guest",
+            "visitor",
+            "unknown",
+            "none",
+            "demo",
+            "example",
+            "sample",
+            "placeholder",
+        ];
+        const lower = distinctId.toLowerCase().trim();
+        return hardcodedPatterns.includes(lower);
+    }
+    /**
+     * Load user identity from storage
+     */
+    loadUserIdentity() {
+        const anonymousId = this.getStoredValue(constants_1.ANONYMOUS_ID_KEY) || this.generateAnonymousId();
+        const distinctId = this.getStoredValue(constants_1.DISTINCT_ID_KEY) || null;
+        const deviceId = this.getStoredValue(constants_1.DEVICE_ID_KEY) || this.generateDeviceId();
+        const properties = this.getStoredUserProperties();
+        const userState = this.getStoredValue(constants_1.USER_STATE_KEY) ||
+            "anonymous";
+        // Ensure anonymous_id is never undefined
+        const safeAnonymousId = anonymousId || this.generateAnonymousId();
+        const identity = {
+            distinct_id: distinctId,
+            anonymous_id: safeAnonymousId,
+            device_id: deviceId,
+            properties: properties,
+            user_state: userState,
+        };
+        return identity;
+    }
+    /**
+     * Save user identity to storage
+     */
+    saveUserIdentity() {
+        this.setStoredValue(constants_1.ANONYMOUS_ID_KEY, this.userIdentity.anonymous_id);
+        this.setStoredValue(constants_1.DEVICE_ID_KEY, this.userIdentity.device_id);
+        this.setStoredValue(constants_1.USER_STATE_KEY, this.userIdentity.user_state);
+        if (this.userIdentity.distinct_id) {
+            this.setStoredValue(constants_1.DISTINCT_ID_KEY, this.userIdentity.distinct_id);
+        }
+        else {
+            this.removeStoredValue(constants_1.DISTINCT_ID_KEY);
+        }
+        this.setStoredUserProperties(this.userIdentity.properties);
+    }
+    /**
+     * Generate a new anonymous ID
+     */
+    generateAnonymousId() {
+        return `anon_${(0, utils_1.uuidv4)()}`;
+    }
+    /**
+     * Generate a new device ID
+     */
+    generateDeviceId() {
+        return `device_${(0, utils_1.uuidv4)()}`;
+    }
+    /**
+     * Send identify event for session merging
+     */
+    sendIdentifyEvent(distinctId, anonymousId, deviceId, propertyOperations) {
+        // This will be handled by the TrackingManager
+        // We'll emit a custom event that the TrackingManager can listen to
+        const identifyEvent = new CustomEvent("vtilt:identify", {
+            detail: {
+                distinct_id: distinctId,
+                anonymous_id: anonymousId,
+                device_id: deviceId,
+                properties: {
+                    $anon_distinct_id: anonymousId,
+                    $device_id: deviceId,
+                    ...propertyOperations,
+                },
+            },
+        });
+        window.dispatchEvent(identifyEvent);
+    }
+    /**
+     * Get stored value from storage
+     */
+    getStoredValue(key) {
+        try {
+            if (this.storageMethod === constants_1.STORAGE_METHODS.localStorage) {
+                return localStorage.getItem(key);
+            }
+            else if (this.storageMethod === constants_1.STORAGE_METHODS.sessionStorage) {
+                return sessionStorage.getItem(key);
+            }
+            else {
+                return this.getCookieValue(key);
+            }
+        }
+        catch (error) {
+            // If storage access fails, return null
+            console.warn("Failed to access storage:", error);
+            return null;
+        }
+    }
+    /**
+     * Set stored value in storage
+     */
+    setStoredValue(key, value) {
+        try {
+            if (this.storageMethod === constants_1.STORAGE_METHODS.localStorage) {
+                localStorage.setItem(key, value);
+            }
+            else if (this.storageMethod === constants_1.STORAGE_METHODS.sessionStorage) {
+                sessionStorage.setItem(key, value);
+            }
+            else {
+                this.setCookieValue(key, value);
+            }
+        }
+        catch (error) {
+            // If storage access fails, log warning but don't throw
+            console.warn("Failed to save to storage:", error);
+        }
+    }
+    /**
+     * Remove stored value from storage
+     */
+    removeStoredValue(key) {
+        if (this.storageMethod === constants_1.STORAGE_METHODS.localStorage) {
+            localStorage.removeItem(key);
+        }
+        else if (this.storageMethod === constants_1.STORAGE_METHODS.sessionStorage) {
+            sessionStorage.removeItem(key);
+        }
+        else {
+            this.removeCookieValue(key);
+        }
+    }
+    /**
+     * Get user properties from storage
+     */
+    getStoredUserProperties() {
+        const stored = this.getStoredValue(constants_1.USER_PROPERTIES_KEY);
+        if (!stored) {
+            return {};
+        }
+        try {
+            return JSON.parse(stored);
+        }
+        catch (_a) {
+            return {};
+        }
+    }
+    /**
+     * Set user properties in storage
+     */
+    setStoredUserProperties(properties) {
+        this.setStoredValue(constants_1.USER_PROPERTIES_KEY, JSON.stringify(properties));
+    }
+    /**
+     * Get cookie value
+     */
+    getCookieValue(name) {
+        const cookies = document.cookie.split(";");
+        for (const cookie of cookies) {
+            const [key, value] = cookie.trim().split("=");
+            if (key === name) {
+                return decodeURIComponent(value);
+            }
+        }
+        return null;
+    }
+    /**
+     * Set cookie value
+     */
+    setCookieValue(name, value) {
+        let cookieValue = `${name}=${encodeURIComponent(value)}; Max-Age=31536000; path=/; secure; SameSite=Lax`;
+        if (this.domain) {
+            cookieValue += `; domain=${this.domain}`;
+        }
+        document.cookie = cookieValue;
+    }
+    /**
+     * Remove cookie value
+     */
+    removeCookieValue(name) {
+        let cookieValue = `${name}=; Max-Age=0; path=/`;
+        if (this.domain) {
+            cookieValue += `; domain=${this.domain}`;
+        }
+        document.cookie = cookieValue;
+    }
+}
+exports.UserManager = UserManager;

package/lib/utils/globals.d.ts

@@ -0,0 +1,4 @@
+export type AssignableWindow = Window & typeof globalThis & {
+    vt: any;
+};
+export declare const assignableWindow: AssignableWindow;

package/lib/utils/globals.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assignableWindow = void 0;
+const win = typeof window !== "undefined" ? window : undefined;
+exports.assignableWindow = win !== null && win !== void 0 ? win : {};

package/lib/utils/index.d.ts

@@ -0,0 +1,30 @@
+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;
+/**
+ * Iterate over an array or object
+ */
+export declare function each<T>(obj: T[] | Record<string, T> | null | undefined, iterator: (value: T, key: string | number) => void, thisArg?: any): void;
+/**
+ * Use this instead of element.addEventListener to avoid eslint errors
+ * 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;

package/lib/utils/index.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uuidv4 = uuidv4;
+exports.isValidUserAgent = isValidUserAgent;
+exports.isValidPayload = isValidPayload;
+exports.maskSuspiciousAttributes = maskSuspiciousAttributes;
+exports.isTestEnvironment = isTestEnvironment;
+exports.each = each;
+exports.addEventListener = addEventListener;
+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);
+}
+/**
+ * Iterate over an array or object
+ */
+function each(obj, iterator, thisArg) {
+    if (!obj) {
+        return;
+    }
+    if (Array.isArray(obj)) {
+        obj.forEach((value, index) => {
+            iterator.call(thisArg, value, index);
+        });
+    }
+    else {
+        for (const key in obj) {
+            if (Object.prototype.hasOwnProperty.call(obj, key)) {
+                iterator.call(thisArg, obj[key], key);
+            }
+        }
+    }
+}
+/**
+ * Use this instead of element.addEventListener to avoid eslint errors
+ * This properly implements the default options for passive event listeners
+ */
+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 });
+}