@v-tilt/browser 1.4.2 → 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.1";
+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

@@ -1,14 +1,9 @@
 /**
- * Lazy Loaded Chat Implementation
- *
- * The actual chat widget implementation that is loaded on demand.
- * This file is bundled into chat.js and loaded when chat is enabled.
- *
- * Uses Ably for real-time messaging.
+ * 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;
@@ -23,7 +18,6 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     private _messageCallbacks;
     private _typingCallbacks;
     private _connectionCallbacks;
-    private _typingTimeout;
     private _typingDebounce;
     private _isUserTyping;
     private _initialUserReadAt;
@@ -43,32 +37,13 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     toggle(): void;
     show(): void;
     hide(): void;
-    /**
-     * Fetch/refresh the list of user's channels
-     */
     getChannels(): Promise<void>;
-    /**
-     * Select a channel and load its messages
-     */
     selectChannel(channelId: string): Promise<void>;
-    /**
-     * Create a new channel and enter it
-     */
     createChannel(): Promise<void>;
-    /**
-     * Go back to channel list from conversation view
-     */
     goToChannelList(): void;
     sendMessage(content: string): Promise<void>;
     markAsRead(): void;
-    /**
-     * Automatically mark unread agent/AI messages as read
-     * Called when widget opens or new messages arrive while open
-     */
     private _autoMarkAsRead;
-    /**
-     * Check if a message has been read by the user (using initial cursor)
-     */
     private _isMessageReadByUser;
     onMessage(callback: MessageCallback): Unsubscribe;
     onTyping(callback: TypingCallback): Unsubscribe;
@@ -86,7 +61,6 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     private _handleUserTyping;
     private _sendTypingIndicator;
     private _handleSend;
-    private _previousView;
     private _updateUI;
     private _updateHeader;
     private _getChannelListHTML;
@@ -96,16 +70,12 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     private _attachConversationListeners;
     private _formatRelativeTime;
     private _renderMessages;
-    private _isMobile;
     private _getContainerStyles;
     private _getBubbleStyles;
     private _getBubbleHTML;
     private _getWidgetStyles;
     private _getWidgetHTML;
     private _getMessageHTML;
-    /**
-     * Check if a message has been read by the agent using cursor comparison
-     */
     private _isMessageReadByAgent;
     private _apiRequest;
     private _trackEvent;