@v-tilt/browser 1.6.0 → 1.7.2

package/lib/user-manager.js

@@ -1,589 +0,0 @@
-"use strict";
-/**
- * User Manager - Handles user identity and properties
- *
- * Uses shared StorageManager for consistent storage operations.
- *
- * Manages:
- * - anonymous_id: Generated ID for anonymous users
- * - distinct_id: User-provided ID after identification
- * - device_id: Persistent device identifier
- * - user_properties: Custom properties set via identify/setUserProperties
- * - user_state: "anonymous" or "identified"
- */
-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");
-const storage_1 = require("./storage");
-class UserManager {
-    constructor(storageMethod = "localStorage", cross_subdomain) {
-        this._cachedPersonProperties = null; // Cache for deduplication
-        this.storage = new storage_1.StorageManager({
-            method: storageMethod,
-            cross_subdomain,
-            sameSite: "Lax",
-        });
-        this.userIdentity = this.loadUserIdentity();
-    }
-    // ============================================================================
-    // Public Getters
-    // ============================================================================
-    /**
-     * 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.storage.set(constants_1.ANONYMOUS_ID_KEY, this.userIdentity.anonymous_id, storage_1.USER_COOKIE_MAX_AGE);
-        }
-        return this.userIdentity.anonymous_id;
-    }
-    /**
-     * Get current user properties
-     */
-    getUserProperties() {
-        return { ...this.userIdentity.properties };
-    }
-    /**
-     * 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;
-    }
-    // ============================================================================
-    // Identity Operations
-    // ============================================================================
-    /**
-     * Identify a user with distinct ID and properties
-     */
-    identify(newDistinctId, userPropertiesToSet, userPropertiesToSetOnce) {
-        // 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.");
-        }
-        // Validation: Check if distinct_id is provided
-        if (!newDistinctId) {
-            console.error("Unique user id has not been set in vTilt.identify");
-            return;
-        }
-        // 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;
-        }
-        // 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;
-        // Register user ID
-        this.userIdentity.distinct_id = newDistinctId;
-        // 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,
-            };
-        }
-        // Clear alias if distinct_id is changing
-        if (newDistinctId !== previousDistinctId) {
-            // Clear any stored alias
-            this.userIdentity.distinct_id = newDistinctId;
-        }
-        // Check if user was anonymous
-        const isKnownAnonymous = this.userIdentity.user_state === "anonymous";
-        // 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();
-            // Note: Event sending is now handled by VTilt.identify()
-            // This method is kept for backward compatibility but should not be called directly
-        }
-        else if (userPropertiesToSet || userPropertiesToSetOnce) {
-            // 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();
-            // Note: Event sending is now handled by VTilt.identify()
-            // This method is kept for backward compatibility but should not be called directly
-        }
-        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
-     */
-    setUserProperties(userPropertiesToSet, userPropertiesToSetOnce) {
-        // Return early if no properties provided
-        if (!userPropertiesToSet && !userPropertiesToSetOnce) {
-            return false;
-        }
-        // Create hash for deduplication
-        const distinctId = this.userIdentity.distinct_id || this.userIdentity.anonymous_id;
-        const hash = this.getPersonPropertiesHash(distinctId, userPropertiesToSet, userPropertiesToSetOnce);
-        // 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 false;
-        }
-        // 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();
-        // Cache the hash to prevent duplicate sends
-        this._cachedPersonProperties = hash;
-        // Note: Event sending is now handled by VTilt.setUserProperties()
-        return true;
-    }
-    /**
-     * Reset user identity (logout)
-     * Generates new anonymous ID, clears user data, optionally resets device ID
-     */
-    reset(reset_device_id) {
-        // 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",
-        };
-        // Clear cached person properties on reset
-        this._cachedPersonProperties = null;
-        this.saveUserIdentity();
-        // Set $last_vtilt_reset property
-        // Store it in properties, it will be sent on the next event
-        this.userIdentity.properties = {
-            ...this.userIdentity.properties,
-            $last_vtilt_reset: new Date().toISOString(),
-        };
-        this.saveUserIdentity();
-    }
-    // ============================================================================
-    // Internal Setters (for VTilt class)
-    // ============================================================================
-    /**
-     * Update distinct ID (internal use - for VTilt)
-     */
-    setDistinctId(distinctId) {
-        this.userIdentity.distinct_id = distinctId;
-        this.saveUserIdentity();
-    }
-    /**
-     * Update user state (internal use - for VTilt)
-     */
-    setUserState(state) {
-        this.userIdentity.user_state = state;
-        this.saveUserIdentity();
-    }
-    /**
-     * Update user properties (internal use - for VTilt)
-     */
-    updateUserProperties(userPropertiesToSet, userPropertiesToSetOnce) {
-        // 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];
-                }
-            });
-        }
-        this.saveUserIdentity();
-    }
-    /**
-     * Set device ID if not already set (internal use - for VTilt)
-     */
-    ensureDeviceId(deviceId) {
-        if (!this.userIdentity.device_id) {
-            this.userIdentity.device_id = deviceId;
-            this.userIdentity.properties = {
-                ...this.userIdentity.properties,
-                $had_persisted_distinct_id: true,
-                $device_id: deviceId,
-            };
-            this.saveUserIdentity();
-        }
-    }
-    // ============================================================================
-    // Alias Operations
-    // ============================================================================
-    /**
-     * Create an alias to link two distinct IDs
-     */
-    createAlias(alias, original) {
-        if (!this.isValidDistinctId(alias)) {
-            console.warn("Invalid alias provided");
-            return null;
-        }
-        // 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 null;
-        }
-        // If alias matches original, return null (caller should use identify)
-        if (alias === original) {
-            console.warn("alias matches current distinct_id - should use identify instead");
-            return null;
-        }
-        // { distinct_id: alias, original: original }
-        const aliasEvent = {
-            distinct_id: alias,
-            original,
-        };
-        // Note: Event sending is now handled by VTilt.createAlias()
-        return aliasEvent;
-    }
-    /**
-     * Check if distinct ID is string-like (hardcoded string) - public for validation
-     */
-    isDistinctIdStringLikePublic(distinctId) {
-        return this.isDistinctIdStringLike(distinctId);
-    }
-    // ============================================================================
-    // Initial Person Info
-    // ============================================================================
-    /**
-     * Set initial person info
-     */
-    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
-     */
-    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
-     */
-    update_referrer_info() {
-        const referrerInfo = (0, event_utils_1.getReferrerInfo)();
-        this.register_once(referrerInfo, undefined);
-    }
-    // ============================================================================
-    // Storage Operations (using StorageManager)
-    // ============================================================================
-    /**
-     * Load user identity from storage.
-     *
-     * For traditional SSR websites where each page navigation reloads JavaScript,
-     * identity MUST be persisted immediately when generated to ensure the same
-     * anonymous_id is used across all page loads.
-     *
-     * Flow:
-     * 1. Load from storage (reads cookies first for critical properties in SSR mode)
-     * 2. Generate new IDs if not found
-     * 3. Immediately persist to storage (saved to both localStorage and cookies)
-     *
-     * With `localStorage+cookie` persistence (default):
-     * - Critical properties are stored in cookies for SSR compatibility
-     * - Full data is stored in localStorage for fast SPA-style access
-     * - Cookies ensure identity persists across full page reloads
-     */
-    loadUserIdentity() {
-        // Try to load existing IDs from storage
-        // In localStorage+cookie mode, this reads from cookies first for critical properties
-        const storedAnonymousId = this.storage.get(constants_1.ANONYMOUS_ID_KEY);
-        const storedDeviceId = this.storage.get(constants_1.DEVICE_ID_KEY);
-        const storedDistinctId = this.storage.get(constants_1.DISTINCT_ID_KEY);
-        const storedUserState = this.storage.get(constants_1.USER_STATE_KEY);
-        const properties = this.getStoredUserProperties();
-        // Generate new IDs if not found in storage
-        const anonymousId = storedAnonymousId || this.generateAnonymousId();
-        const deviceId = storedDeviceId || this.generateDeviceId();
-        const distinctId = storedDistinctId || null;
-        const userState = storedUserState || "anonymous";
-        // Ensure anonymous_id is never undefined
-        const safeAnonymousId = anonymousId || this.generateAnonymousId();
-        // CRITICAL: Immediately persist newly generated IDs to storage
-        // This ensures identity survives page reloads in traditional SSR websites
-        // In localStorage+cookie mode, critical properties are saved to cookies automatically
-        if (!storedAnonymousId) {
-            this.storage.set(constants_1.ANONYMOUS_ID_KEY, safeAnonymousId, storage_1.USER_COOKIE_MAX_AGE);
-        }
-        if (!storedDeviceId) {
-            this.storage.set(constants_1.DEVICE_ID_KEY, deviceId, storage_1.USER_COOKIE_MAX_AGE);
-        }
-        if (!storedUserState) {
-            this.storage.set(constants_1.USER_STATE_KEY, userState, storage_1.USER_COOKIE_MAX_AGE);
-        }
-        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.storage.set(constants_1.ANONYMOUS_ID_KEY, this.userIdentity.anonymous_id, storage_1.USER_COOKIE_MAX_AGE);
-        this.storage.set(constants_1.DEVICE_ID_KEY, this.userIdentity.device_id, storage_1.USER_COOKIE_MAX_AGE);
-        this.storage.set(constants_1.USER_STATE_KEY, this.userIdentity.user_state, storage_1.USER_COOKIE_MAX_AGE);
-        if (this.userIdentity.distinct_id) {
-            this.storage.set(constants_1.DISTINCT_ID_KEY, this.userIdentity.distinct_id, storage_1.USER_COOKIE_MAX_AGE);
-        }
-        else {
-            this.storage.remove(constants_1.DISTINCT_ID_KEY);
-        }
-        this.setStoredUserProperties(this.userIdentity.properties);
-    }
-    /**
-     * Get user properties from storage
-     */
-    getStoredUserProperties() {
-        return this.storage.getJSON(constants_1.USER_PROPERTIES_KEY) || {};
-    }
-    /**
-     * Set user properties in storage
-     */
-    setStoredUserProperties(properties) {
-        this.storage.setJSON(constants_1.USER_PROPERTIES_KEY, properties, storage_1.USER_COOKIE_MAX_AGE);
-    }
-    /**
-     * Register a value once (only if not already set)
-     */
-    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);
-        }
-    }
-    // ============================================================================
-    // Utility Methods
-    // ============================================================================
-    /**
-     * Generate a new anonymous ID
-     */
-    generateAnonymousId() {
-        return `anon_${(0, utils_1.uuidv4)()}`;
-    }
-    /**
-     * Generate a new device ID
-     */
-    generateDeviceId() {
-        return `device_${(0, utils_1.uuidv4)()}`;
-    }
-    /**
-     * Get hash for person properties (for deduplication)
-     */
-    getPersonPropertiesHash(distinctId, userPropertiesToSet, userPropertiesToSetOnce) {
-        return JSON.stringify({
-            distinct_id: distinctId,
-            userPropertiesToSet,
-            userPropertiesToSetOnce,
-        });
-    }
-    /**
-     * Validate distinct ID
-     */
-    isValidDistinctId(distinctId) {
-        if (!distinctId || typeof distinctId !== "string") {
-            return false;
-        }
-        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;
-        }
-        if (distinctId.trim().length === 0) {
-            return false;
-        }
-        return true;
-    }
-    /**
-     * Check if distinct ID is string-like (hardcoded string)
-     */
-    isDistinctIdStringLike(distinctId) {
-        if (!distinctId || typeof distinctId !== "string") {
-            return false;
-        }
-        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);
-    }
-    // ============================================================================
-    // Storage Management
-    // ============================================================================
-    /**
-     * Update storage method at runtime
-     */
-    updateStorageMethod(method, cross_subdomain) {
-        this.storage = new storage_1.StorageManager({
-            method,
-            cross_subdomain,
-            sameSite: "Lax",
-        });
-        // Reload identity from new storage
-        this.userIdentity = this.loadUserIdentity();
-    }
-}
-exports.UserManager = UserManager;

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

@@ -1,52 +0,0 @@
-/**
- * Event utilities
- * Functions for extracting event properties, campaign parameters, and person info
- */
-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 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 information
- * Returns current referrer and referring domain
- */
-export declare function getReferrerInfo(): Record<string, any>;
-/**
- * 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 getPersonInfo(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): {
-    r: string;
-    u: string | undefined;
-};
-/**
- * Convert person info to person properties
- * Extracts referrer, URL, campaign params, and search info from stored person info
- */
-export declare function getPersonPropsFromInfo(info: Record<string, any>): Record<string, any>;
-/**
- * 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(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): Record<string, any>;