@v-tilt/browser 1.8.0 → 1.10.0

package/dist/server.d.ts

@@ -13,6 +13,8 @@ interface RemoteConfig {
         enabled?: boolean;
         sampleRate?: number;
         minimumDurationMs?: number;
+        /** Full DOM snapshot interval in ms (default 300000 = 5 min). Higher = less data. */
+        fullSnapshotIntervalMs?: number;
         maskAllInputs?: boolean;
         maskAllText?: boolean;
         captureConsole?: boolean;

package/dist/types.d.ts

@@ -48,8 +48,12 @@ export interface VTiltConfig {
      * - 'never': Never create person profiles
      */
     person_profiles?: PersonProfilesMode;
-    /** Enable autocapture */
-    autocapture?: boolean;
+    /**
+     * Enable autocapture for automatic DOM event tracking.
+     * Can be a boolean or an object with detailed configuration.
+     * When true, captures clicks, form submissions, and input changes.
+     */
+    autocapture?: boolean | AutocaptureOptions;
     /**
      * Enable web vitals tracking.
      * Can be a boolean or an object with detailed configuration.
@@ -222,6 +226,48 @@ export interface RequestOptions {
     timeout?: number;
     retry?: boolean;
 }
+/**
+ * Autocapture configuration options
+ * Controls automatic DOM event tracking (clicks, form submissions, input changes)
+ */
+export interface AutocaptureOptions {
+    /**
+     * Enable autocapture (default: true when autocapture config is present)
+     */
+    enabled?: boolean;
+    /**
+     * URL patterns to allow autocapture on (default: all URLs)
+     * Supports strings (exact match) and RegExp patterns
+     */
+    url_allowlist?: (string | RegExp)[];
+    /**
+     * URL patterns to exclude from autocapture
+     * Supports strings (exact match) and RegExp patterns
+     */
+    url_ignorelist?: (string | RegExp)[];
+    /**
+     * DOM events to capture (default: ['click', 'change', 'submit'])
+     */
+    dom_event_allowlist?: ("click" | "change" | "submit")[];
+    /**
+     * Element tags to capture (default: ['a', 'button', 'form', 'input', 'select', 'textarea', 'label'])
+     */
+    element_allowlist?: string[];
+    /**
+     * CSS selectors to allow for capture (elements matching these are always captured)
+     * Example: ['[data-track]', '.track-click']
+     */
+    css_selector_allowlist?: string[];
+    /**
+     * Element attributes to exclude from capture
+     * Example: ['data-secret', 'aria-label']
+     */
+    element_attribute_ignorelist?: string[];
+    /**
+     * Capture text content from copy/cut events (default: false)
+     */
+    capture_copied_text?: boolean;
+}
 /** Mask options for input elements in session recording */
 export interface SessionRecordingMaskInputOptions {
     color?: boolean;
@@ -322,6 +368,8 @@ export interface RemoteConfig {
         enabled?: boolean;
         sampleRate?: number;
         minimumDurationMs?: number;
+        /** Full DOM snapshot interval in ms (default 300000 = 5 min). Higher = less data. */
+        fullSnapshotIntervalMs?: number;
         maskAllInputs?: boolean;
         maskAllText?: boolean;
         captureConsole?: boolean;

package/dist/utils/event-emitter.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Simple Event Emitter
+ *
+ * Lightweight pub/sub system for internal feature communication.
+ * Following PostHog's SimpleEventEmitter pattern.
+ */
+/**
+ * Event listener function type
+ */
+export type EventListener<T = unknown> = (payload: T) => void;
+/**
+ * Unsubscribe function returned by on()
+ */
+export type Unsubscribe = () => void;
+/**
+ * Simple event emitter for internal SDK communication.
+ * Features can emit and listen to events without direct coupling.
+ *
+ * @example
+ * ```typescript
+ * const emitter = new SimpleEventEmitter();
+ *
+ * // Subscribe to events
+ * const unsubscribe = emitter.on('user:identified', (data) => {
+ *   console.log('User identified:', data);
+ * });
+ *
+ * // Emit events
+ * emitter.emit('user:identified', { userId: '123' });
+ *
+ * // Unsubscribe when done
+ * unsubscribe();
+ * ```
+ */
+export declare class SimpleEventEmitter {
+    private _events;
+    private _onceEvents;
+    /**
+     * Subscribe to an event.
+     *
+     * @param event - Event name to subscribe to
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     */
+    on<T = unknown>(event: string, listener: EventListener<T>): Unsubscribe;
+    /**
+     * Subscribe to an event once (auto-unsubscribes after first call).
+     *
+     * @param event - Event name to subscribe to
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     */
+    once<T = unknown>(event: string, listener: EventListener<T>): Unsubscribe;
+    /**
+     * Emit an event to all listeners.
+     *
+     * @param event - Event name to emit
+     * @param payload - Data to pass to listeners
+     */
+    emit<T = unknown>(event: string, payload?: T): void;
+    /**
+     * Remove all listeners for an event.
+     *
+     * @param event - Event name (or undefined to remove all)
+     */
+    off(event?: string): void;
+    /**
+     * Get the number of listeners for an event.
+     *
+     * @param event - Event name
+     * @returns Number of listeners
+     */
+    listenerCount(event: string): number;
+    /**
+     * Check if there are any listeners for an event.
+     *
+     * @param event - Event name
+     * @returns True if there are listeners
+     */
+    hasListeners(event: string): boolean;
+}
+/**
+ * VTilt SDK Events
+ *
+ * Standard events emitted by the SDK for internal communication.
+ */
+export declare const VTiltEvents: {
+    readonly INITIALIZED: "sdk:initialized";
+    readonly CONFIG_UPDATED: "sdk:config_updated";
+    readonly REMOTE_CONFIG_LOADED: "sdk:remote_config_loaded";
+    readonly USER_IDENTIFIED: "user:identified";
+    readonly USER_RESET: "user:reset";
+    readonly USER_PROPERTIES_SET: "user:properties_set";
+    readonly SESSION_STARTED: "session:started";
+    readonly SESSION_ENDED: "session:ended";
+    readonly SESSION_ROTATED: "session:rotated";
+    readonly FEATURE_STARTED: "feature:started";
+    readonly FEATURE_STOPPED: "feature:stopped";
+    readonly EVENT_CAPTURED: "event:captured";
+    readonly EVENT_SENT: "event:sent";
+    readonly EVENT_FAILED: "event:failed";
+    readonly RECORDING_STARTED: "recording:started";
+    readonly RECORDING_STOPPED: "recording:stopped";
+    readonly ERROR: "error";
+};
+export type VTiltEventName = (typeof VTiltEvents)[keyof typeof VTiltEvents];

package/dist/utils/globals.d.ts

@@ -136,6 +136,29 @@ export interface ChatConfig {
     offlineMessage?: string;
     /** Collect email when offline */
     collectEmailOffline?: boolean;
+    /** Called when widget is opened */
+    onWidgetOpen?: () => void;
+    /** Called when widget is closed */
+    onWidgetClose?: (data: {
+        timeOpenSeconds: number;
+        messagesSent: number;
+    }) => void;
+    /** Called when a new conversation is started */
+    onConversationStart?: (data: {
+        channelId: string;
+        aiMode: boolean;
+    }) => void;
+    /** Called when user sends a message */
+    onMessageSent?: (data: {
+        channelId: string;
+        messageId: string;
+    }) => void;
+    /** Called when a message is received (from AI or agent) */
+    onMessageReceived?: (data: {
+        channelId: string;
+        messageId: string;
+        senderType: "ai" | "agent";
+    }) => void;
 }
 /**
  * Chat theme customization
@@ -177,6 +200,7 @@ export interface LazyLoadedChatInterface {
     onMessage(callback: (message: ChatMessage) => void): () => void;
     onTyping(callback: (isTyping: boolean, senderType: string) => void): () => void;
     onConnectionChange(callback: (connected: boolean) => void): () => void;
+    updateConfig?(config: ChatConfig): void;
     destroy(): void;
 }
 /**

package/dist/utils/index.d.ts

@@ -1,3 +1,6 @@
+export * from "./type-guards";
+export * from "./safewrap";
+export * from "./event-emitter";
 /**
  * Generate uuid to identify the session. Random, not data-derived
  */

package/dist/utils/safewrap.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Safe Wrapper Utilities
+ *
+ * Error isolation utilities to prevent feature errors from crashing the SDK.
+ * Following PostHog's safewrap pattern.
+ */
+/**
+ * Logger interface for error reporting
+ */
+interface Logger {
+    error: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+}
+/**
+ * Wrap a function to catch and log errors without throwing.
+ * Prevents errors in one feature from crashing the entire SDK.
+ *
+ * @param fn - The function to wrap
+ * @param context - Optional context string for error messages
+ * @param logger - Optional custom logger
+ * @returns Wrapped function that catches errors
+ *
+ * @example
+ * ```typescript
+ * const safeHandler = safewrap(
+ *   (event: Event) => this._handleEvent(event),
+ *   'Autocapture._handleEvent'
+ * );
+ * document.addEventListener('click', safeHandler);
+ * ```
+ */
+export declare function safewrap<F extends (...args: any[]) => any>(fn: F, context?: string, logger?: Logger): F;
+/**
+ * Try to execute a function and return undefined on error.
+ * Useful for one-off operations that might fail.
+ *
+ * @param fn - The function to try
+ * @param fallback - Optional fallback value on error
+ * @returns The result or fallback/undefined
+ *
+ * @example
+ * ```typescript
+ * const value = trySafe(() => JSON.parse(data), {});
+ * const element = trySafe(() => document.querySelector('.my-class'));
+ * ```
+ */
+export declare function trySafe<T>(fn: () => T): T | undefined;
+export declare function trySafe<T, F>(fn: () => T, fallback: F): T | F;
+/**
+ * Wrap all methods of a class prototype with safewrap.
+ * Useful for wrapping entire feature classes.
+ *
+ * @param Class - The class constructor
+ * @param methodNames - Array of method names to wrap
+ * @param logger - Optional custom logger
+ *
+ * @example
+ * ```typescript
+ * class MyFeature {
+ *   capture() { ... }
+ *   identify() { ... }
+ * }
+ * safewrapClass(MyFeature, ['capture', 'identify']);
+ * ```
+ */
+export declare function safewrapClass<T extends new (...args: any[]) => any>(Class: T, methodNames: (keyof InstanceType<T>)[], logger?: Logger): void;
+/**
+ * Create a safe event handler that won't break on errors.
+ * Specifically designed for DOM event handlers.
+ *
+ * @param handler - The event handler function
+ * @param context - Context string for error messages
+ * @returns Safe event handler
+ *
+ * @example
+ * ```typescript
+ * document.addEventListener('click', safeEventHandler(
+ *   (e) => this._onClick(e),
+ *   'Autocapture.onClick'
+ * ));
+ * ```
+ */
+export declare function safeEventHandler<E extends Event>(handler: (event: E) => void, context?: string): (event: E) => void;
+/**
+ * Execute an async function safely, catching any errors.
+ *
+ * @param fn - The async function to execute
+ * @param context - Context string for error messages
+ * @param logger - Optional custom logger
+ * @returns Promise that resolves to result or undefined
+ *
+ * @example
+ * ```typescript
+ * const result = await trySafeAsync(
+ *   () => fetch('/api/data'),
+ *   'fetchData'
+ * );
+ * ```
+ */
+export declare function trySafeAsync<T>(fn: () => Promise<T>, context?: string, logger?: Logger): Promise<T | undefined>;
+export {};

package/dist/utils/type-guards.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Type Guards
+ *
+ * Runtime type checking utilities for type-safe code.
+ * Following PostHog's pattern from @posthog/core.
+ */
+/**
+ * Check if value is a string
+ */
+export declare function isString(x: unknown): x is string;
+/**
+ * Check if value is a number (and not NaN)
+ */
+export declare function isNumber(x: unknown): x is number;
+/**
+ * Check if value is a boolean
+ */
+export declare function isBoolean(x: unknown): x is boolean;
+/**
+ * Check if value is undefined
+ */
+export declare function isUndefined(x: unknown): x is undefined;
+/**
+ * Check if value is null
+ */
+export declare function isNull(x: unknown): x is null;
+/**
+ * Check if value is null or undefined
+ */
+export declare function isNullish(x: unknown): x is null | undefined;
+/**
+ * Check if value is an array
+ */
+export declare function isArray(x: unknown): x is unknown[];
+/**
+ * Check if value is a plain object (not null, not array)
+ */
+export declare function isObject(x: unknown): x is Record<string, unknown>;
+/**
+ * Check if value is a function
+ */
+export declare function isFunction(x: unknown): x is Function;
+/**
+ * Check if value is a Date object
+ */
+export declare function isDate(x: unknown): x is Date;
+/**
+ * Check if value is a valid element
+ */
+export declare function isElement(x: unknown): x is Element;
+/**
+ * Check if value is a valid HTMLElement
+ */
+export declare function isHTMLElement(x: unknown): x is HTMLElement;
+/**
+ * Check if value is empty (null, undefined, empty string, empty array, empty object)
+ */
+export declare function isEmpty(x: unknown): boolean;
+/**
+ * Check if value is a non-empty string
+ */
+export declare function isNonEmptyString(x: unknown): x is string;
+/**
+ * Check if value is a positive number
+ */
+export declare function isPositiveNumber(x: unknown): x is number;
+/**
+ * Check if value is a RegExp
+ */
+export declare function isRegExp(x: unknown): x is RegExp;