@v-tilt/browser 1.1.4 → 1.2.0

package/lib/extensions/replay/session-recording-utils.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Session Recording Utilities
+ *
+ * Utility functions for session recording.
+ * Based on PostHog's sessionrecording-utils.ts
+ */
+import { EventType, IncrementalSource, eventWithTime } from "@rrweb/types";
+import type { SnapshotBuffer } from "./types";
+export declare const INCREMENTAL_SNAPSHOT_EVENT_TYPE = 3;
+export declare const ONE_KB = 1024;
+export declare const ONE_MB: number;
+export declare const SEVEN_MB: number;
+export declare const PARTIAL_COMPRESSION_THRESHOLD = 1024;
+export declare const RECORDING_MAX_EVENT_SIZE: number;
+export declare const RECORDING_BUFFER_TIMEOUT = 2000;
+export declare const RECORDING_IDLE_THRESHOLD_MS: number;
+/** Active interaction sources */
+export declare const ACTIVE_SOURCES: IncrementalSource[];
+/**
+ * Gzip compress data to a base64 string
+ */
+export declare function gzipToString(data: unknown): string;
+/**
+ * Estimate the size of an object in bytes
+ */
+export declare function estimateSize(obj: unknown): number;
+export interface CompressedFullSnapshotEvent {
+    type: typeof EventType.FullSnapshot;
+    data: string;
+}
+export interface CompressedIncrementalSnapshotEvent {
+    type: typeof EventType.IncrementalSnapshot;
+    data: {
+        source: IncrementalSource;
+        texts: string;
+        attributes: string;
+        removes: string;
+        adds: string;
+    };
+}
+export interface CompressedIncrementalStyleSnapshotEvent {
+    type: typeof EventType.IncrementalSnapshot;
+    data: {
+        source: typeof IncrementalSource.StyleSheetRule;
+        id?: number;
+        styleId?: number;
+        replace?: string;
+        replaceSync?: string;
+        adds?: string;
+        removes?: string;
+    };
+}
+export type CompressedEvent = CompressedFullSnapshotEvent | CompressedIncrementalSnapshotEvent | CompressedIncrementalStyleSnapshotEvent;
+export type CompressedEventWithTime = CompressedEvent & {
+    timestamp: number;
+    delay?: number;
+    cv: "2024-10";
+};
+/**
+ * Compress an rrweb event for transmission
+ * Only compresses full snapshots and mutation events above threshold
+ */
+export declare function compressEvent(event: eventWithTime): eventWithTime | CompressedEventWithTime;
+/**
+ * Truncate large console log payloads to prevent excessive data
+ */
+export declare function truncateLargeConsoleLogs(event: eventWithTime): eventWithTime;
+/**
+ * Split a large buffer into smaller chunks for transmission
+ */
+export declare function splitBuffer(buffer: SnapshotBuffer, sizeLimit?: number): SnapshotBuffer[];
+/**
+ * Check if an event is a session idle custom event
+ */
+export declare function isSessionIdleEvent(event: eventWithTime): event is eventWithTime & {
+    data: {
+        tag: string;
+        payload: unknown;
+    };
+};
+/**
+ * Check if an event is a recording paused custom event
+ */
+export declare function isRecordingPausedEvent(event: eventWithTime): boolean;
+/**
+ * Check if an event represents user interaction
+ */
+export declare function isInteractiveEvent(event: eventWithTime): boolean;
+/**
+ * Clamp a value to a range with logging
+ */
+export declare function clampToRange(value: number, min: number, max: number, label: string, defaultValue: number): number;

package/lib/extensions/replay/session-recording-utils.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * Session Recording Utilities
+ *
+ * Utility functions for session recording.
+ * Based on PostHog's sessionrecording-utils.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVE_SOURCES = exports.RECORDING_IDLE_THRESHOLD_MS = exports.RECORDING_BUFFER_TIMEOUT = exports.RECORDING_MAX_EVENT_SIZE = exports.PARTIAL_COMPRESSION_THRESHOLD = exports.SEVEN_MB = exports.ONE_MB = exports.ONE_KB = exports.INCREMENTAL_SNAPSHOT_EVENT_TYPE = void 0;
+exports.gzipToString = gzipToString;
+exports.estimateSize = estimateSize;
+exports.compressEvent = compressEvent;
+exports.truncateLargeConsoleLogs = truncateLargeConsoleLogs;
+exports.splitBuffer = splitBuffer;
+exports.isSessionIdleEvent = isSessionIdleEvent;
+exports.isRecordingPausedEvent = isRecordingPausedEvent;
+exports.isInteractiveEvent = isInteractiveEvent;
+exports.clampToRange = clampToRange;
+const types_1 = require("@rrweb/types");
+const fflate_1 = require("fflate");
+// ============================================================================
+// Constants
+// ============================================================================
+exports.INCREMENTAL_SNAPSHOT_EVENT_TYPE = 3;
+exports.ONE_KB = 1024;
+exports.ONE_MB = exports.ONE_KB * exports.ONE_KB;
+exports.SEVEN_MB = exports.ONE_MB * 7 * 0.9; // ~7mb with wiggle room
+exports.PARTIAL_COMPRESSION_THRESHOLD = exports.ONE_KB;
+exports.RECORDING_MAX_EVENT_SIZE = exports.ONE_MB * 0.9; // ~1mb with wiggle room
+exports.RECORDING_BUFFER_TIMEOUT = 2000; // 2 seconds
+exports.RECORDING_IDLE_THRESHOLD_MS = 5 * 60 * 1000; // 5 minutes
+/** Active interaction sources */
+exports.ACTIVE_SOURCES = [
+    types_1.IncrementalSource.MouseMove,
+    types_1.IncrementalSource.MouseInteraction,
+    types_1.IncrementalSource.Scroll,
+    types_1.IncrementalSource.ViewportResize,
+    types_1.IncrementalSource.Input,
+    types_1.IncrementalSource.TouchMove,
+    types_1.IncrementalSource.MediaInteraction,
+    types_1.IncrementalSource.Drag,
+];
+// ============================================================================
+// Compression
+// ============================================================================
+/**
+ * Gzip compress data to a base64 string
+ */
+function gzipToString(data) {
+    return (0, fflate_1.strFromU8)((0, fflate_1.gzipSync)((0, fflate_1.strToU8)(JSON.stringify(data))), true);
+}
+/**
+ * Estimate the size of an object in bytes
+ */
+function estimateSize(obj) {
+    try {
+        return new Blob([JSON.stringify(obj)]).size;
+    }
+    catch (_a) {
+        // Fallback for environments without Blob
+        return JSON.stringify(obj).length * 2;
+    }
+}
+/**
+ * Compress an rrweb event for transmission
+ * Only compresses full snapshots and mutation events above threshold
+ */
+function compressEvent(event) {
+    const originalSize = estimateSize(event);
+    if (originalSize < exports.PARTIAL_COMPRESSION_THRESHOLD) {
+        return event;
+    }
+    try {
+        if (event.type === types_1.EventType.FullSnapshot) {
+            return {
+                ...event,
+                data: gzipToString(event.data),
+                cv: "2024-10",
+            };
+        }
+        if (event.type === types_1.EventType.IncrementalSnapshot &&
+            event.data.source === types_1.IncrementalSource.Mutation) {
+            const mutationData = event.data;
+            return {
+                ...event,
+                cv: "2024-10",
+                data: {
+                    ...mutationData,
+                    texts: gzipToString(mutationData.texts),
+                    attributes: gzipToString(mutationData.attributes),
+                    removes: gzipToString(mutationData.removes),
+                    adds: gzipToString(mutationData.adds),
+                },
+            };
+        }
+        if (event.type === types_1.EventType.IncrementalSnapshot &&
+            event.data.source === types_1.IncrementalSource.StyleSheetRule) {
+            const styleData = event.data;
+            return {
+                ...event,
+                cv: "2024-10",
+                data: {
+                    ...styleData,
+                    adds: styleData.adds ? gzipToString(styleData.adds) : undefined,
+                    removes: styleData.removes
+                        ? gzipToString(styleData.removes)
+                        : undefined,
+                },
+            };
+        }
+    }
+    catch (e) {
+        console.error("[SessionRecording] Could not compress event - will use uncompressed event", e);
+    }
+    return event;
+}
+// ============================================================================
+// Console Log Handling
+// ============================================================================
+const MAX_CONSOLE_LOG_SIZE = 1000;
+/**
+ * Truncate large console log payloads to prevent excessive data
+ */
+function truncateLargeConsoleLogs(event) {
+    if (event.type !== types_1.EventType.Plugin ||
+        event.data.plugin !== "rrweb/console@1") {
+        return event;
+    }
+    const payload = event.data.payload;
+    if (!(payload === null || payload === void 0 ? void 0 : payload.payload)) {
+        return event;
+    }
+    const truncatedPayload = payload.payload.map((item) => {
+        if (typeof item === "string" && item.length > MAX_CONSOLE_LOG_SIZE) {
+            return item.substring(0, MAX_CONSOLE_LOG_SIZE) + "... [truncated]";
+        }
+        return item;
+    });
+    return {
+        ...event,
+        data: {
+            ...event.data,
+            payload: {
+                ...payload,
+                payload: truncatedPayload,
+            },
+        },
+    };
+}
+// ============================================================================
+// Buffer Management
+// ============================================================================
+/**
+ * Split a large buffer into smaller chunks for transmission
+ */
+function splitBuffer(buffer, sizeLimit = exports.SEVEN_MB) {
+    if (buffer.size >= sizeLimit && buffer.data.length > 1) {
+        const half = Math.floor(buffer.data.length / 2);
+        const firstHalf = buffer.data.slice(0, half);
+        const secondHalf = buffer.data.slice(half);
+        return [
+            ...splitBuffer({
+                size: estimateSize(firstHalf),
+                data: firstHalf,
+                sessionId: buffer.sessionId,
+                windowId: buffer.windowId,
+            }),
+            ...splitBuffer({
+                size: estimateSize(secondHalf),
+                data: secondHalf,
+                sessionId: buffer.sessionId,
+                windowId: buffer.windowId,
+            }),
+        ];
+    }
+    return [buffer];
+}
+// ============================================================================
+// Event Helpers
+// ============================================================================
+/**
+ * Check if an event is a session idle custom event
+ */
+function isSessionIdleEvent(event) {
+    return (event.type === types_1.EventType.Custom &&
+        event.data.tag === "sessionIdle");
+}
+/**
+ * Check if an event is a recording paused custom event
+ */
+function isRecordingPausedEvent(event) {
+    return (event.type === types_1.EventType.Custom &&
+        event.data.tag === "recording paused");
+}
+/**
+ * Check if an event represents user interaction
+ */
+function isInteractiveEvent(event) {
+    return (event.type === exports.INCREMENTAL_SNAPSHOT_EVENT_TYPE &&
+        exports.ACTIVE_SOURCES.includes(event.data
+            .source));
+}
+/**
+ * Clamp a value to a range with logging
+ */
+function clampToRange(value, min, max, label, defaultValue) {
+    if (value < min || value > max) {
+        console.warn(`[SessionRecording] ${label} must be between ${min} and ${max}. Using default: ${defaultValue}`);
+        return defaultValue;
+    }
+    return value;
+}

package/lib/extensions/replay/session-recording-wrapper.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Session Recording Wrapper
+ *
+ * Lightweight wrapper that handles the decision of WHEN to load recording.
+ * The actual recording logic is in LazyLoadedSessionRecording which is
+ * loaded on demand.
+ *
+ * Based on PostHog's sessionrecording-wrapper.ts
+ */
+import type { VTilt } from "../../vtilt";
+import type { SessionRecordingConfig, SessionStartReason } from "./types";
+import { LazyLoadedSessionRecordingInterface } from "../../utils/globals";
+/** Status when lazy loading is in progress */
+export declare const LAZY_LOADING: "lazy_loading";
+/** Session recording status */
+export type SessionRecordingStatus = "disabled" | "buffering" | "active" | "paused" | "sampled" | "trigger_pending" | typeof LAZY_LOADING;
+export type { LazyLoadedSessionRecordingInterface };
+/**
+ * Session Recording Wrapper
+ *
+ * This is the lightweight class that lives in the main bundle.
+ * It handles:
+ * - Deciding if recording should be enabled
+ * - Lazy loading the actual recording code
+ * - Delegating to LazyLoadedSessionRecording
+ */
+export declare class SessionRecordingWrapper {
+    private readonly _instance;
+    private _lazyLoadedRecording;
+    private _config;
+    constructor(_instance: VTilt, config?: SessionRecordingConfig);
+    get started(): boolean;
+    get status(): SessionRecordingStatus;
+    get sessionId(): string;
+    /**
+     * Start recording if enabled, otherwise stop
+     */
+    startIfEnabledOrStop(startReason?: SessionStartReason): void;
+    /**
+     * Stop recording
+     */
+    stopRecording(): void;
+    /**
+     * Log a message to the recording
+     */
+    log(message: string, level?: "log" | "warn" | "error"): void;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<SessionRecordingConfig>): void;
+    private get _isRecordingEnabled();
+    private get _scriptName();
+    /**
+     * Lazy load the recording script and start
+     */
+    private _lazyLoadAndStart;
+    /**
+     * Called after the recording script is loaded
+     */
+    private _onScriptLoaded;
+}

package/lib/extensions/replay/session-recording-wrapper.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Session Recording Wrapper
+ *
+ * Lightweight wrapper that handles the decision of WHEN to load recording.
+ * The actual recording logic is in LazyLoadedSessionRecording which is
+ * loaded on demand.
+ *
+ * Based on PostHog's sessionrecording-wrapper.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionRecordingWrapper = exports.LAZY_LOADING = void 0;
+const globals_1 = require("../../utils/globals");
+const LOGGER_PREFIX = "[SessionRecording]";
+/** Status when lazy loading is in progress */
+exports.LAZY_LOADING = "lazy_loading";
+/**
+ * Session Recording Wrapper
+ *
+ * This is the lightweight class that lives in the main bundle.
+ * It handles:
+ * - Deciding if recording should be enabled
+ * - Lazy loading the actual recording code
+ * - Delegating to LazyLoadedSessionRecording
+ */
+class SessionRecordingWrapper {
+    constructor(_instance, config = {}) {
+        this._instance = _instance;
+        this._config = config;
+    }
+    // ============================================================================
+    // Public API
+    // ============================================================================
+    get started() {
+        var _a;
+        return !!((_a = this._lazyLoadedRecording) === null || _a === void 0 ? void 0 : _a.isStarted);
+    }
+    get status() {
+        var _a;
+        return (((_a = this._lazyLoadedRecording) === null || _a === void 0 ? void 0 : _a.status) ||
+            exports.LAZY_LOADING);
+    }
+    get sessionId() {
+        var _a;
+        return ((_a = this._lazyLoadedRecording) === null || _a === void 0 ? void 0 : _a.sessionId) || "";
+    }
+    /**
+     * Start recording if enabled, otherwise stop
+     */
+    startIfEnabledOrStop(startReason) {
+        var _a;
+        if (this._isRecordingEnabled && ((_a = this._lazyLoadedRecording) === null || _a === void 0 ? void 0 : _a.isStarted)) {
+            return;
+        }
+        // Check browser compatibility
+        const canRunReplay = typeof Object.assign !== "undefined" && typeof Array.from !== "undefined";
+        if (this._isRecordingEnabled && canRunReplay) {
+            this._lazyLoadAndStart(startReason);
+            console.info(`${LOGGER_PREFIX} starting`);
+        }
+        else {
+            this.stopRecording();
+        }
+    }
+    /**
+     * Stop recording
+     */
+    stopRecording() {
+        var _a;
+        (_a = this._lazyLoadedRecording) === null || _a === void 0 ? void 0 : _a.stop();
+    }
+    /**
+     * Log a message to the recording
+     */
+    log(message, level = "log") {
+        var _a;
+        if ((_a = this._lazyLoadedRecording) === null || _a === void 0 ? void 0 : _a.log) {
+            this._lazyLoadedRecording.log(message, level);
+        }
+        else {
+            console.warn(`${LOGGER_PREFIX} log called before recorder was ready`);
+        }
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(config) {
+        var _a;
+        this._config = { ...this._config, ...config };
+        (_a = this._lazyLoadedRecording) === null || _a === void 0 ? void 0 : _a.updateConfig(this._config);
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    get _isRecordingEnabled() {
+        var _a;
+        const config = this._instance.getConfig();
+        const enabled = (_a = this._config.enabled) !== null && _a !== void 0 ? _a : false;
+        const notDisabled = !config.disable_session_recording;
+        return !!globals_1.window && enabled && notDisabled;
+    }
+    get _scriptName() {
+        return "recorder";
+    }
+    /**
+     * Lazy load the recording script and start
+     */
+    _lazyLoadAndStart(startReason) {
+        var _a, _b, _c, _d;
+        if (!this._isRecordingEnabled) {
+            return;
+        }
+        // Check if already loaded
+        if (((_b = (_a = globals_1.assignableWindow === null || globals_1.assignableWindow === void 0 ? void 0 : globals_1.assignableWindow.__VTiltExtensions__) === null || _a === void 0 ? void 0 : _a.rrweb) === null || _b === void 0 ? void 0 : _b.record) &&
+            ((_c = globals_1.assignableWindow.__VTiltExtensions__) === null || _c === void 0 ? void 0 : _c.initSessionRecording)) {
+            this._onScriptLoaded(startReason);
+            return;
+        }
+        // Load the recorder script
+        const loadExternalDependency = (_d = globals_1.assignableWindow.__VTiltExtensions__) === null || _d === void 0 ? void 0 : _d.loadExternalDependency;
+        if (!loadExternalDependency) {
+            console.error(`${LOGGER_PREFIX} loadExternalDependency not available. Session recording cannot start.`);
+            return;
+        }
+        loadExternalDependency(this._instance, this._scriptName, (err) => {
+            if (err) {
+                console.error(`${LOGGER_PREFIX} could not load recorder:`, err);
+                return;
+            }
+            this._onScriptLoaded(startReason);
+        });
+    }
+    /**
+     * Called after the recording script is loaded
+     */
+    _onScriptLoaded(startReason) {
+        var _a;
+        const initSessionRecording = (_a = globals_1.assignableWindow.__VTiltExtensions__) === null || _a === void 0 ? void 0 : _a.initSessionRecording;
+        if (!initSessionRecording) {
+            console.error(`${LOGGER_PREFIX} initSessionRecording not available after script load`);
+            return;
+        }
+        if (!this._lazyLoadedRecording) {
+            this._lazyLoadedRecording = initSessionRecording(this._instance, this._config);
+        }
+        this._lazyLoadedRecording.start(startReason);
+    }
+}
+exports.SessionRecordingWrapper = SessionRecordingWrapper;

package/lib/extensions/replay/session-recording.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Lazy Loaded Session Recording
+ *
+ * The actual rrweb session recording implementation.
+ * This is loaded on demand when recording is enabled.
+ *
+ * Based on PostHog's lazy-loaded-session-recorder.ts
+ */
+import { type eventWithTime } from "@rrweb/types";
+import type { VTilt } from "../../vtilt";
+import { LazyLoadedSessionRecordingInterface } from "../../utils/globals";
+import type { SessionRecordingConfig, SessionRecordingStatus } from "./types";
+export declare const SESSION_RECORDING_BATCH_KEY = "recordings";
+export declare class LazyLoadedSessionRecording implements LazyLoadedSessionRecordingInterface {
+    private _instance;
+    private _endpoint;
+    private _flushBufferTimer?;
+    private _fullSnapshotTimer?;
+    private _captureStarted;
+    private _stopRrweb?;
+    private _isIdle;
+    private _lastActivityTimestamp;
+    private _lastHref?;
+    private _sessionId;
+    private _windowId;
+    private _buffer;
+    private _queuedRRWebEvents;
+    private _config;
+    constructor(instance: VTilt, config?: SessionRecordingConfig);
+    get isStarted(): boolean;
+    /** @deprecated Use isStarted instead */
+    get started(): boolean;
+    get sessionId(): string;
+    get status(): SessionRecordingStatus;
+    /**
+     * Start session recording (interface method)
+     */
+    start(startReason?: string): void;
+    /**
+     * Stop session recording (interface method)
+     */
+    stop(): void;
+    /** @deprecated Use stop() instead */
+    stopRecording(): void;
+    /**
+     * Add a custom event to the recording
+     */
+    addCustomEvent(tag: string, payload: unknown): boolean;
+    /**
+     * Take a full snapshot
+     */
+    takeFullSnapshot(): boolean;
+    /**
+     * Log a message to the recording
+     */
+    log(message: string, level?: "log" | "warn" | "error"): void;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<SessionRecordingConfig>): void;
+    private _onBeforeUnload;
+    private _onOffline;
+    private _onOnline;
+    private _onVisibilityChange;
+    private _isRecordingEnabled;
+    private _startCapture;
+    private _loadRecorder;
+    private _onScriptLoaded;
+    private _gatherRRWebPlugins;
+    onRRwebEmit(rawEvent: eventWithTime): void;
+    private _processQueuedEvents;
+    private _updateWindowAndSessionIds;
+    private _clearBuffer;
+    private _flushBuffer;
+    private _captureSnapshotBuffered;
+    private _captureSnapshot;
+    private _sendSnapshot;
+    /**
+     * Fetch with exponential backoff retry (PostHog-style)
+     * Retries on network errors and 5xx server errors
+     */
+    private _fetchWithRetry;
+    /**
+     * Schedule a retry with exponential backoff and jitter
+     */
+    private _scheduleRetry;
+    private _scheduleFullSnapshot;
+    private _tryRRWebMethod;
+    private _tryAddCustomEvent;
+    private _tryTakeFullSnapshot;
+    private _getCanvasConfig;
+    private _getMaskingConfig;
+    private _generateId;
+    private _reportStarted;
+}