@v-tilt/browser 1.4.3 → 1.4.4

package/dist/storage.d.ts

@@ -1,23 +1,41 @@
 /**
- * Unified Storage Manager - Following PostHog's PostHogPersistence pattern
+ * Unified Storage Manager
  *
- * Single class handles all storage operations for both sessions and users.
- * Reduces code duplication and ensures consistent cookie handling.
+ * Handles all storage operations for sessions and users with consistent
+ * cookie handling across different persistence methods.
  *
  * 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)
+ * - `cookie`: Browser cookies with cross-subdomain support
+ * - `localStorage`: Persistent local storage
+ * - `sessionStorage`: Tab-specific storage (cleared on tab close)
+ * - `localStorage+cookie`: Hybrid mode (default) - full data in localStorage,
+ *   critical identity properties also in cookies for SSR support
+ * - `memory`: In-memory only (no persistence)
+ *
+ * The `localStorage+cookie` mode is designed for traditional server-side
+ * rendered websites where each page navigation reloads JavaScript:
+ * - Critical properties (anonymous_id, device_id, etc.) are stored in cookies
+ * - Cookies ensure identity persists across full page reloads
+ * - localStorage provides fast access for SPA-style navigation
+ * - Falls back to cookie-only if localStorage is unavailable
  */
 import { PersistenceMethod } from "./types";
+/**
+ * Critical properties persisted to cookies in `localStorage+cookie` mode.
+ * These ensure identity survives full page reloads in traditional SSR websites.
+ */
+export declare const COOKIE_PERSISTED_PROPERTIES: readonly ["__vt_anonymous_id", "__vt_device_id", "__vt_distinct_id", "__vt_user_state"];
+/** Session cookie TTL: 30 minutes */
 export declare const SESSION_COOKIE_MAX_AGE = 1800;
+/** User cookie TTL: 1 year */
 export declare const USER_COOKIE_MAX_AGE = 31536000;
 export interface StorageOptions {
     method: PersistenceMethod;
+    /** Enable cross-subdomain cookies (auto-detected if not specified) */
     cross_subdomain?: boolean;
+    /** Use secure cookies (auto-detected from protocol if not specified) */
     secure?: boolean;
+    /** Cookie SameSite attribute */
     sameSite?: "Strict" | "Lax" | "None";
 }
 export interface StorageItem<T = string> {
@@ -25,13 +43,15 @@ export interface StorageItem<T = string> {
     expiry?: number;
 }
 /**
- * Auto-detect if cross-subdomain cookies should be enabled
- * Returns false for platforms like herokuapp.com, vercel.app, netlify.app
+ * Check if cross-subdomain cookies should be enabled.
+ * Returns false for shared hosting platforms to prevent cookie conflicts.
  */
 export declare function shouldUseCrossSubdomainCookie(): boolean;
 /**
  * Unified Storage Manager
+ *
  * Provides consistent storage operations across all persistence methods
+ * with automatic fallbacks and SSR support.
  */
 export declare class StorageManager {
     private method;
@@ -39,62 +59,59 @@ export declare class StorageManager {
     private secure;
     private sameSite;
     private memoryStorage;
+    private _localStorageSupported;
     constructor(options: StorageOptions);
+    /** Check if localStorage is available (result is cached) */
+    private isLocalStorageSupported;
+    /** Check if a key should be persisted to cookies */
+    private isCriticalProperty;
     /**
-     * Get a value from storage
+     * Get a value from storage.
+     *
+     * For `localStorage+cookie` mode:
+     * - Critical properties: read cookie first (for SSR), fall back to localStorage
+     * - Non-critical properties: read from localStorage only
      */
     get(key: string): string | null;
     /**
-     * Set a value in storage
-     * @param maxAge - Cookie max age in seconds (ignored for localStorage/sessionStorage)
+     * Set a value in storage.
+     * @param maxAge Cookie max age in seconds (only for cookie-based storage)
+     *
+     * For `localStorage+cookie` mode:
+     * - All values stored in localStorage (if available)
+     * - Critical properties ALWAYS stored in cookies for SSR support
      */
     set(key: string, value: string, maxAge?: number): void;
-    /**
-     * Remove a value from storage
-     */
+    /** Remove a value from storage */
     remove(key: string): void;
-    /**
-     * Get JSON value with expiry check
-     * Returns null if expired or not found
-     */
+    private getLocalStoragePlusCookie;
+    private setLocalStoragePlusCookie;
+    private removeLocalStoragePlusCookie;
+    private getLocalStorage;
+    private setLocalStorage;
+    private removeLocalStorage;
+    private readFromSessionStorage;
+    private writeToSessionStorage;
+    private removeFromSessionStorage;
+    private getCookie;
+    private setCookie;
+    private removeCookie;
+    /** Get JSON value with expiry check */
     getWithExpiry<T>(key: string): T | null;
-    /**
-     * Set JSON value with optional expiry
-     * @param ttlMs - Time to live in milliseconds
-     */
+    /** Set JSON value with optional TTL */
     setWithExpiry<T>(key: string, value: T, ttlMs?: number): void;
-    /**
-     * Get JSON value (no expiry check)
-     */
+    /** Get parsed JSON value */
     getJSON<T>(key: string): T | null;
-    /**
-     * Set JSON value
-     */
+    /** 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
-     */
+    /** Check if sessionStorage is available */
     canUseSessionStorage(): boolean;
-    /**
-     * Get direct access to sessionStorage (for window_id which always uses sessionStorage)
-     */
+    /** Get sessionStorage instance (for window_id which always uses sessionStorage) */
     getSessionStorage(): Storage | null;
-    /**
-     * Update storage method at runtime
-     */
+    /** Update storage method at runtime */
     setMethod(method: PersistenceMethod): void;
-    /**
-     * Get current storage method
-     */
+    /** Get current storage method */
     getMethod(): PersistenceMethod;
 }
-/**
- * Create a shared storage instance
- * Use this for creating storage managers with consistent settings
- */
+/** Factory function to create a StorageManager with default settings */
 export declare function createStorageManager(method: PersistenceMethod, cross_subdomain?: boolean): StorageManager;

package/dist/user-manager.d.ts

@@ -94,7 +94,21 @@ export declare class UserManager {
      */
     update_referrer_info(): void;
     /**
-     * Load user identity from storage
+     * 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
      */
     private loadUserIdentity;
     /**

package/lib/entrypoints/external-scripts-loader.js

@@ -72,7 +72,7 @@ exports.loadScript = loadScript;
 /**
  * SDK version - used for loading correct script version from CDN
  */
-const SDK_VERSION = "1.4.3";
+const SDK_VERSION = "1.4.4";
 /**
  * Get the URL for an extension script
  *

package/lib/extensions/chat/chat-wrapper.d.ts

@@ -31,7 +31,7 @@
  * Code config always takes precedence over dashboard settings.
  */
 import type { VTilt } from "../../vtilt";
-import type { ChatConfig, ChatChannelSummary, ChatWidgetView } from "../../utils/globals";
+import { type ChatConfig, type ChatChannelSummary, type ChatWidgetView } from "../../utils/globals";
 import type { MessageCallback, TypingCallback, ConnectionCallback, Unsubscribe } from "./types";
 /** Status when lazy loading is in progress */
 export declare const CHAT_LOADING: "loading";

package/lib/extensions/chat/chat-wrapper.js

@@ -352,13 +352,16 @@ class ChatWrapper {
     get _isChatEnabled() {
         var _a;
         // Code config takes precedence
-        if (this._config.enabled === false)
+        if (this._config.enabled === false) {
             return false;
-        if (this._config.enabled === true)
+        }
+        if (this._config.enabled === true) {
             return true;
+        }
         // Fall back to server config
-        if (((_a = this._serverConfig) === null || _a === void 0 ? void 0 : _a.enabled) === true)
+        if (((_a = this._serverConfig) === null || _a === void 0 ? void 0 : _a.enabled) === true) {
             return true;
+        }
         // Default: disabled unless explicitly enabled
         return false;
     }
@@ -367,8 +370,9 @@ class ChatWrapper {
      * This enables "snippet-only" installation where widget configures from dashboard
      */
     async _fetchServerSettings() {
-        if (this._configFetched)
+        if (this._configFetched) {
             return;
+        }
         const config = this._instance.getConfig();
         const token = config.token;
         const apiHost = config.api_host;
@@ -399,11 +403,13 @@ class ChatWrapper {
      * This creates a lightweight bubble that loads the full widget on click
      */
     _showBubble() {
-        if (!(globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.document))
+        if (!(globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.document)) {
             return;
+        }
         // Don't create if already exists
-        if (document.getElementById("vtilt-chat-bubble"))
+        if (document.getElementById("vtilt-chat-bubble")) {
             return;
+        }
         const mergedConfig = this.getMergedConfig();
         const position = mergedConfig.position || "bottom-right";
         const color = mergedConfig.color || "#6366f1";

package/lib/extensions/chat/chat.d.ts

@@ -2,8 +2,8 @@
  * Chat Widget - Lazy loaded chat implementation using Ably for real-time messaging.
  */
 import type { VTilt } from "../../vtilt";
-import type { ChatConfig, ChatChannel, ChatChannelSummary, ChatWidgetView, LazyLoadedChatInterface } from "../../utils/globals";
-import type { MessageCallback, TypingCallback, ConnectionCallback, Unsubscribe } from "./types";
+import { type ChatConfig, type ChatChannel, type ChatChannelSummary, type ChatWidgetView, type LazyLoadedChatInterface } from "../../utils/globals";
+import { type MessageCallback, type TypingCallback, type ConnectionCallback, type Unsubscribe } from "./types";
 export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     private _instance;
     private _config;

package/lib/extensions/chat/chat.js

@@ -117,8 +117,9 @@ class LazyLoadedChat {
     // ============================================================================
     open() {
         var _a;
-        if (this._state.isOpen)
+        if (this._state.isOpen) {
             return;
+        }
         this._state.isOpen = true;
         this._updateUI();
         // Add opening animation
@@ -136,8 +137,9 @@ class LazyLoadedChat {
         }
     }
     close() {
-        if (!this._state.isOpen)
+        if (!this._state.isOpen) {
             return;
+        }
         const timeOpen = this._getTimeOpen();
         // Add closing animation
         if (this._widget) {
@@ -210,11 +212,13 @@ class LazyLoadedChat {
                 this._state.channel = response.channel;
                 this._state.messages = response.messages || [];
                 this._state.currentView = "conversation";
-                this._state.agentLastReadAt = response.channel.agent_last_read_at || null;
+                this._state.agentLastReadAt =
+                    response.channel.agent_last_read_at || null;
                 this._initialUserReadAt = response.channel.user_last_read_at || null;
                 this._connectRealtime();
-                if (this._state.isOpen)
+                if (this._state.isOpen) {
                     this._autoMarkAsRead();
+                }
             }
         }
         catch (error) {
@@ -242,7 +246,8 @@ class LazyLoadedChat {
                 this._state.channel = response.channel;
                 this._state.messages = response.messages || [];
                 this._state.currentView = "conversation";
-                this._state.agentLastReadAt = response.channel.agent_last_read_at || null;
+                this._state.agentLastReadAt =
+                    response.channel.agent_last_read_at || null;
                 this._initialUserReadAt = response.channel.user_last_read_at || null;
                 const newChannelSummary = {
                     id: response.channel.id,
@@ -286,7 +291,8 @@ class LazyLoadedChat {
                         ? this._state.messages[this._state.messages.length - 1].content.substring(0, 100)
                         : this._state.channels[channelIndex].last_message_preview,
                     last_message_sender: this._state.messages.length > 0
-                        ? this._state.messages[this._state.messages.length - 1].sender_type
+                        ? this._state.messages[this._state.messages.length - 1]
+                            .sender_type
                         : this._state.channels[channelIndex].last_message_sender,
                     unread_count: 0, // We just viewed it
                 };
@@ -304,8 +310,9 @@ class LazyLoadedChat {
     // ============================================================================
     async sendMessage(content) {
         var _a, _b, _c, _d;
-        if (!content.trim())
+        if (!content.trim()) {
             return;
+        }
         // Ensure we're in conversation view with a channel
         if (!this._state.channel || this._state.currentView !== "conversation") {
             console.error(`${LOGGER_PREFIX} Cannot send message: not in conversation view`);
@@ -367,14 +374,18 @@ class LazyLoadedChat {
         this._autoMarkAsRead();
     }
     _autoMarkAsRead() {
-        if (!this._state.channel || this._isMarkingRead)
+        if (!this._state.channel || this._isMarkingRead) {
             return;
+        }
         const latestMessage = this._state.messages[this._state.messages.length - 1];
-        if (!latestMessage)
+        if (!latestMessage) {
             return;
-        const hasUnreadAgentMessages = this._state.messages.some((m) => (m.sender_type === "agent" || m.sender_type === "ai") && !this._isMessageReadByUser(m.created_at));
-        if (!hasUnreadAgentMessages)
+        }
+        const hasUnreadAgentMessages = this._state.messages.some((m) => (m.sender_type === "agent" || m.sender_type === "ai") &&
+            !this._isMessageReadByUser(m.created_at));
+        if (!hasUnreadAgentMessages) {
             return;
+        }
         this._state.unreadCount = 0;
         this._isMarkingRead = true;
         this._updateUI();
@@ -397,8 +408,9 @@ class LazyLoadedChat {
         });
     }
     _isMessageReadByUser(messageCreatedAt) {
-        if (!this._initialUserReadAt)
+        if (!this._initialUserReadAt) {
             return false;
+        }
         return new Date(messageCreatedAt) <= new Date(this._initialUserReadAt);
     }
     // ============================================================================
@@ -408,24 +420,27 @@ class LazyLoadedChat {
         this._messageCallbacks.push(callback);
         return () => {
             const index = this._messageCallbacks.indexOf(callback);
-            if (index > -1)
+            if (index > -1) {
                 this._messageCallbacks.splice(index, 1);
+            }
         };
     }
     onTyping(callback) {
         this._typingCallbacks.push(callback);
         return () => {
             const index = this._typingCallbacks.indexOf(callback);
-            if (index > -1)
+            if (index > -1) {
                 this._typingCallbacks.splice(index, 1);
+            }
         };
     }
     onConnectionChange(callback) {
         this._connectionCallbacks.push(callback);
         return () => {
             const index = this._connectionCallbacks.indexOf(callback);
-            if (index > -1)
+            if (index > -1) {
                 this._connectionCallbacks.splice(index, 1);
+            }
         };
     }
     // ============================================================================
@@ -434,8 +449,9 @@ class LazyLoadedChat {
     destroy() {
         var _a;
         this._disconnectRealtime();
-        if (this._typingDebounce)
+        if (this._typingDebounce) {
             clearTimeout(this._typingDebounce);
+        }
         if ((_a = this._container) === null || _a === void 0 ? void 0 : _a.parentNode) {
             this._container.parentNode.removeChild(this._container);
         }
@@ -549,11 +565,15 @@ class LazyLoadedChat {
         return parts[0] || "";
     }
     _handleNewMessage(message) {
-        if (this._state.messages.some((m) => m.id === message.id))
+        if (this._state.messages.some((m) => m.id === message.id)) {
             return;
+        }
         // Skip own messages but replace temp message if present
-        if (message.sender_type === "user" && message.sender_id === this._distinctId) {
-            const tempIndex = this._state.messages.findIndex((m) => m.id.startsWith("temp-") && m.content === message.content && m.sender_type === "user");
+        if (message.sender_type === "user" &&
+            message.sender_id === this._distinctId) {
+            const tempIndex = this._state.messages.findIndex((m) => m.id.startsWith("temp-") &&
+                m.content === message.content &&
+                m.sender_type === "user");
             if (tempIndex !== -1) {
                 this._state.messages[tempIndex] = message;
                 this._updateUI();
@@ -581,17 +601,20 @@ class LazyLoadedChat {
         this._updateUI();
     }
     _handleTypingEvent(event) {
-        if (event.sender_type === "user")
+        if (event.sender_type === "user") {
             return;
-        const senderName = event.sender_name || (event.sender_type === "ai" ? "AI Assistant" : "Agent");
+        }
+        const senderName = event.sender_name ||
+            (event.sender_type === "ai" ? "AI Assistant" : "Agent");
         this._state.isTyping = event.is_typing;
         this._state.typingSender = event.is_typing ? senderName : null;
         this._typingCallbacks.forEach((cb) => cb(event.is_typing, senderName));
         this._updateUI();
     }
     _handleReadCursorEvent(event) {
-        if (event.reader_type !== "agent")
+        if (event.reader_type !== "agent") {
             return;
+        }
         this._state.agentLastReadAt = event.read_at;
         this._updateUI();
     }
@@ -602,8 +625,9 @@ class LazyLoadedChat {
     // Private - UI
     // ============================================================================
     _createUI() {
-        if (!globals_1.document)
+        if (!globals_1.document) {
             return;
+        }
         this._container = globals_1.document.createElement("div");
         this._container.id = "vtilt-chat-container";
         this._container.setAttribute("style", this._getContainerStyles());
@@ -625,22 +649,25 @@ class LazyLoadedChat {
         (_c = (_b = this._widget) === null || _b === void 0 ? void 0 : _b.querySelector(".vtilt-chat-close")) === null || _c === void 0 ? void 0 : _c.addEventListener("click", () => this.close());
     }
     _handleUserTyping() {
-        if (!this._typingChannel)
+        if (!this._typingChannel) {
             return;
+        }
         if (!this._isUserTyping) {
             this._isUserTyping = true;
             this._sendTypingIndicator(true);
         }
-        if (this._typingDebounce)
+        if (this._typingDebounce) {
             clearTimeout(this._typingDebounce);
+        }
         this._typingDebounce = setTimeout(() => {
             this._isUserTyping = false;
             this._sendTypingIndicator(false);
         }, 2000);
     }
     _sendTypingIndicator(isTyping) {
-        if (!this._typingChannel)
+        if (!this._typingChannel) {
             return;
+        }
         try {
             this._typingChannel.publish("typing", {
                 sender_type: "user",
@@ -656,8 +683,9 @@ class LazyLoadedChat {
     _handleSend() {
         var _a;
         const input = (_a = this._widget) === null || _a === void 0 ? void 0 : _a.querySelector(".vtilt-chat-input");
-        if (!input)
+        if (!input) {
             return;
+        }
         const content = input.value.trim();
         if (content) {
             if (this._isUserTyping) {
@@ -673,8 +701,9 @@ class LazyLoadedChat {
         }
     }
     _updateUI() {
-        if (!this._container || !this._widget || !this._bubble)
+        if (!this._container || !this._widget || !this._bubble) {
             return;
+        }
         // Update visibility
         this._container.style.display = this._state.isVisible ? "block" : "none";
         // Update widget open state
@@ -724,8 +753,9 @@ class LazyLoadedChat {
     _updateHeader() {
         var _a, _b;
         const header = (_a = this._widget) === null || _a === void 0 ? void 0 : _a.querySelector(".vtilt-chat-header");
-        if (!header)
+        if (!header) {
             return;
+        }
         const greeting = this._config.greeting || "Messages";
         const primary = this._theme.primaryColor;
         if (this._state.currentView === "list") {
@@ -981,15 +1011,17 @@ class LazyLoadedChat {
               flex: 1;
               min-width: 0;
               line-height: 1.4;
-            ">${senderPrefix}${this._escapeHTML(preview)}${channel.status === "closed" ? ' · Closed' : ""}</div>
-            ${hasUnread ? `<div style="
+            ">${senderPrefix}${this._escapeHTML(preview)}${channel.status === "closed" ? " · Closed" : ""}</div>
+            ${hasUnread
+            ? `<div style="
               min-width: 10px;
               width: 10px;
               height: 10px;
               background: ${primary};
               border-radius: 50%;
               flex-shrink: 0;
-            "></div>` : ""}
+            "></div>`
+            : ""}
           </div>
         </div>
       </div>
@@ -1097,8 +1129,9 @@ class LazyLoadedChat {
         (_d = (_c = this._widget) === null || _c === void 0 ? void 0 : _c.querySelectorAll(".vtilt-channel-item")) === null || _d === void 0 ? void 0 : _d.forEach((item) => {
             item.addEventListener("click", () => {
                 const channelId = item.getAttribute("data-channel-id");
-                if (channelId)
+                if (channelId) {
                     this.selectChannel(channelId);
+                }
             });
         });
     }
@@ -1121,29 +1154,37 @@ class LazyLoadedChat {
         const diffMins = Math.floor(diffMs / 60000);
         const diffHours = Math.floor(diffMs / 3600000);
         const diffDays = Math.floor(diffMs / 86400000);
-        if (diffMins < 1)
+        if (diffMins < 1) {
             return "Just now";
-        if (diffMins < 60)
+        }
+        if (diffMins < 60) {
             return `${diffMins}m ago`;
-        if (diffHours < 24)
+        }
+        if (diffHours < 24) {
             return `${diffHours}h ago`;
-        if (diffDays < 7)
+        }
+        if (diffDays < 7) {
             return `${diffDays}d ago`;
+        }
         return date.toLocaleDateString();
     }
     _renderMessages() {
         var _a;
         const container = (_a = this._widget) === null || _a === void 0 ? void 0 : _a.querySelector(".vtilt-chat-messages");
-        if (!container)
+        if (!container) {
             return;
+        }
         const primary = this._theme.primaryColor;
-        const firstUnreadIndex = this._state.messages.findIndex((m) => (m.sender_type === "agent" || m.sender_type === "ai") && !this._isMessageReadByUser(m.created_at));
-        const html = this._state.messages.map((msg, i) => {
+        const firstUnreadIndex = this._state.messages.findIndex((m) => (m.sender_type === "agent" || m.sender_type === "ai") &&
+            !this._isMessageReadByUser(m.created_at));
+        const html = this._state.messages
+            .map((msg, i) => {
             const divider = i === firstUnreadIndex && firstUnreadIndex > 0
                 ? `<div style="display:flex;align-items:center;gap:12px;margin:12px 0"><div style="flex:1;height:1px;background:#DDD"></div><span style="font-size:12px;font-weight:600;color:${primary}">New</span><div style="flex:1;height:1px;background:#DDD"></div></div>`
                 : "";
             return divider + this._getMessageHTML(msg);
-        }).join("");
+        })
+            .join("");
         container.innerHTML = html;
         container.scrollTop = container.scrollHeight;
     }
@@ -1375,7 +1416,9 @@ class LazyLoadedChat {
         </div>
       `;
         }
-        const senderLabel = isAi ? "AI Assistant" : (message.sender_name || "Support");
+        const senderLabel = isAi
+            ? "AI Assistant"
+            : message.sender_name || "Support";
         return `
       <div class="vtilt-msg" style="
         display: flex;
@@ -1416,8 +1459,9 @@ class LazyLoadedChat {
     `;
     }
     _isMessageReadByAgent(messageCreatedAt) {
-        if (!this._state.agentLastReadAt)
+        if (!this._state.agentLastReadAt) {
             return false;
+        }
         return new Date(messageCreatedAt) <= new Date(this._state.agentLastReadAt);
     }
     // ============================================================================
@@ -1456,8 +1500,9 @@ class LazyLoadedChat {
         return 0;
     }
     _escapeHTML(text) {
-        if (!globals_1.document)
+        if (!globals_1.document) {
             return text;
+        }
         const div = globals_1.document.createElement("div");
         div.textContent = text;
         return div.innerHTML;