@v-tilt/browser 1.1.4 → 1.2.0

package/lib/extensions/replay/types.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Session Recording Types
+ *
+ * Type definitions for rrweb session recording.
+ * Based on PostHog's implementation.
+ */
+import type { blockClass, eventWithTime, hooksParam, KeepIframeSrcFn, maskTextClass, PackFn, RecordPlugin, SamplingStrategy } from "@rrweb/types";
+/** Mask options for input elements */
+export type MaskInputOptions = Partial<{
+    color: boolean;
+    date: boolean;
+    "datetime-local": boolean;
+    email: boolean;
+    month: boolean;
+    number: boolean;
+    range: boolean;
+    search: boolean;
+    tel: boolean;
+    text: boolean;
+    time: boolean;
+    url: boolean;
+    week: boolean;
+    textarea: boolean;
+    select: boolean;
+    password: boolean;
+}>;
+/** Function to mask input values */
+export type MaskInputFn = (text: string, element: HTMLElement) => string;
+/** Function to mask text content */
+export type MaskTextFn = (text: string, element: HTMLElement | null) => string;
+/** Options for slim DOM mode */
+export type SlimDOMOptions = Partial<{
+    script: boolean;
+    comment: boolean;
+    headFavicon: boolean;
+    headWhitespace: boolean;
+    headMetaDescKeywords: boolean;
+    headMetaSocial: boolean;
+    headMetaRobots: boolean;
+    headMetaHttpEquiv: boolean;
+    headMetaAuthorship: boolean;
+    headMetaVerification: boolean;
+    headTitleMutations: boolean;
+}>;
+/** Options for data URL generation */
+export type DataURLOptions = Partial<{
+    type: string;
+    quality: number;
+}>;
+/** Error handler type */
+export type ErrorHandler = (error: unknown) => void | boolean;
+/** rrweb record options */
+export interface RecordOptions {
+    emit?: (e: eventWithTime, isCheckout?: boolean) => void;
+    checkoutEveryNth?: number;
+    checkoutEveryNms?: number;
+    blockClass?: blockClass;
+    blockSelector?: string;
+    ignoreClass?: string;
+    ignoreSelector?: string;
+    maskTextClass?: maskTextClass;
+    maskTextSelector?: string;
+    maskAllInputs?: boolean;
+    maskInputOptions?: MaskInputOptions;
+    maskInputFn?: MaskInputFn;
+    maskTextFn?: MaskTextFn;
+    slimDOMOptions?: SlimDOMOptions | "all" | true;
+    ignoreCSSAttributes?: Set<string>;
+    inlineStylesheet?: boolean;
+    hooks?: hooksParam;
+    packFn?: PackFn;
+    sampling?: SamplingStrategy;
+    dataURLOptions?: DataURLOptions;
+    recordDOM?: boolean;
+    recordCanvas?: boolean;
+    recordCrossOriginIframes?: boolean;
+    recordAfter?: "DOMContentLoaded" | "load";
+    userTriggeredOnInput?: boolean;
+    collectFonts?: boolean;
+    inlineImages?: boolean;
+    plugins?: RecordPlugin[];
+    mousemoveWait?: number;
+    keepIframeSrcFn?: KeepIframeSrcFn;
+    errorHandler?: ErrorHandler;
+}
+/** rrweb record function type */
+export interface RRWebRecord {
+    (options: RecordOptions): () => void;
+    addCustomEvent: (tag: string, payload: unknown) => void;
+    takeFullSnapshot: () => void;
+    mirror: {
+        getId(n: Node | undefined | null): number;
+        getNode(id: number): Node | null;
+    };
+}
+/** Canvas recording configuration */
+export interface CanvasRecordingConfig {
+    enabled: boolean;
+    fps: number;
+    quality: number;
+}
+/** Network payload capture configuration */
+export interface NetworkPayloadCaptureConfig {
+    recordHeaders?: boolean;
+    recordBody?: boolean;
+    recordPerformance?: boolean;
+}
+/** Masking configuration */
+export interface MaskingConfig {
+    maskAllInputs?: boolean;
+    maskTextSelector?: string;
+    blockSelector?: string;
+}
+/** Session recording configuration */
+export interface SessionRecordingConfig {
+    /** Enable session recording */
+    enabled?: boolean;
+    /** Sample rate (0-1, where 1 = 100%) */
+    sampleRate?: number;
+    /** Minimum session duration in ms before sending */
+    minimumDurationMs?: number;
+    /** Session idle threshold in ms */
+    sessionIdleThresholdMs?: number;
+    /** Full snapshot interval in ms */
+    fullSnapshotIntervalMs?: number;
+    /** Enable console log capture */
+    captureConsole?: boolean;
+    /** Enable network request capture */
+    captureNetwork?: boolean;
+    /** Canvas recording settings */
+    captureCanvas?: {
+        recordCanvas?: boolean;
+        canvasFps?: number;
+        canvasQuality?: number;
+    };
+    /** Masking settings */
+    masking?: MaskingConfig;
+    /** Block class for elements to hide */
+    blockClass?: string;
+    /** Block selector for elements to hide */
+    blockSelector?: string;
+    /** Ignore class for input masking */
+    ignoreClass?: string;
+    /** Mask text class */
+    maskTextClass?: string;
+    /** Mask text selector */
+    maskTextSelector?: string;
+    /** Mask all inputs */
+    maskAllInputs?: boolean;
+    /** Mask input options */
+    maskInputOptions?: MaskInputOptions;
+    /** Record headers in network requests */
+    recordHeaders?: boolean;
+    /** Record body in network requests */
+    recordBody?: boolean;
+    /** Compress events before sending */
+    compressEvents?: boolean;
+    /** Internal: Mutation throttler refill rate */
+    __mutationThrottlerRefillRate?: number;
+    /** Internal: Mutation throttler bucket size */
+    __mutationThrottlerBucketSize?: number;
+}
+/** Recording status values */
+export type SessionRecordingStatus = "disabled" | "buffering" | "active" | "paused" | "sampled" | "trigger_pending";
+/** Recording start reason */
+export type SessionStartReason = "recording_initialized" | "session_id_changed" | "linked_flag_matched" | "linked_flag_overridden" | "sampling_overridden" | "url_trigger_matched" | "event_trigger_matched" | "sampled";
+/** Trigger type for starting recording */
+export type TriggerType = "url" | "event";
+/** Buffer for snapshot events */
+export interface SnapshotBuffer {
+    size: number;
+    data: eventWithTime[];
+    sessionId: string;
+    windowId: string;
+}
+/** Remote configuration for session recording */
+export interface SessionRecordingRemoteConfig {
+    enabled?: boolean;
+    endpoint?: string;
+    sampleRate?: string;
+    minimumDurationMilliseconds?: number;
+    consoleLogRecordingEnabled?: boolean;
+    networkPayloadCapture?: {
+        recordHeaders?: boolean;
+        recordBody?: boolean;
+        capturePerformance?: boolean;
+    };
+    masking?: MaskingConfig;
+    recordCanvas?: boolean;
+    canvasFps?: number;
+    canvasQuality?: number;
+    scriptConfig?: {
+        script?: string;
+    };
+    triggerMatchType?: "any" | "all";
+    urlTriggers?: Array<{
+        url: string;
+        matching: "regex" | "exact" | "contains";
+    }>;
+    urlBlocklist?: Array<{
+        url: string;
+        matching: "regex" | "exact" | "contains";
+    }>;
+    eventTriggers?: string[];
+}
+/** Queued rrweb method call */
+export interface QueuedRRWebEvent {
+    rrwebMethod: () => void;
+    attempt: number;
+    enqueuedAt: number;
+}

package/lib/extensions/replay/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Session Recording Types
+ *
+ * Type definitions for rrweb session recording.
+ * Based on PostHog's implementation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/session.d.ts

@@ -10,7 +10,7 @@ import { PersistenceMethod } from "./types";
 export declare class SessionManager {
     private storage;
     private _windowId;
-    constructor(storageMethod?: PersistenceMethod, domain?: string);
+    constructor(storageMethod?: PersistenceMethod, cross_subdomain?: boolean);
     /**
      * Get session ID (always returns a value, generates if needed)
      */
@@ -26,10 +26,12 @@ export declare class SessionManager {
     resetSessionId(): void;
     /**
      * Get session ID from storage (raw, can return null)
+     * Cookie Max-Age handles expiration automatically
      */
     private _getSessionIdRaw;
     /**
      * Store session ID
+     * Uses plain string format - cookie Max-Age handles expiration
      */
     private _storeSessionId;
     /**
@@ -60,5 +62,5 @@ export declare class SessionManager {
     /**
      * Update storage method at runtime
      */
-    updateStorageMethod(method: PersistenceMethod, domain?: string): void;
+    updateStorageMethod(method: PersistenceMethod, cross_subdomain?: boolean): void;
 }

package/lib/session.js

@@ -13,13 +13,11 @@ 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) {
+    constructor(storageMethod = "cookie", cross_subdomain) {
         this.storage = new storage_1.StorageManager({
             method: storageMethod,
-            domain,
+            cross_subdomain,
             sameSite: "Lax",
         });
         this._windowId = undefined;
@@ -66,48 +64,16 @@ class SessionManager {
     }
     /**
      * Get session ID from storage (raw, can return null)
+     * Cookie Max-Age handles expiration automatically
      */
     _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;
+        return this.storage.get(constants_1.STORAGE_KEY);
     }
     /**
      * Store session ID
+     * Uses plain string format - cookie Max-Age handles expiration
      */
     _storeSessionId(sessionId) {
-        // Use setWithExpiry for localStorage/sessionStorage
-        // For cookies, the StorageManager handles Max-Age
-        this.storage.setWithExpiry(constants_1.STORAGE_KEY, 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);
     }
     /**
@@ -214,10 +180,10 @@ class SessionManager {
     /**
      * Update storage method at runtime
      */
-    updateStorageMethod(method, domain) {
+    updateStorageMethod(method, cross_subdomain) {
         this.storage = new storage_1.StorageManager({
             method,
-            domain,
+            cross_subdomain,
             sameSite: "Lax",
         });
     }

package/lib/storage.d.ts

@@ -16,7 +16,7 @@ export declare const SESSION_COOKIE_MAX_AGE = 1800;
 export declare const USER_COOKIE_MAX_AGE = 31536000;
 export interface StorageOptions {
     method: PersistenceMethod;
-    domain?: string;
+    cross_subdomain?: boolean;
     secure?: boolean;
     sameSite?: "Strict" | "Lax" | "None";
 }
@@ -24,13 +24,18 @@ export interface StorageItem<T = string> {
     value: T;
     expiry?: number;
 }
+/**
+ * Auto-detect if cross-subdomain cookies should be enabled
+ * Returns false for platforms like herokuapp.com, vercel.app, netlify.app
+ */
+export declare function shouldUseCrossSubdomainCookie(): boolean;
 /**
  * Unified Storage Manager
  * Provides consistent storage operations across all persistence methods
  */
 export declare class StorageManager {
     private method;
-    private domain?;
+    private cross_subdomain;
     private secure;
     private sameSite;
     private memoryStorage;
@@ -92,4 +97,4 @@ export declare class StorageManager {
  * Create a shared storage instance
  * Use this for creating storage managers with consistent settings
  */
-export declare function createStorageManager(method: PersistenceMethod, domain?: string): StorageManager;
+export declare function createStorageManager(method: PersistenceMethod, cross_subdomain?: boolean): StorageManager;

package/lib/storage.js

@@ -14,26 +14,75 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StorageManager = exports.USER_COOKIE_MAX_AGE = exports.SESSION_COOKIE_MAX_AGE = void 0;
+exports.shouldUseCrossSubdomainCookie = shouldUseCrossSubdomainCookie;
 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
+// Platforms excluded from cross-subdomain cookies (following PostHog)
+const EXCLUDED_FROM_CROSS_SUBDOMAIN = [
+    "herokuapp.com",
+    "vercel.app",
+    "netlify.app",
+];
+/**
+ * Auto-detect if cross-subdomain cookies should be enabled
+ * Returns false for platforms like herokuapp.com, vercel.app, netlify.app
+ */
+function shouldUseCrossSubdomainCookie() {
+    var _a;
+    if (typeof document === "undefined") {
+        return false;
+    }
+    const hostname = (_a = document.location) === null || _a === void 0 ? void 0 : _a.hostname;
+    if (!hostname) {
+        return false;
+    }
+    const lastTwoParts = hostname.split(".").slice(-2).join(".");
+    for (const excluded of EXCLUDED_FROM_CROSS_SUBDOMAIN) {
+        if (lastTwoParts === excluded) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Get the cookie domain for cross-subdomain cookies
+ * Returns domain like ".example.com" or empty string for same-origin
+ */
+function getCookieDomain(cross_subdomain) {
+    var _a;
+    if (!cross_subdomain) {
+        return "";
+    }
+    if (typeof document === "undefined") {
+        return "";
+    }
+    const hostname = (_a = document.location) === null || _a === void 0 ? void 0 : _a.hostname;
+    if (!hostname) {
+        return "";
+    }
+    // Match domain pattern like "example.com" from "sub.example.com"
+    const matches = hostname.match(/[a-z0-9][a-z0-9-]+\.[a-z]{2,}$/i);
+    return matches ? `.${matches[0]}` : "";
+}
 /**
  * Unified Storage Manager
  * Provides consistent storage operations across all persistence methods
  */
 class StorageManager {
     constructor(options) {
-        var _a;
+        var _a, _b;
         this.memoryStorage = new Map();
         this.method = options.method;
-        this.domain = options.domain;
+        this.cross_subdomain =
+            (_a = options.cross_subdomain) !== null && _a !== void 0 ? _a : shouldUseCrossSubdomainCookie();
         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:");
+            (_b = options.secure) !== null && _b !== void 0 ? _b : (typeof location !== "undefined" && location.protocol === "https:");
     }
     // ============================================================================
     // Public API - Simple key-value operations
@@ -216,8 +265,10 @@ class StorageManager {
         if (this.secure) {
             cookieString += `; Secure`;
         }
-        if (this.domain) {
-            cookieString += `; domain=${this.domain}`;
+        // Auto-detect domain for cross-subdomain cookies
+        const domain = getCookieDomain(this.cross_subdomain);
+        if (domain) {
+            cookieString += `; domain=${domain}`;
         }
         document.cookie = cookieString;
     }
@@ -225,10 +276,12 @@ class StorageManager {
         if (typeof document === "undefined") {
             return;
         }
+        // Auto-detect domain for cross-subdomain cookies
+        const domain = getCookieDomain(this.cross_subdomain);
         // Set cookie with expired date
         let cookieString = `${name}=; Max-Age=0; path=/`;
-        if (this.domain) {
-            cookieString += `; domain=${this.domain}`;
+        if (domain) {
+            cookieString += `; domain=${domain}`;
         }
         document.cookie = cookieString;
         // Also try without domain (in case it was set without)
@@ -289,10 +342,10 @@ exports.StorageManager = StorageManager;
  * Create a shared storage instance
  * Use this for creating storage managers with consistent settings
  */
-function createStorageManager(method, domain) {
+function createStorageManager(method, cross_subdomain) {
     return new StorageManager({
         method,
-        domain,
+        cross_subdomain,
         sameSite: "Lax",
     });
 }

package/lib/types.d.ts

@@ -12,6 +12,13 @@ export interface VTiltConfig {
     api_host?: string;
     /** UI host for dashboard links */
     ui_host?: string | null;
+    /**
+     * Host for loading extension scripts (recorder.js, etc.)
+     * Defaults to unpkg CDN: https://unpkg.com/@v-tilt/browser@{version}/dist
+     * Can also use jsdelivr: https://cdn.jsdelivr.net/npm/@v-tilt/browser@{version}/dist
+     * Or self-hosted: https://your-domain.com/static
+     */
+    script_host?: string;
     /** Proxy domain for tracking requests */
     proxy?: string;
     /** Full proxy URL for tracking requests */
@@ -20,7 +27,7 @@ export interface VTiltConfig {
     name?: string;
     /** Project ID (set via init() first argument) */
     projectId?: string;
-    /** Domain to track (auto-detected if not provided) */
+    /** Domain to track (auto-detected if not provided) - used in event properties */
     domain?: string;
     /** Storage method for session data */
     storage?: PersistenceMethod;
@@ -28,7 +35,12 @@ export interface VTiltConfig {
     persistence?: PersistenceMethod;
     /** Persistence name prefix */
     persistence_name?: string;
-    /** Enable cross-subdomain cookies */
+    /**
+     * Enable cross-subdomain cookies.
+     * When true, cookies are shared across subdomains (e.g., app.example.com and www.example.com).
+     * Auto-detects false for platforms like herokuapp.com, vercel.app, netlify.app.
+     * @default true (except for excluded platforms)
+     */
     cross_subdomain_cookie?: boolean;
     /**
      * Person profiles mode:
@@ -59,6 +71,10 @@ export interface VTiltConfig {
     respect_dnt?: boolean;
     /** Opt users out by default */
     opt_out_capturing_by_default?: boolean;
+    /** Session recording configuration */
+    session_recording?: SessionRecordingOptions;
+    /** Disable session recording (convenience flag) */
+    disable_session_recording?: boolean;
     /** Global attributes added to all events */
     globalAttributes?: Record<string, string>;
     /** Bootstrap data for initialization */
@@ -97,7 +113,6 @@ export interface TrackingEvent {
     timestamp: string;
     event: string;
     project_id: string;
-    domain: string;
     distinct_id: string;
     anonymous_id?: string;
     payload: EventPayload;
@@ -172,14 +187,83 @@ export interface RequestOptions {
     timeout?: number;
     retry?: boolean;
 }
+/** Mask options for input elements in session recording */
+export interface SessionRecordingMaskInputOptions {
+    color?: boolean;
+    date?: boolean;
+    "datetime-local"?: boolean;
+    email?: boolean;
+    month?: boolean;
+    number?: boolean;
+    range?: boolean;
+    search?: boolean;
+    tel?: boolean;
+    text?: boolean;
+    time?: boolean;
+    url?: boolean;
+    week?: boolean;
+    textarea?: boolean;
+    select?: boolean;
+    password?: boolean;
+}
+/** Session recording configuration */
+export interface SessionRecordingOptions {
+    /** Enable session recording */
+    enabled?: boolean;
+    /** Sample rate (0-1, where 1 = 100%) */
+    sampleRate?: number;
+    /** Minimum session duration in ms before sending */
+    minimumDurationMs?: number;
+    /** Session idle threshold in ms (default: 5 minutes) */
+    sessionIdleThresholdMs?: number;
+    /** Full snapshot interval in ms (default: 5 minutes) */
+    fullSnapshotIntervalMs?: number;
+    /** Enable console log capture */
+    captureConsole?: boolean;
+    /** Enable network request capture */
+    captureNetwork?: boolean;
+    /** Canvas recording settings */
+    captureCanvas?: {
+        recordCanvas?: boolean;
+        canvasFps?: number;
+        canvasQuality?: number;
+    };
+    /** Block class for elements to hide (default: 'vt-no-capture') */
+    blockClass?: string;
+    /** Block selector for elements to hide */
+    blockSelector?: string;
+    /** Ignore class for input masking (default: 'vt-ignore-input') */
+    ignoreClass?: string;
+    /** Mask text class (default: 'vt-mask') */
+    maskTextClass?: string;
+    /** Mask text selector */
+    maskTextSelector?: string;
+    /** Mask all inputs (default: true) */
+    maskAllInputs?: boolean;
+    /** Mask input options */
+    maskInputOptions?: SessionRecordingMaskInputOptions;
+    /** Masking configuration */
+    masking?: {
+        maskAllInputs?: boolean;
+        maskTextSelector?: string;
+        blockSelector?: string;
+    };
+    /** Record headers in network requests */
+    recordHeaders?: boolean;
+    /** Record body in network requests */
+    recordBody?: boolean;
+    /** Compress events before sending (default: true) */
+    compressEvents?: boolean;
+    /** Internal: Mutation throttler refill rate */
+    __mutationThrottlerRefillRate?: number;
+    /** Internal: Mutation throttler bucket size */
+    __mutationThrottlerBucketSize?: number;
+}
 export interface RemoteConfig {
     /** Default to identified_only mode */
     defaultIdentifiedOnly?: boolean;
     /** Feature flags */
     featureFlags?: FeatureFlagsConfig;
     /** Session recording config */
-    sessionRecording?: {
-        enabled?: boolean;
-        sampleRate?: number;
-    };
+    sessionRecording?: SessionRecordingOptions;
 }

package/lib/user-manager.d.ts

@@ -15,7 +15,7 @@ export declare class UserManager {
     private storage;
     private userIdentity;
     private _cachedPersonProperties;
-    constructor(storageMethod?: PersistenceMethod, domain?: string);
+    constructor(storageMethod?: PersistenceMethod, cross_subdomain?: boolean);
     /**
      * Get current user identity
      */
@@ -136,5 +136,5 @@ export declare class UserManager {
     /**
      * Update storage method at runtime
      */
-    updateStorageMethod(method: PersistenceMethod, domain?: string): void;
+    updateStorageMethod(method: PersistenceMethod, cross_subdomain?: boolean): void;
 }

package/lib/user-manager.js

@@ -18,11 +18,11 @@ const utils_1 = require("./utils");
 const event_utils_1 = require("./utils/event-utils");
 const storage_1 = require("./storage");
 class UserManager {
-    constructor(storageMethod = "localStorage", domain) {
+    constructor(storageMethod = "localStorage", cross_subdomain) {
         this._cachedPersonProperties = null; // Cache for deduplication
         this.storage = new storage_1.StorageManager({
             method: storageMethod,
-            domain,
+            cross_subdomain,
             sameSite: "Lax",
         });
         this.userIdentity = this.loadUserIdentity();
@@ -544,10 +544,10 @@ class UserManager {
     /**
      * Update storage method at runtime
      */
-    updateStorageMethod(method, domain) {
+    updateStorageMethod(method, cross_subdomain) {
         this.storage = new storage_1.StorageManager({
             method,
-            domain,
+            cross_subdomain,
             sameSite: "Lax",
         });
         // Reload identity from new storage