@v-tilt/browser 1.1.1 → 1.1.3

package/lib/session.d.ts

@@ -1,59 +1,41 @@
+/**
+ * Session Manager - Handles session_id and window_id
+ *
+ * Uses shared StorageManager for consistent storage operations.
+ *
+ * Session ID: Unique per user session, expires after 30 minutes of inactivity
+ * Window ID: Unique per browser tab, persists across page reloads
+ */
 import { PersistenceMethod } from "./types";
 export declare class SessionManager {
-    private storageMethod;
-    private domain?;
+    private storage;
     private _windowId;
     constructor(storageMethod?: PersistenceMethod, domain?: string);
     /**
-     * Check if using web storage (localStorage or sessionStorage)
-     */
-    private _isWebStorage;
-    /**
-     * Get storage object (localStorage or sessionStorage)
-     */
-    private _getStorage;
-    /**
-     * Create session data object with expiry
-     */
-    private _createSessionData;
-    /**
-     * Store session ID in web storage
-     */
-    private _storeSessionIdInWebStorage;
-    /**
-     * Get session ID from cookie
+     * Get session ID (always returns a value, generates if needed)
      */
-    private getSessionIdFromCookie;
+    getSessionId(): string;
     /**
-     * Set session ID in cookie
+     * Set session ID in storage
+     * Extends TTL if session_id exists, generates new one if not
      */
-    private setSessionIdFromCookie;
+    setSessionId(): string;
     /**
-     * Store session ID (in web storage or cookie)
+     * Reset session ID (generates new session on reset)
      */
-    private _storeSessionId;
+    resetSessionId(): void;
     /**
      * Get session ID from storage (raw, can return null)
-     * Private method used internally
      */
     private _getSessionIdRaw;
     /**
-     * Get session ID (always returns a value, generates if needed)
-     */
-    getSessionId(): string;
-    /**
-     * Set session ID in storage
-     * Extends TTL if session_id exists, generates new one if not
+     * Store session ID
      */
-    setSessionId(): string;
+    private _storeSessionId;
     /**
      * Clear session ID from storage
      */
     private _clearSessionId;
-    /**
-     * Reset session ID (generates new session on reset)
-     */
-    resetSessionId(): void;
     /**
      * Get window ID
      * Window ID is unique per browser tab/window and persists across page reloads
@@ -65,11 +47,6 @@ export declare class SessionManager {
      * Stores in sessionStorage which is unique per tab
      */
     private _setWindowId;
-    /**
-     * Check if we can use sessionStorage for window_id
-     * sessionStorage is unique per tab, perfect for window_id
-     */
-    private _canUseSessionStorage;
     /**
      * Initialize window ID
      * Detects tab duplication and handles window_id persistence
@@ -80,4 +57,8 @@ export declare class SessionManager {
      * This helps distinguish between page reloads and tab duplication
      */
     private _listenToUnload;
+    /**
+     * Update storage method at runtime
+     */
+    updateStorageMethod(method: PersistenceMethod, domain?: string): void;
 }

package/lib/session.js

@@ -1,118 +1,34 @@
 "use strict";
+/**
+ * Session Manager - Handles session_id and window_id
+ *
+ * Uses shared StorageManager for consistent storage operations.
+ *
+ * Session ID: Unique per user session, expires after 30 minutes of inactivity
+ * Window ID: Unique per browser tab, persists across page reloads
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionManager = void 0;
 const constants_1 = require("./constants");
 const utils_1 = require("./utils");
 const globals_1 = require("./utils/globals");
+const storage_1 = require("./storage");
+// Session TTL in milliseconds (30 minutes)
+const SESSION_TTL_MS = 30 * 60 * 1000;
 class SessionManager {
     constructor(storageMethod = "cookie", domain) {
-        this.storageMethod = storageMethod;
-        this.domain = domain;
+        this.storage = new storage_1.StorageManager({
+            method: storageMethod,
+            domain,
+            sameSite: "Lax",
+        });
         this._windowId = undefined;
         // Initialize window_id
         this._initializeWindowId();
     }
-    /**
-     * Check if using web storage (localStorage or sessionStorage)
-     */
-    _isWebStorage() {
-        return (this.storageMethod === constants_1.PERSISTENCE_METHODS.localStorage ||
-            this.storageMethod === constants_1.PERSISTENCE_METHODS.sessionStorage);
-    }
-    /**
-     * Get storage object (localStorage or sessionStorage)
-     */
-    _getStorage() {
-        if (!this._isWebStorage()) {
-            return null;
-        }
-        return this.storageMethod === constants_1.PERSISTENCE_METHODS.localStorage
-            ? localStorage
-            : sessionStorage;
-    }
-    /**
-     * Create session data object with expiry
-     */
-    _createSessionData(sessionId) {
-        const now = new Date();
-        return {
-            value: sessionId,
-            expiry: now.getTime() + 1800 * 1000, // 30 minutes
-        };
-    }
-    /**
-     * Store session ID in web storage
-     */
-    _storeSessionIdInWebStorage(sessionId) {
-        const storage = this._getStorage();
-        if (!storage) {
-            return;
-        }
-        const item = this._createSessionData(sessionId);
-        storage.setItem(constants_1.STORAGE_KEY, JSON.stringify(item));
-    }
-    /**
-     * Get session ID from cookie
-     */
-    getSessionIdFromCookie() {
-        const cookie = {};
-        document.cookie.split(";").forEach(function (el) {
-            const [key, value] = el.split("=");
-            cookie[key.trim()] = value;
-        });
-        return cookie[constants_1.STORAGE_KEY] || null;
-    }
-    /**
-     * Set session ID in cookie
-     */
-    setSessionIdFromCookie(sessionId) {
-        let cookieValue = `${constants_1.STORAGE_KEY}=${sessionId}; Max-Age=1800; path=/; secure`;
-        if (this.domain) {
-            cookieValue += `; domain=${this.domain}`;
-        }
-        document.cookie = cookieValue;
-    }
-    /**
-     * Store session ID (in web storage or cookie)
-     */
-    _storeSessionId(sessionId) {
-        if (this._isWebStorage()) {
-            this._storeSessionIdInWebStorage(sessionId);
-        }
-        else {
-            this.setSessionIdFromCookie(sessionId);
-        }
-    }
-    /**
-     * Get session ID from storage (raw, can return null)
-     * Private method used internally
-     */
-    _getSessionIdRaw() {
-        const storage = this._getStorage();
-        if (storage) {
-            const serializedItem = storage.getItem(constants_1.STORAGE_KEY);
-            if (!serializedItem) {
-                return null;
-            }
-            let item = null;
-            try {
-                item = JSON.parse(serializedItem);
-            }
-            catch (_a) {
-                return null;
-            }
-            if (typeof item !== "object" || item === null) {
-                return null;
-            }
-            const now = new Date();
-            if (now.getTime() > item.expiry) {
-                storage.removeItem(constants_1.STORAGE_KEY);
-                return null;
-            }
-            return item.value;
-        }
-        return this.getSessionIdFromCookie();
-    }
+    // ============================================================================
+    // Session ID Operations
+    // ============================================================================
     /**
      * Get session ID (always returns a value, generates if needed)
      */
@@ -139,23 +55,6 @@ class SessionManager {
         this._storeSessionId(sessionId);
         return sessionId;
     }
-    /**
-     * Clear session ID from storage
-     */
-    _clearSessionId() {
-        const storage = this._getStorage();
-        if (storage) {
-            storage.removeItem(constants_1.STORAGE_KEY);
-        }
-        else {
-            // Clear cookie
-            const expires = "Thu, 01 Jan 1970 00:00:00 UTC";
-            document.cookie = `${constants_1.STORAGE_KEY}=; expires=${expires}; path=/;`;
-            if (this.domain) {
-                document.cookie = `${constants_1.STORAGE_KEY}=; expires=${expires}; path=/; domain=${this.domain};`;
-            }
-        }
-    }
     /**
      * Reset session ID (generates new session on reset)
      */
@@ -165,6 +64,61 @@ class SessionManager {
         this.setSessionId();
         this._setWindowId((0, utils_1.uuidv4)());
     }
+    /**
+     * Get session ID from storage (raw, can return null)
+     */
+    _getSessionIdRaw() {
+        // Use getWithExpiry for localStorage/sessionStorage (handles JSON + expiry)
+        const sessionData = this.storage.getWithExpiry(constants_1.STORAGE_KEY);
+        if (sessionData) {
+            return sessionData;
+        }
+        // For cookie mode, the cookie itself handles expiry via Max-Age
+        // Just get the raw value
+        const rawValue = this.storage.get(constants_1.STORAGE_KEY);
+        if (rawValue) {
+            // Check if it's JSON format (from web storage) or plain string (from cookie)
+            try {
+                const parsed = JSON.parse(rawValue);
+                // If it's a StorageItem, extract value and check expiry
+                if (typeof parsed === "object" &&
+                    parsed !== null &&
+                    "value" in parsed) {
+                    if (parsed.expiry && Date.now() > parsed.expiry) {
+                        this.storage.remove(constants_1.STORAGE_KEY);
+                        return null;
+                    }
+                    return parsed.value;
+                }
+                return rawValue;
+            }
+            catch (_a) {
+                // Plain string value (from cookie)
+                return rawValue;
+            }
+        }
+        return null;
+    }
+    /**
+     * Store session ID
+     */
+    _storeSessionId(sessionId) {
+        // Use setWithExpiry for localStorage/sessionStorage
+        // For cookies, the StorageManager handles Max-Age
+        this.storage.setWithExpiry(sessionId, sessionId, SESSION_TTL_MS);
+        // Also set as plain cookie for cookie mode (overwrites JSON format)
+        // This ensures cookies work properly with Max-Age
+        this.storage.set(constants_1.STORAGE_KEY, sessionId, storage_1.SESSION_COOKIE_MAX_AGE);
+    }
+    /**
+     * Clear session ID from storage
+     */
+    _clearSessionId() {
+        this.storage.remove(constants_1.STORAGE_KEY);
+    }
+    // ============================================================================
+    // Window ID Operations
+    // ============================================================================
     /**
      * Get window ID
      * Window ID is unique per browser tab/window and persists across page reloads
@@ -175,8 +129,9 @@ class SessionManager {
             return this._windowId;
         }
         // Try to get from sessionStorage (unique per tab)
-        if (this._canUseSessionStorage() && globals_1.window) {
-            const windowId = globals_1.window.sessionStorage.getItem(constants_1.WINDOW_ID_KEY);
+        const sessionStorage = this.storage.getSessionStorage();
+        if (sessionStorage) {
+            const windowId = sessionStorage.getItem(constants_1.WINDOW_ID_KEY);
             if (windowId) {
                 this._windowId = windowId;
                 return windowId;
@@ -194,35 +149,19 @@ class SessionManager {
     _setWindowId(windowId) {
         if (windowId !== this._windowId) {
             this._windowId = windowId;
-            if (this._canUseSessionStorage() && globals_1.window) {
-                globals_1.window.sessionStorage.setItem(constants_1.WINDOW_ID_KEY, windowId);
+            const sessionStorage = this.storage.getSessionStorage();
+            if (sessionStorage) {
+                sessionStorage.setItem(constants_1.WINDOW_ID_KEY, windowId);
             }
         }
     }
-    /**
-     * Check if we can use sessionStorage for window_id
-     * sessionStorage is unique per tab, perfect for window_id
-     */
-    _canUseSessionStorage() {
-        if (typeof globals_1.window === "undefined" || !globals_1.window.sessionStorage) {
-            return false;
-        }
-        try {
-            const testKey = "__vt_session_storage_test__";
-            globals_1.window.sessionStorage.setItem(testKey, "test");
-            globals_1.window.sessionStorage.removeItem(testKey);
-            return true;
-        }
-        catch (_a) {
-            return false;
-        }
-    }
     /**
      * Initialize window ID
      * Detects tab duplication and handles window_id persistence
      */
     _initializeWindowId() {
-        if (!this._canUseSessionStorage() || !globals_1.window) {
+        const sessionStorage = this.storage.getSessionStorage();
+        if (!sessionStorage) {
             // Fallback: generate window_id in memory (won't persist across reloads)
             this._windowId = (0, utils_1.uuidv4)();
             return;
@@ -230,8 +169,8 @@ class SessionManager {
         // Check if primary window exists flag is set
         // If it exists, this means the tab was duplicated/cloned (window.open, tab duplication, etc.)
         // If it doesn't exist, this is a fresh/reloaded tab
-        const primaryWindowExists = globals_1.window.sessionStorage.getItem(constants_1.PRIMARY_WINDOW_EXISTS_KEY);
-        const lastWindowId = globals_1.window.sessionStorage.getItem(constants_1.WINDOW_ID_KEY);
+        const primaryWindowExists = sessionStorage.getItem(constants_1.PRIMARY_WINDOW_EXISTS_KEY);
+        const lastWindowId = sessionStorage.getItem(constants_1.WINDOW_ID_KEY);
         if (lastWindowId && !primaryWindowExists) {
             // Tab was reloaded - reuse the window_id from sessionStorage
             this._windowId = lastWindowId;
@@ -240,13 +179,13 @@ class SessionManager {
             // New tab or duplicated tab - generate new window_id
             if (lastWindowId) {
                 // Clear old window_id (this is a duplicated tab)
-                globals_1.window.sessionStorage.removeItem(constants_1.WINDOW_ID_KEY);
+                sessionStorage.removeItem(constants_1.WINDOW_ID_KEY);
             }
             // Generate new window_id
             this._setWindowId((0, utils_1.uuidv4)());
         }
         // Flag this session as having a primary window
-        globals_1.window.sessionStorage.setItem(constants_1.PRIMARY_WINDOW_EXISTS_KEY, "true");
+        sessionStorage.setItem(constants_1.PRIMARY_WINDOW_EXISTS_KEY, "true");
         // Listen for page unload to clear the primary window flag
         // This allows us to detect tab duplication vs page reload
         this._listenToUnload();
@@ -256,16 +195,31 @@ class SessionManager {
      * This helps distinguish between page reloads and tab duplication
      */
     _listenToUnload() {
-        if (!globals_1.window || !this._canUseSessionStorage()) {
+        const sessionStorage = this.storage.getSessionStorage();
+        if (!globals_1.window || !sessionStorage) {
             return;
         }
         (0, utils_1.addEventListener)(globals_1.window, "beforeunload", () => {
             // Clear the primary window flag on unload
             // Reloaded tabs won't have this flag, duplicated tabs will
-            if (globals_1.window && globals_1.window.sessionStorage) {
-                globals_1.window.sessionStorage.removeItem(constants_1.PRIMARY_WINDOW_EXISTS_KEY);
+            const ss = this.storage.getSessionStorage();
+            if (ss) {
+                ss.removeItem(constants_1.PRIMARY_WINDOW_EXISTS_KEY);
             }
         }, { capture: false });
     }
+    // ============================================================================
+    // Storage Management
+    // ============================================================================
+    /**
+     * Update storage method at runtime
+     */
+    updateStorageMethod(method, domain) {
+        this.storage = new storage_1.StorageManager({
+            method,
+            domain,
+            sameSite: "Lax",
+        });
+    }
 }
 exports.SessionManager = SessionManager;

package/lib/storage.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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)
+ */
+import { PersistenceMethod } from "./types";
+export declare const SESSION_COOKIE_MAX_AGE = 1800;
+export declare const USER_COOKIE_MAX_AGE = 31536000;
+export interface StorageOptions {
+    method: PersistenceMethod;
+    domain?: string;
+    secure?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+export interface StorageItem<T = string> {
+    value: T;
+    expiry?: number;
+}
+/**
+ * Unified Storage Manager
+ * Provides consistent storage operations across all persistence methods
+ */
+export declare class StorageManager {
+    private method;
+    private domain?;
+    private secure;
+    private sameSite;
+    private memoryStorage;
+    constructor(options: StorageOptions);
+    /**
+     * Get a value from storage
+     */
+    get(key: string): string | null;
+    /**
+     * Set a value in storage
+     * @param maxAge - Cookie max age in seconds (ignored for localStorage/sessionStorage)
+     */
+    set(key: string, value: string, maxAge?: number): void;
+    /**
+     * Remove a value from storage
+     */
+    remove(key: string): void;
+    /**
+     * Get JSON value with expiry check
+     * Returns null if expired or not found
+     */
+    getWithExpiry<T>(key: string): T | null;
+    /**
+     * Set JSON value with optional expiry
+     * @param ttlMs - Time to live in milliseconds
+     */
+    setWithExpiry<T>(key: string, value: T, ttlMs?: number): void;
+    /**
+     * Get JSON value (no expiry check)
+     */
+    getJSON<T>(key: string): T | null;
+    /**
+     * Set JSON value
+     */
+    setJSON<T>(key: string, value: T, maxAge?: number): void;
+    private getCookie;
+    private setCookie;
+    private removeCookie;
+    private usesLocalStorage;
+    private usesSessionStorage;
+    /**
+     * Check if sessionStorage is available
+     */
+    canUseSessionStorage(): boolean;
+    /**
+     * Get direct access to sessionStorage (for window_id which always uses sessionStorage)
+     */
+    getSessionStorage(): Storage | null;
+    /**
+     * Update storage method at runtime
+     */
+    setMethod(method: PersistenceMethod): void;
+    /**
+     * Get current storage method
+     */
+    getMethod(): PersistenceMethod;
+}
+/**
+ * Create a shared storage instance
+ * Use this for creating storage managers with consistent settings
+ */
+export declare function createStorageManager(method: PersistenceMethod, domain?: string): StorageManager;