@v-tilt/browser 1.1.5 → 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/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 */
@@ -64,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 */
@@ -176,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/utils/globals.d.ts

@@ -1,6 +1,48 @@
 declare const win: (Window & typeof globalThis) | undefined;
+/**
+ * Extension kinds that can be lazy loaded
+ */
+export type VTiltExtensionKind = "recorder" | "web-vitals";
+/**
+ * Interface for lazy-loaded session recording (set by recorder.ts)
+ * Matches LazyLoadedSessionRecordingInterface in session-recording-wrapper.ts
+ */
+export interface LazyLoadedSessionRecordingInterface {
+    start: (startReason?: string) => void;
+    stop: () => void;
+    sessionId: string;
+    status: string;
+    isStarted: boolean;
+    onRemoteConfig?: (response: any) => void;
+    log: (message: string, level: "log" | "warn" | "error") => void;
+    updateConfig: (config: any) => void;
+}
+/**
+ * VTilt Extensions interface for dynamically loaded modules
+ * This is the contract between lazily loaded extensions and the SDK
+ */
+export interface VTiltExtensions {
+    /** Load an external dependency script */
+    loadExternalDependency?: (instance: any, // VTilt instance - using any to avoid circular imports
+    kind: VTiltExtensionKind, callback: (error?: string | Event, event?: Event) => void) => void;
+    /** rrweb record function (set by recorder.ts) */
+    rrweb?: {
+        record: any;
+        version?: string;
+    };
+    /** rrweb plugins (set by recorder.ts) */
+    rrwebPlugins?: {
+        getRecordConsolePlugin?: () => any;
+        getRecordNetworkPlugin?: (options: any) => any;
+    };
+    /** Factory to create LazyLoadedSessionRecording (set by recorder.ts) */
+    initSessionRecording?: (instance: any, config?: any) => LazyLoadedSessionRecordingInterface;
+}
 export type AssignableWindow = Window & typeof globalThis & {
+    /** Main VTilt instance */
     vt: any;
+    /** VTilt Extensions for dynamically loaded modules */
+    __VTiltExtensions__?: VTiltExtensions;
 };
 export declare const ArrayProto: any[];
 export declare const nativeForEach: (callbackfn: (value: any, index: number, array: any[]) => void, thisArg?: any) => void;

package/lib/utils/globals.js

@@ -10,6 +10,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.window = exports.assignableWindow = exports.userAgent = exports.AbortController = exports.XMLHttpRequest = exports.fetch = exports.location = exports.document = exports.navigator = exports.nativeIndexOf = exports.nativeForEach = exports.ArrayProto = void 0;
+// Note: We use 'any' for VTilt to avoid circular imports
+// The actual type checking happens in the external-scripts-loader.ts
 const win = typeof window !== "undefined" ? window : undefined;
 exports.window = win;
 const global = typeof globalThis !== "undefined" ? globalThis : win;

package/lib/vtilt.d.ts

@@ -1,7 +1,9 @@
 import { VTiltConfig, EventPayload } from "./types";
 import { HistoryAutocapture } from "./extensions/history-autocapture";
+import { SessionRecordingWrapper } from "./extensions/replay";
 import { type QueuedRequest } from "./request-queue";
 export declare class VTilt {
+    readonly version = "1.1.5";
     private configManager;
     private sessionManager;
     private userManager;
@@ -10,6 +12,7 @@ export declare class VTilt {
     private retryQueue;
     private rateLimiter;
     historyAutocapture?: HistoryAutocapture;
+    sessionRecording?: SessionRecordingWrapper;
     __loaded: boolean;
     private _initial_pageview_captured;
     private _visibility_state_listener;
@@ -236,10 +239,43 @@ export declare class VTilt {
      * Get current session ID
      */
     getSessionId(): string | null;
+    /**
+     * Get current distinct ID
+     */
+    getDistinctId(): string;
+    /**
+     * Get anonymous ID
+     */
+    getAnonymousId(): string;
     /**
      * Update configuration
      */
     updateConfig(config: Partial<VTiltConfig>): void;
+    /**
+     * Initialize session recording
+     */
+    private _initSessionRecording;
+    /**
+     * Build session recording config from VTiltConfig
+     */
+    private _buildSessionRecordingConfig;
+    /**
+     * Start session recording
+     * Call this to manually start recording if it wasn't enabled initially
+     */
+    startSessionRecording(): void;
+    /**
+     * Stop session recording
+     */
+    stopSessionRecording(): void;
+    /**
+     * Check if session recording is active
+     */
+    isSessionRecordingActive(): boolean;
+    /**
+     * Get session recording ID
+     */
+    getSessionRecordingId(): string | null;
     /**
      * _execute_array() deals with processing any vTilt function
      * calls that were called before the vTilt library was loaded

package/lib/vtilt.js

@@ -8,6 +8,7 @@ const session_1 = require("./session");
 const user_manager_1 = require("./user-manager");
 const web_vitals_1 = require("./web-vitals");
 const history_autocapture_1 = require("./extensions/history-autocapture");
+const replay_1 = require("./extensions/replay");
 const request_1 = require("./request");
 const request_queue_1 = require("./request-queue");
 const retry_queue_1 = require("./retry-queue");
@@ -31,6 +32,8 @@ Use TypeScript accessibility modifiers (private/protected) for non-public member
 const isArray = Array.isArray;
 class VTilt {
     constructor(config = {}) {
+        // SDK version - injected at build time or defaults to package version
+        this.version = "1.1.5";
         this.__loaded = false; // Matches snippet's window.vt.__loaded check
         this._initial_pageview_captured = false;
         this._visibility_state_listener = null;
@@ -132,6 +135,8 @@ class VTilt {
         // Initialize history autocapture
         this.historyAutocapture = new history_autocapture_1.HistoryAutocapture(this);
         this.historyAutocapture.startIfEnabled();
+        // Initialize session recording if enabled
+        this._initSessionRecording();
         // Set up page unload handler to flush queued events
         this._setup_unload_handler();
         // Enable the request queue for batched sending (PostHog pattern)
@@ -719,6 +724,18 @@ class VTilt {
     getSessionId() {
         return this.sessionManager.getSessionId();
     }
+    /**
+     * Get current distinct ID
+     */
+    getDistinctId() {
+        return (this.userManager.getDistinctId() || this.userManager.getAnonymousId());
+    }
+    /**
+     * Get anonymous ID
+     */
+    getAnonymousId() {
+        return this.userManager.getAnonymousId();
+    }
     /**
      * Update configuration
      */
@@ -729,6 +746,95 @@ class VTilt {
         this.sessionManager = new session_1.SessionManager(fullConfig.storage || "cookie", fullConfig.cross_subdomain_cookie);
         this.userManager = new user_manager_1.UserManager(fullConfig.persistence || "localStorage", fullConfig.cross_subdomain_cookie);
         this.webVitalsManager = new web_vitals_1.WebVitalsManager(fullConfig, this);
+        // Update session recording config if it exists
+        if (this.sessionRecording && fullConfig.session_recording) {
+            this.sessionRecording.updateConfig(this._buildSessionRecordingConfig(fullConfig));
+        }
+    }
+    // ============================================================================
+    // Session Recording
+    // ============================================================================
+    /**
+     * Initialize session recording
+     */
+    _initSessionRecording() {
+        const config = this.configManager.getConfig();
+        // Don't initialize if explicitly disabled
+        if (config.disable_session_recording) {
+            return;
+        }
+        // Build session recording config
+        const sessionRecordingConfig = this._buildSessionRecordingConfig(config);
+        // Create session recording wrapper (lightweight - actual recorder is lazy-loaded)
+        this.sessionRecording = new replay_1.SessionRecordingWrapper(this, sessionRecordingConfig);
+        // Start recording if enabled (this will lazy-load the recorder script)
+        if (sessionRecordingConfig.enabled) {
+            this.sessionRecording.startIfEnabledOrStop("recording_initialized");
+        }
+    }
+    /**
+     * Build session recording config from VTiltConfig
+     */
+    _buildSessionRecordingConfig(config) {
+        var _a, _b, _c;
+        const sessionRecording = config.session_recording || {};
+        return {
+            enabled: (_a = sessionRecording.enabled) !== null && _a !== void 0 ? _a : false,
+            sampleRate: sessionRecording.sampleRate,
+            minimumDurationMs: sessionRecording.minimumDurationMs,
+            sessionIdleThresholdMs: sessionRecording.sessionIdleThresholdMs,
+            fullSnapshotIntervalMs: sessionRecording.fullSnapshotIntervalMs,
+            captureConsole: (_b = sessionRecording.captureConsole) !== null && _b !== void 0 ? _b : false,
+            captureNetwork: (_c = sessionRecording.captureNetwork) !== null && _c !== void 0 ? _c : false,
+            captureCanvas: sessionRecording.captureCanvas,
+            blockClass: sessionRecording.blockClass,
+            blockSelector: sessionRecording.blockSelector,
+            ignoreClass: sessionRecording.ignoreClass,
+            maskTextClass: sessionRecording.maskTextClass,
+            maskTextSelector: sessionRecording.maskTextSelector,
+            maskAllInputs: sessionRecording.maskAllInputs,
+            maskInputOptions: sessionRecording.maskInputOptions,
+            masking: sessionRecording.masking,
+            recordHeaders: sessionRecording.recordHeaders,
+            recordBody: sessionRecording.recordBody,
+            compressEvents: sessionRecording.compressEvents,
+            __mutationThrottlerRefillRate: sessionRecording.__mutationThrottlerRefillRate,
+            __mutationThrottlerBucketSize: sessionRecording.__mutationThrottlerBucketSize,
+        };
+    }
+    /**
+     * Start session recording
+     * Call this to manually start recording if it wasn't enabled initially
+     */
+    startSessionRecording() {
+        if (!this.sessionRecording) {
+            const config = this.configManager.getConfig();
+            const sessionRecordingConfig = this._buildSessionRecordingConfig(config);
+            sessionRecordingConfig.enabled = true;
+            this.sessionRecording = new replay_1.SessionRecordingWrapper(this, sessionRecordingConfig);
+        }
+        this.sessionRecording.startIfEnabledOrStop("recording_initialized");
+    }
+    /**
+     * Stop session recording
+     */
+    stopSessionRecording() {
+        var _a;
+        (_a = this.sessionRecording) === null || _a === void 0 ? void 0 : _a.stopRecording();
+    }
+    /**
+     * Check if session recording is active
+     */
+    isSessionRecordingActive() {
+        var _a;
+        return ((_a = this.sessionRecording) === null || _a === void 0 ? void 0 : _a.status) === "active";
+    }
+    /**
+     * Get session recording ID
+     */
+    getSessionRecordingId() {
+        var _a;
+        return ((_a = this.sessionRecording) === null || _a === void 0 ? void 0 : _a.sessionId) || null;
     }
     /**
      * _execute_array() deals with processing any vTilt function

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-tilt/browser",
-  "version": "1.1.5",
+  "version": "1.2.0",
   "description": "vTilt browser tracking library",
   "main": "dist/main.js",
   "module": "dist/module.js",
@@ -48,6 +48,9 @@
     "typescript": "^5.3.3"
   },
   "dependencies": {
+    "@rrweb/record": "2.0.0-alpha.17",
+    "@rrweb/rrweb-plugin-console-record": "2.0.0-alpha.17",
+    "@rrweb/types": "2.0.0-alpha.17",
     "fflate": "^0.8.2",
     "web-vitals": "^3.5.0"
   },