@v-tilt/browser 1.1.5 → 1.3.0

package/dist/module.d.ts

@@ -20,6 +20,13 @@ 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 */
@@ -52,8 +59,11 @@ interface VTiltConfig {
     person_profiles?: PersonProfilesMode;
     /** Enable autocapture */
     autocapture?: boolean;
-    /** Enable web vitals tracking */
-    capture_performance?: boolean;
+    /**
+     * Enable web vitals tracking.
+     * Can be a boolean or an object with detailed configuration.
+     */
+    capture_performance?: boolean | CapturePerformanceConfig;
     /** Enable page view tracking */
     capture_pageview?: boolean | "auto";
     /** Enable page leave tracking */
@@ -72,6 +82,10 @@ 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 */
@@ -157,6 +171,29 @@ interface AliasEvent {
     distinct_id: string;
     original: string;
 }
+/** Supported Web Vitals metrics */
+type SupportedWebVitalsMetric = "LCP" | "CLS" | "FCP" | "INP" | "TTFB";
+/** All supported Web Vitals metrics */
+declare const ALL_WEB_VITALS_METRICS: SupportedWebVitalsMetric[];
+/** Default Web Vitals metrics (matches PostHog defaults) */
+declare const DEFAULT_WEB_VITALS_METRICS: SupportedWebVitalsMetric[];
+/**
+ * Web Vitals capture configuration
+ */
+interface CapturePerformanceConfig {
+    /** Enable or disable web vitals capture */
+    web_vitals?: boolean;
+    /** Which metrics to capture (default: LCP, CLS, FCP, INP) */
+    web_vitals_allowed_metrics?: SupportedWebVitalsMetric[];
+    /** Delay before flushing metrics in ms (default: 5000) */
+    web_vitals_delayed_flush_ms?: number;
+    /**
+     * Maximum allowed metric value in ms (default: 900000 = 15 minutes)
+     * Values above this are considered anomalies and ignored.
+     * Set to 0 to disable this check.
+     */
+    __web_vitals_max_value?: number;
+}
 interface WebVitalMetric {
     name: string;
     value: number;
@@ -164,6 +201,10 @@ interface WebVitalMetric {
     rating: "good" | "needs-improvement" | "poor";
     id: string;
     navigationType: string;
+    /** Timestamp when the metric was captured (added internally) */
+    timestamp?: number;
+    /** Attribution data from web-vitals library */
+    attribution?: Record<string, unknown>;
 }
 interface GeolocationData {
     country?: string;
@@ -184,16 +225,85 @@ interface RequestOptions {
     timeout?: number;
     retry?: boolean;
 }
+/** Mask options for input elements in session recording */
+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 */
+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;
+}
 interface RemoteConfig {
     /** Default to identified_only mode */
     defaultIdentifiedOnly?: boolean;
     /** Feature flags */
     featureFlags?: FeatureFlagsConfig;
     /** Session recording config */
-    sessionRecording?: {
-        enabled?: boolean;
-        sampleRate?: number;
-    };
+    sessionRecording?: SessionRecordingOptions;
 }
 
 /**
@@ -213,6 +323,150 @@ declare class HistoryAutocapture {
     private _setupPopstateListener;
 }
 
+/**
+ * Session Recording Types
+ *
+ * Type definitions for rrweb session recording.
+ * Based on PostHog's implementation.
+ */
+
+/** Mask options for input elements */
+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;
+}>;
+/** Masking configuration */
+interface MaskingConfig {
+    maskAllInputs?: boolean;
+    maskTextSelector?: string;
+    blockSelector?: string;
+}
+/** Session recording configuration */
+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 start reason */
+type SessionStartReason = "recording_initialized" | "session_id_changed" | "linked_flag_matched" | "linked_flag_overridden" | "sampling_overridden" | "url_trigger_matched" | "event_trigger_matched" | "sampled";
+
+/**
+ * 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
+ */
+
+/** Status when lazy loading is in progress */
+declare const LAZY_LOADING: "lazy_loading";
+/** Session recording status */
+type SessionRecordingStatus = "disabled" | "buffering" | "active" | "paused" | "sampled" | "trigger_pending" | typeof 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
+ */
+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;
+}
+
 /**
  * Request Queue - Event Batching (PostHog-style)
  *
@@ -234,6 +488,7 @@ interface QueuedRequest {
 }
 
 declare class VTilt {
+    readonly version = "1.1.5";
     private configManager;
     private sessionManager;
     private userManager;
@@ -242,6 +497,7 @@ declare class VTilt {
     private retryQueue;
     private rateLimiter;
     historyAutocapture?: HistoryAutocapture;
+    sessionRecording?: SessionRecordingWrapper;
     __loaded: boolean;
     private _initial_pageview_captured;
     private _visibility_state_listener;
@@ -468,10 +724,43 @@ 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
@@ -493,5 +782,5 @@ declare class VTilt {
 
 declare const vt: VTilt;
 
-export { VTilt, vt as default, vt };
-export type { AliasEvent, CaptureOptions, CaptureResult, EventPayload, FeatureFlagsConfig, GeolocationData, GroupsConfig, PersistenceMethod, Properties, Property, PropertyOperations, RemoteConfig, RequestOptions, SessionData, SessionIdChangedCallback, TrackingEvent, UserIdentity, UserProperties, VTiltConfig, WebVitalMetric };
+export { ALL_WEB_VITALS_METRICS, DEFAULT_WEB_VITALS_METRICS, VTilt, vt as default, vt };
+export type { AliasEvent, CaptureOptions, CapturePerformanceConfig, CaptureResult, EventPayload, FeatureFlagsConfig, GeolocationData, GroupsConfig, PersistenceMethod, Properties, Property, PropertyOperations, RemoteConfig, RequestOptions, SessionData, SessionIdChangedCallback, SessionRecordingMaskInputOptions, SessionRecordingOptions, SupportedWebVitalsMetric, TrackingEvent, UserIdentity, UserProperties, VTiltConfig, WebVitalMetric };