@v-tilt/browser 1.1.1 → 1.1.3

package/lib/storage.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * Unified Storage Manager - Following PostHog's PostHogPersistence pattern
+ *
+ * Single class handles all storage operations for both sessions and users.
+ * Reduces code duplication and ensures consistent cookie handling.
+ *
+ * Storage methods:
+ * - cookie: Browser cookies (cross-subdomain support)
+ * - localStorage: Persistent local storage
+ * - sessionStorage: Tab-specific storage (cleared on tab close)
+ * - localStorage+cookie: Both for redundancy
+ * - memory: In-memory only (no persistence)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageManager = exports.USER_COOKIE_MAX_AGE = exports.SESSION_COOKIE_MAX_AGE = void 0;
+exports.createStorageManager = createStorageManager;
+const constants_1 = require("./constants");
+const globals_1 = require("./utils/globals");
+// Default cookie TTLs
+exports.SESSION_COOKIE_MAX_AGE = 1800; // 30 minutes
+exports.USER_COOKIE_MAX_AGE = 31536000; // 1 year
+/**
+ * Unified Storage Manager
+ * Provides consistent storage operations across all persistence methods
+ */
+class StorageManager {
+    constructor(options) {
+        var _a;
+        this.memoryStorage = new Map();
+        this.method = options.method;
+        this.domain = options.domain;
+        this.sameSite = options.sameSite || "Lax";
+        // Auto-detect secure flag from protocol
+        this.secure =
+            (_a = options.secure) !== null && _a !== void 0 ? _a : (typeof location !== "undefined" && location.protocol === "https:");
+    }
+    // ============================================================================
+    // Public API - Simple key-value operations
+    // ============================================================================
+    /**
+     * Get a value from storage
+     */
+    get(key) {
+        var _a;
+        try {
+            if (this.method === constants_1.PERSISTENCE_METHODS.memory) {
+                return (_a = this.memoryStorage.get(key)) !== null && _a !== void 0 ? _a : null;
+            }
+            if (this.usesLocalStorage()) {
+                const value = localStorage.getItem(key);
+                if (value !== null)
+                    return value;
+                // Fall back to cookie for localStorage+cookie mode
+                if (this.method === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie) {
+                    return this.getCookie(key);
+                }
+                return null;
+            }
+            if (this.usesSessionStorage()) {
+                return sessionStorage.getItem(key);
+            }
+            // Cookie-only mode
+            return this.getCookie(key);
+        }
+        catch (error) {
+            console.warn(`[StorageManager] Failed to get "${key}":`, error);
+            return null;
+        }
+    }
+    /**
+     * Set a value in storage
+     * @param maxAge - Cookie max age in seconds (ignored for localStorage/sessionStorage)
+     */
+    set(key, value, maxAge) {
+        try {
+            if (this.method === constants_1.PERSISTENCE_METHODS.memory) {
+                this.memoryStorage.set(key, value);
+                return;
+            }
+            if (this.usesLocalStorage()) {
+                localStorage.setItem(key, value);
+                // Also set cookie for localStorage+cookie mode
+                if (this.method === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie) {
+                    this.setCookie(key, value, maxAge || exports.USER_COOKIE_MAX_AGE);
+                }
+                return;
+            }
+            if (this.usesSessionStorage()) {
+                sessionStorage.setItem(key, value);
+                return;
+            }
+            // Cookie-only mode
+            this.setCookie(key, value, maxAge || exports.USER_COOKIE_MAX_AGE);
+        }
+        catch (error) {
+            console.warn(`[StorageManager] Failed to set "${key}":`, error);
+        }
+    }
+    /**
+     * Remove a value from storage
+     */
+    remove(key) {
+        try {
+            if (this.method === constants_1.PERSISTENCE_METHODS.memory) {
+                this.memoryStorage.delete(key);
+                return;
+            }
+            if (this.usesLocalStorage()) {
+                localStorage.removeItem(key);
+                if (this.method === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie) {
+                    this.removeCookie(key);
+                }
+                return;
+            }
+            if (this.usesSessionStorage()) {
+                sessionStorage.removeItem(key);
+                return;
+            }
+            // Cookie-only mode
+            this.removeCookie(key);
+        }
+        catch (error) {
+            console.warn(`[StorageManager] Failed to remove "${key}":`, error);
+        }
+    }
+    // ============================================================================
+    // JSON operations with optional expiry (for session data)
+    // ============================================================================
+    /**
+     * Get JSON value with expiry check
+     * Returns null if expired or not found
+     */
+    getWithExpiry(key) {
+        const raw = this.get(key);
+        if (!raw)
+            return null;
+        try {
+            const item = JSON.parse(raw);
+            // Check expiry if set
+            if (item.expiry && Date.now() > item.expiry) {
+                this.remove(key);
+                return null;
+            }
+            return item.value;
+        }
+        catch (_a) {
+            // Not JSON or invalid format - return raw value if compatible
+            return null;
+        }
+    }
+    /**
+     * Set JSON value with optional expiry
+     * @param ttlMs - Time to live in milliseconds
+     */
+    setWithExpiry(key, value, ttlMs) {
+        const item = {
+            value,
+            ...(ttlMs ? { expiry: Date.now() + ttlMs } : {}),
+        };
+        this.set(key, JSON.stringify(item));
+    }
+    /**
+     * Get JSON value (no expiry check)
+     */
+    getJSON(key) {
+        const raw = this.get(key);
+        if (!raw)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    /**
+     * Set JSON value
+     */
+    setJSON(key, value, maxAge) {
+        this.set(key, JSON.stringify(value), maxAge);
+    }
+    // ============================================================================
+    // Cookie operations (internal)
+    // ============================================================================
+    getCookie(name) {
+        if (typeof document === "undefined")
+            return null;
+        const cookies = document.cookie.split(";");
+        for (const cookie of cookies) {
+            const [key, ...valueParts] = cookie.trim().split("=");
+            if (key === name) {
+                const value = valueParts.join("="); // Handle values with = in them
+                try {
+                    return decodeURIComponent(value);
+                }
+                catch (_a) {
+                    return value;
+                }
+            }
+        }
+        return null;
+    }
+    setCookie(name, value, maxAge) {
+        if (typeof document === "undefined")
+            return;
+        let cookieString = `${name}=${encodeURIComponent(value)}`;
+        cookieString += `; Max-Age=${maxAge}`;
+        cookieString += `; path=/`;
+        cookieString += `; SameSite=${this.sameSite}`;
+        if (this.secure) {
+            cookieString += `; Secure`;
+        }
+        if (this.domain) {
+            cookieString += `; domain=${this.domain}`;
+        }
+        document.cookie = cookieString;
+    }
+    removeCookie(name) {
+        if (typeof document === "undefined")
+            return;
+        // Set cookie with expired date
+        let cookieString = `${name}=; Max-Age=0; path=/`;
+        if (this.domain) {
+            cookieString += `; domain=${this.domain}`;
+        }
+        document.cookie = cookieString;
+        // Also try without domain (in case it was set without)
+        document.cookie = `${name}=; Max-Age=0; path=/`;
+    }
+    // ============================================================================
+    // Helper methods
+    // ============================================================================
+    usesLocalStorage() {
+        return (this.method === constants_1.PERSISTENCE_METHODS.localStorage ||
+            this.method === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie);
+    }
+    usesSessionStorage() {
+        return this.method === constants_1.PERSISTENCE_METHODS.sessionStorage;
+    }
+    /**
+     * Check if sessionStorage is available
+     */
+    canUseSessionStorage() {
+        if (typeof globals_1.window === "undefined" || !(globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.sessionStorage)) {
+            return false;
+        }
+        try {
+            const testKey = "__vt_storage_test__";
+            globals_1.window.sessionStorage.setItem(testKey, "test");
+            globals_1.window.sessionStorage.removeItem(testKey);
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    }
+    /**
+     * Get direct access to sessionStorage (for window_id which always uses sessionStorage)
+     */
+    getSessionStorage() {
+        var _a;
+        if (!this.canUseSessionStorage())
+            return null;
+        return (_a = globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.sessionStorage) !== null && _a !== void 0 ? _a : null;
+    }
+    /**
+     * Update storage method at runtime
+     */
+    setMethod(method) {
+        this.method = method;
+    }
+    /**
+     * Get current storage method
+     */
+    getMethod() {
+        return this.method;
+    }
+}
+exports.StorageManager = StorageManager;
+/**
+ * Create a shared storage instance
+ * Use this for creating storage managers with consistent settings
+ */
+function createStorageManager(method, domain) {
+    return new StorageManager({
+        method,
+        domain,
+        sameSite: "Lax",
+    });
+}

package/lib/types.d.ts

@@ -4,7 +4,7 @@
  * Type definitions for the VTilt tracking SDK.
  * Following PostHog's patterns where applicable.
  */
-import type { PersonProfilesMode } from './constants';
+import type { PersonProfilesMode } from "./constants";
 export interface VTiltConfig {
     /** Project identifier (required) */
     token: string;
@@ -42,9 +42,9 @@ export interface VTiltConfig {
     /** Enable web vitals tracking */
     capture_performance?: boolean;
     /** Enable page view tracking */
-    capture_pageview?: boolean | 'auto';
+    capture_pageview?: boolean | "auto";
     /** Enable page leave tracking */
-    capture_pageleave?: boolean | 'if_capture_pageview';
+    capture_pageleave?: boolean | "if_capture_pageview";
     /** Disable compression */
     disable_compression?: boolean;
     /** Whether to stringify payload before sending */
@@ -124,7 +124,7 @@ export interface SessionData {
  * - 'sessionStorage': Stores all data in sessionStorage
  * - 'memory': Stores all data in memory only (no persistence)
  */
-export type PersistenceMethod = 'localStorage+cookie' | 'cookie' | 'localStorage' | 'sessionStorage' | 'memory';
+export type PersistenceMethod = "localStorage+cookie" | "cookie" | "localStorage" | "sessionStorage" | "memory";
 /** User identity state */
 export interface UserIdentity {
     /** Current distinct ID (null if anonymous) */
@@ -136,7 +136,7 @@ export interface UserIdentity {
     /** User properties */
     properties: Properties;
     /** Identity state */
-    user_state: 'anonymous' | 'identified';
+    user_state: "anonymous" | "identified";
 }
 export interface UserProperties {
     [key: string]: any;
@@ -149,7 +149,7 @@ export interface WebVitalMetric {
     name: string;
     value: number;
     delta: number;
-    rating: 'good' | 'needs-improvement' | 'poor';
+    rating: "good" | "needs-improvement" | "poor";
     id: string;
     navigationType: string;
 }
@@ -164,10 +164,10 @@ export interface FeatureFlagsConfig {
     [flagKey: string]: boolean | string;
 }
 export type SessionIdChangedCallback = (newSessionId: string, previousSessionId: string | null, changeInfo: {
-    reason: 'timeout' | 'new_session' | 'reset';
+    reason: "timeout" | "new_session" | "reset";
 }) => void;
 export interface RequestOptions {
-    method?: 'POST' | 'GET';
+    method?: "POST" | "GET";
     headers?: Record<string, string>;
     timeout?: number;
     retry?: boolean;

package/lib/user-manager.d.ts

@@ -1,7 +1,18 @@
+/**
+ * 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"
+ */
 import { UserIdentity, AliasEvent, PersistenceMethod } from "./types";
 export declare class UserManager {
-    private storageMethod;
-    private domain?;
+    private storage;
     private userIdentity;
     private _cachedPersonProperties;
     constructor(storageMethod?: PersistenceMethod, domain?: string);
@@ -21,57 +32,31 @@ export declare class UserManager {
      * Get current user properties
      */
     getUserProperties(): Record<string, any>;
+    /**
+     * Get the effective ID for event tracking
+     */
+    getEffectiveId(): string;
+    /**
+     * Get current device ID
+     */
+    getDeviceId(): string;
+    /**
+     * Get current user state
+     */
+    getUserState(): "anonymous" | "identified";
     /**
      * Identify a user with distinct ID and properties
      */
     identify(newDistinctId?: string, userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
     /**
      * Set user properties without changing distinct ID
-     * 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?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): boolean;
-    /**
-     * Get hash for person properties
-     * Used for deduplication of identical setUserProperties calls
-     */
-    private getPersonPropertiesHash;
     /**
      * Reset user identity (logout)
      * 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?: boolean): void;
-    /**
-     * Get the effective ID for event tracking
-     */
-    getEffectiveId(): string;
-    /**
-     * Get current device ID
-     */
-    getDeviceId(): string;
-    /**
-     * Get current user state
-     */
-    getUserState(): "anonymous" | "identified";
     /**
      * Update distinct ID (internal use - for VTilt)
      */
@@ -88,29 +73,26 @@ export declare class UserManager {
      * Set device ID if not already set (internal use - for VTilt)
      */
     ensureDeviceId(deviceId: string): void;
+    /**
+     * Create an alias to link two distinct IDs
+     */
+    createAlias(alias: string, original?: string): AliasEvent | null;
     /**
      * Check if distinct ID is string-like (hardcoded string) - public for validation
-     * This is a wrapper to expose the private method
      */
     isDistinctIdStringLikePublic(distinctId: string): boolean;
     /**
-     * Create an alias to link two distinct IDs
-     * If original is not provided, uses current distinct_id
-     * If alias matches original, returns null (caller should use 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)
-     * @returns AliasEvent if alias was created, null if alias matches original or invalid
+     * Set initial person info
      */
-    createAlias(alias: string, original?: string): AliasEvent | null;
+    set_initial_person_info(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): void;
     /**
-     * Validate distinct ID to prevent hardcoded strings
+     * Get initial props
      */
-    private isValidDistinctId;
+    get_initial_props(): Record<string, any>;
     /**
-     * Check if distinct ID is string-like (hardcoded string)
+     * Update referrer info
      */
-    private isDistinctIdStringLike;
+    update_referrer_info(): void;
     /**
      * Load user identity from storage
      */
@@ -119,26 +101,6 @@ export declare class UserManager {
      * Save user identity to storage
      */
     private saveUserIdentity;
-    /**
-     * Generate a new anonymous ID
-     */
-    private generateAnonymousId;
-    /**
-     * Generate a new device ID
-     */
-    private generateDeviceId;
-    /**
-     * Get stored value from storage
-     */
-    private getStoredValue;
-    /**
-     * Set stored value in storage
-     */
-    private setStoredValue;
-    /**
-     * Remove stored value from storage
-     */
-    private removeStoredValue;
     /**
      * Get user properties from storage
      */
@@ -148,36 +110,31 @@ export declare class UserManager {
      */
     private setStoredUserProperties;
     /**
-     * Get cookie value
+     * Register a value once (only if not already set)
      */
-    private getCookieValue;
+    private register_once;
     /**
-     * Set cookie value
+     * Generate a new anonymous ID
      */
-    private setCookieValue;
+    private generateAnonymousId;
     /**
-     * Remove cookie value
+     * Generate a new device ID
      */
-    private removeCookieValue;
+    private generateDeviceId;
     /**
-     * Register a value once (only if not already set)
-     * Stores properties in localStorage only if they don't already exist
+     * Get hash for person properties (for deduplication)
      */
-    private register_once;
+    private getPersonPropertiesHash;
     /**
-     * Set initial person info
-     * Stores referrer and URL info on first visit for generating $initial_* properties
+     * Validate distinct ID
      */
-    set_initial_person_info(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): void;
+    private isValidDistinctId;
     /**
-     * Get initial props
-     * Generates $initial_* properties from stored initial person info
-     * These are sent with events as $set_once to preserve first values
+     * Check if distinct ID is string-like (hardcoded string)
      */
-    get_initial_props(): Record<string, any>;
+    private isDistinctIdStringLike;
     /**
-     * Update referrer info
-     * Stores current referrer information if not already stored
+     * Update storage method at runtime
      */
-    update_referrer_info(): void;
+    updateStorageMethod(method: PersistenceMethod, domain?: string): void;
 }