@v-tilt/browser 1.1.4 → 1.2.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 */
@@ -28,7 +35,7 @@ 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;
@@ -36,7 +43,12 @@ 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:
@@ -67,6 +79,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 */
@@ -105,7 +121,6 @@ interface TrackingEvent {
     timestamp: string;
     event: string;
     project_id: string;
-    domain: string;
     distinct_id: string;
     anonymous_id?: string;
     payload: EventPayload;
@@ -180,16 +195,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;
 }
 
 /**
@@ -209,6 +293,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)
  *
@@ -230,6 +458,7 @@ interface QueuedRequest {
 }
 
 declare class VTilt {
+    readonly version = "1.1.5";
     private configManager;
     private sessionManager;
     private userManager;
@@ -238,6 +467,7 @@ declare class VTilt {
     private retryQueue;
     private rateLimiter;
     historyAutocapture?: HistoryAutocapture;
+    sessionRecording?: SessionRecordingWrapper;
     __loaded: boolean;
     private _initial_pageview_captured;
     private _visibility_state_listener;
@@ -464,10 +694,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
@@ -490,4 +753,4 @@ 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 type { AliasEvent, CaptureOptions, CaptureResult, EventPayload, FeatureFlagsConfig, GeolocationData, GroupsConfig, PersistenceMethod, Properties, Property, PropertyOperations, RemoteConfig, RequestOptions, SessionData, SessionIdChangedCallback, SessionRecordingMaskInputOptions, SessionRecordingOptions, TrackingEvent, UserIdentity, UserProperties, VTiltConfig, WebVitalMetric };