@v-tilt/browser 1.2.0 → 1.4.0

package/dist/module.d.ts

@@ -59,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 */
@@ -83,6 +86,10 @@ interface VTiltConfig {
     session_recording?: SessionRecordingOptions;
     /** Disable session recording (convenience flag) */
     disable_session_recording?: boolean;
+    /** Chat widget configuration */
+    chat?: ChatWidgetConfig;
+    /** Disable chat (convenience flag) */
+    disable_chat?: boolean;
     /** Global attributes added to all events */
     globalAttributes?: Record<string, string>;
     /** Bootstrap data for initialization */
@@ -168,6 +175,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;
@@ -175,6 +205,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;
@@ -267,6 +301,29 @@ interface SessionRecordingOptions {
     /** Internal: Mutation throttler bucket size */
     __mutationThrottlerBucketSize?: number;
 }
+/** Chat widget configuration */
+interface ChatWidgetConfig {
+    /** Enable/disable chat widget (default: auto from dashboard) */
+    enabled?: boolean;
+    /** Auto-fetch settings from dashboard (default: true) */
+    autoConfig?: boolean;
+    /** Widget position (default: 'bottom-right') */
+    position?: "bottom-right" | "bottom-left";
+    /** Widget header/greeting message */
+    greeting?: string;
+    /** Widget primary color */
+    color?: string;
+    /** Start in AI mode (default: true) */
+    aiMode?: boolean;
+    /** AI greeting message (first message from AI) */
+    aiGreeting?: string;
+    /** Preload widget script on idle vs on-demand */
+    preload?: boolean;
+    /** Offline message shown when business is unavailable */
+    offlineMessage?: string;
+    /** Collect email when offline */
+    collectEmailOffline?: boolean;
+}
 interface RemoteConfig {
     /** Default to identified_only mode */
     defaultIdentifiedOnly?: boolean;
@@ -377,6 +434,94 @@ interface SessionRecordingConfig {
 /** 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";
 
+/**
+ * Chat message structure (matches PostgreSQL chat_messages table)
+ * Note: Read status is determined by cursor comparison, not per-message
+ */
+interface ChatMessage {
+    id: string;
+    channel_id: string;
+    sender_type: "user" | "agent" | "ai" | "system";
+    sender_id: string | null;
+    sender_name: string | null;
+    sender_avatar_url: string | null;
+    content: string;
+    content_type: "text" | "html" | "attachment";
+    metadata: Record<string, unknown>;
+    created_at: string;
+}
+/**
+ * Chat channel structure (maps 1:1 to Ably channel)
+ */
+interface ChatChannel {
+    id: string;
+    project_id: string;
+    person_id: string;
+    distinct_id: string;
+    status: "open" | "closed" | "snoozed";
+    ai_mode: boolean;
+    unread_count: number;
+    last_message_at: string | null;
+    last_message_preview: string | null;
+    last_message_sender: "user" | "agent" | "ai" | "system" | null;
+    user_last_read_at: string | null;
+    agent_last_read_at: string | null;
+    created_at: string;
+}
+/**
+ * Chat widget configuration
+ *
+ * Settings can come from two sources:
+ * 1. Dashboard (fetched from /api/chat/settings) - "snippet-only" mode
+ * 2. Code config (passed to vt.init) - overrides dashboard settings
+ *
+ * This enables Intercom-like flexibility: just add snippet OR customize with code.
+ */
+interface ChatConfig {
+    /**
+     * Enable/disable chat widget.
+     * - undefined: Use dashboard setting (auto-fetch)
+     * - true: Enable (override dashboard)
+     * - false: Disable entirely
+     */
+    enabled?: boolean;
+    /**
+     * Auto-fetch settings from dashboard (default: true)
+     * When true, SDK fetches /api/chat/settings and uses those as base config.
+     * Code config always overrides fetched settings.
+     */
+    autoConfig?: boolean;
+    /** Widget position (default: 'bottom-right') */
+    position?: "bottom-right" | "bottom-left";
+    /** Widget header/greeting message */
+    greeting?: string;
+    /** Widget primary color */
+    color?: string;
+    /** Start in AI mode (default: true) */
+    aiMode?: boolean;
+    /** AI greeting message (first message from AI) */
+    aiGreeting?: string;
+    /** Preload widget script on idle vs on-demand */
+    preload?: boolean;
+    /** Custom theme */
+    theme?: ChatTheme;
+    /** Offline message shown when business is unavailable */
+    offlineMessage?: string;
+    /** Collect email when offline */
+    collectEmailOffline?: boolean;
+}
+/**
+ * Chat theme customization
+ */
+interface ChatTheme {
+    primaryColor?: string;
+    fontFamily?: string;
+    borderRadius?: string;
+    headerBgColor?: string;
+    userBubbleColor?: string;
+    agentBubbleColor?: string;
+}
+
 /**
  * Session Recording Wrapper
  *
@@ -437,6 +582,159 @@ declare class SessionRecordingWrapper {
     private _onScriptLoaded;
 }
 
+/**
+ * Message callback type
+ */
+type MessageCallback = (message: ChatMessage) => void;
+/**
+ * Typing callback type
+ */
+type TypingCallback = (isTyping: boolean, senderType: string) => void;
+/**
+ * Connection callback type
+ */
+type ConnectionCallback = (connected: boolean) => void;
+/**
+ * Unsubscribe function type
+ */
+type Unsubscribe = () => void;
+
+/**
+ * Chat Wrapper
+ *
+ * This is the lightweight class that lives in the main bundle.
+ * It handles:
+ * - Auto-fetching settings from dashboard (Intercom-like)
+ * - Merging server settings with code config
+ * - Deciding if chat should be enabled
+ * - Lazy loading the actual chat widget code
+ * - Delegating to LazyLoadedChat
+ * - Queuing messages/callbacks before widget loads
+ */
+declare class ChatWrapper {
+    private readonly _instance;
+    private _lazyLoadedChat;
+    private _config;
+    private _serverConfig;
+    private _configFetched;
+    private _isLoading;
+    private _loadError;
+    private _pendingMessages;
+    private _pendingCallbacks;
+    private _messageCallbacks;
+    private _typingCallbacks;
+    private _connectionCallbacks;
+    constructor(_instance: VTilt, config?: ChatConfig);
+    /**
+     * Whether the chat widget is open
+     */
+    get isOpen(): boolean;
+    /**
+     * Whether connected to realtime service
+     */
+    get isConnected(): boolean;
+    /**
+     * Whether the widget is loading
+     */
+    get isLoading(): boolean;
+    /**
+     * Number of unread messages
+     */
+    get unreadCount(): number;
+    /**
+     * Current channel (if any)
+     */
+    get channel(): ChatChannel | null;
+    /**
+     * Open the chat widget
+     */
+    open(): void;
+    /**
+     * Close the chat widget
+     */
+    close(): void;
+    /**
+     * Toggle the chat widget open/closed
+     */
+    toggle(): void;
+    /**
+     * Show the chat widget (make visible but not necessarily open)
+     */
+    show(): void;
+    /**
+     * Hide the chat widget
+     */
+    hide(): void;
+    /**
+     * Send a message
+     */
+    sendMessage(content: string): void;
+    /**
+     * Mark messages as read
+     */
+    markAsRead(): void;
+    /**
+     * Subscribe to new messages
+     */
+    onMessage(callback: MessageCallback): Unsubscribe;
+    /**
+     * Subscribe to typing indicators
+     */
+    onTyping(callback: TypingCallback): Unsubscribe;
+    /**
+     * Subscribe to connection changes
+     */
+    onConnectionChange(callback: ConnectionCallback): Unsubscribe;
+    /**
+     * Start chat if enabled, called by VTilt after init
+     *
+     * This method supports two modes (Intercom-like):
+     * 1. Auto-config: Fetch settings from /api/chat/settings (default)
+     * 2. Code-only: Use only code config (autoConfig: false)
+     */
+    startIfEnabled(): Promise<void>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<ChatConfig>): void;
+    /**
+     * Get the merged configuration (server + code, code takes precedence)
+     */
+    getMergedConfig(): ChatConfig;
+    /**
+     * Destroy the chat widget
+     */
+    destroy(): void;
+    private get _isChatEnabled();
+    /**
+     * Fetch chat settings from the server
+     * This enables "snippet-only" installation where widget configures from dashboard
+     */
+    private _fetchServerSettings;
+    /**
+     * Show the chat bubble (launcher button) without fully loading the widget
+     * This creates a lightweight bubble that loads the full widget on click
+     */
+    private _showBubble;
+    private get _scriptName();
+    /**
+     * Schedule preload on idle
+     */
+    private _schedulePreload;
+    /**
+     * Lazy load and then execute callback
+     */
+    private _lazyLoadAndThen;
+    /**
+     * Lazy load the chat script
+     */
+    private _lazyLoad;
+    /**
+     * Called after the chat script is loaded
+     */
+    private _onScriptLoaded;
+}
+
 /**
  * Request Queue - Event Batching (PostHog-style)
  *
@@ -468,6 +766,7 @@ declare class VTilt {
     private rateLimiter;
     historyAutocapture?: HistoryAutocapture;
     sessionRecording?: SessionRecordingWrapper;
+    chat?: ChatWrapper;
     __loaded: boolean;
     private _initial_pageview_captured;
     private _visibility_state_listener;
@@ -726,11 +1025,19 @@ declare class VTilt {
     /**
      * Check if session recording is active
      */
-    isSessionRecordingActive(): boolean;
+    isRecordingActive(): boolean;
     /**
      * Get session recording ID
      */
     getSessionRecordingId(): string | null;
+    /**
+     * Initialize chat widget
+     */
+    private _initChat;
+    /**
+     * Build chat config from VTiltConfig
+     */
+    private _buildChatConfig;
     /**
      * _execute_array() deals with processing any vTilt function
      * calls that were called before the vTilt library was loaded
@@ -752,5 +1059,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, SessionRecordingMaskInputOptions, SessionRecordingOptions, 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, ChatWidgetConfig, EventPayload, FeatureFlagsConfig, GeolocationData, GroupsConfig, PersistenceMethod, Properties, Property, PropertyOperations, RemoteConfig, RequestOptions, SessionData, SessionIdChangedCallback, SessionRecordingMaskInputOptions, SessionRecordingOptions, SupportedWebVitalsMetric, TrackingEvent, UserIdentity, UserProperties, VTiltConfig, WebVitalMetric };