@v-tilt/browser 1.2.0 → 1.4.0

package/lib/extensions/chat/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Chat Extension
+ *
+ * Exports for the chat widget extension.
+ * The main export is ChatWrapper which is included in the main bundle.
+ * The actual implementation (LazyLoadedChat) is loaded on demand.
+ */
+export { ChatWrapper } from "./chat-wrapper";
+export * from "./types";
+export type { ChatMessage, ChatChannel, ChatConfig, ChatTheme, LazyLoadedChatInterface, } from "../../utils/globals";

package/lib/extensions/chat/index.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Chat Extension
+ *
+ * Exports for the chat widget extension.
+ * The main export is ChatWrapper which is included in the main bundle.
+ * The actual implementation (LazyLoadedChat) is loaded on demand.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatWrapper = void 0;
+var chat_wrapper_1 = require("./chat-wrapper");
+Object.defineProperty(exports, "ChatWrapper", { enumerable: true, get: function () { return chat_wrapper_1.ChatWrapper; } });
+__exportStar(require("./types"), exports);

package/lib/extensions/chat/types.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Chat Extension Types
+ *
+ * Type definitions for the chat widget extension.
+ * Core types are re-exported from globals.ts for consistency.
+ */
+export type { ChatMessage, ChatChannel, ChatConfig, ChatTheme, LazyLoadedChatInterface, } from "../../utils/globals";
+/**
+ * Sender types for chat messages
+ */
+export type SenderType = "user" | "agent" | "ai" | "system";
+/**
+ * Channel status
+ */
+export type ChannelStatus = "open" | "closed" | "snoozed";
+/**
+ * Content types for messages
+ */
+export type ContentType = "text" | "html" | "attachment";
+/**
+ * Widget position options
+ */
+export type WidgetPosition = "bottom-right" | "bottom-left";
+/**
+ * Connection state for realtime
+ */
+export type ConnectionState = "connecting" | "connected" | "disconnected" | "error";
+/**
+ * Typing status event
+ */
+export interface TypingStatus {
+    channel_id: string;
+    sender_type: SenderType;
+    sender_id: string;
+    is_typing: boolean;
+    timestamp: number;
+}
+/**
+ * Presence status for users
+ */
+export interface PresenceStatus {
+    distinct_id: string;
+    status: "online" | "away" | "offline";
+    last_seen_at: string;
+    current_page_url?: string;
+}
+/**
+ * Chat event names for analytics tracking
+ */
+export declare const CHAT_EVENTS: {
+    readonly STARTED: "$chat_started";
+    readonly MESSAGE_SENT: "$chat_message_sent";
+    readonly MESSAGE_RECEIVED: "$chat_message_received";
+    readonly AI_HANDOFF: "$chat_ai_handoff";
+    readonly CLOSED: "$chat_closed";
+    readonly READ: "$chat_read";
+    readonly WIDGET_OPENED: "$chat_widget_opened";
+    readonly WIDGET_CLOSED: "$chat_widget_closed";
+};
+/**
+ * Chat event properties for $chat_message_sent
+ */
+export interface ChatMessageSentEventProperties {
+    $channel_id: string;
+    $message_id: string;
+    $content_preview: string;
+    $sender_type: SenderType;
+    $ai_mode: boolean;
+    $word_count: number;
+}
+/**
+ * Chat event properties for $chat_message_received
+ */
+export interface ChatMessageReceivedEventProperties {
+    $channel_id: string;
+    $message_id: string;
+    $content_preview: string;
+    $sender_type: SenderType;
+    $response_time_ms?: number;
+}
+/**
+ * Chat event properties for $chat_started
+ */
+export interface ChatStartedEventProperties {
+    $channel_id: string;
+    $initiated_by: "user" | "agent";
+    $ai_mode: boolean;
+}
+/**
+ * Chat event properties for $chat_closed
+ */
+export interface ChatClosedEventProperties {
+    $channel_id: string;
+    $resolved_by: "agent" | "user" | "system" | "auto";
+    $resolution: "resolved" | "unresolved" | "abandoned";
+    $message_count: number;
+    $duration_seconds: number;
+    $ai_only: boolean;
+}
+/**
+ * Internal widget state
+ */
+export interface ChatWidgetState {
+    isOpen: boolean;
+    isVisible: boolean;
+    isConnected: boolean;
+    isLoading: boolean;
+    unreadCount: number;
+    channel: import("../../utils/globals").ChatChannel | null;
+    messages: import("../../utils/globals").ChatMessage[];
+    isTyping: boolean;
+    typingSender: string | null;
+    agentLastReadAt: string | null;
+}
+/**
+ * Message callback type
+ */
+export type MessageCallback = (message: import("../../utils/globals").ChatMessage) => void;
+/**
+ * Typing callback type
+ */
+export type TypingCallback = (isTyping: boolean, senderType: string) => void;
+/**
+ * Connection callback type
+ */
+export type ConnectionCallback = (connected: boolean) => void;
+/**
+ * Unsubscribe function type
+ */
+export type Unsubscribe = () => void;
+/**
+ * API response for creating a channel
+ */
+export interface CreateChannelResponse {
+    channel: import("../../utils/globals").ChatChannel;
+    config: {
+        ai_enabled: boolean;
+        ai_greeting: string | null;
+        widget_greeting: string | null;
+    };
+}
+/**
+ * API response for sending a message
+ */
+export interface SendMessageResponse {
+    message: import("../../utils/globals").ChatMessage;
+    ai_response?: import("../../utils/globals").ChatMessage;
+}
+/**
+ * Ably realtime channel for chat
+ */
+export interface AblyChannel {
+    subscribe: (event: string, callback: (message: unknown) => void) => void;
+    unsubscribe: () => void;
+    publish: (event: string, data: unknown) => Promise<void>;
+}

package/lib/extensions/chat/types.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Chat Extension Types
+ *
+ * Type definitions for the chat widget extension.
+ * Core types are re-exported from globals.ts for consistency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHAT_EVENTS = void 0;
+/**
+ * Chat event names for analytics tracking
+ */
+exports.CHAT_EVENTS = {
+    STARTED: "$chat_started",
+    MESSAGE_SENT: "$chat_message_sent",
+    MESSAGE_RECEIVED: "$chat_message_received",
+    AI_HANDOFF: "$chat_ai_handoff",
+    CLOSED: "$chat_closed",
+    READ: "$chat_read",
+    WIDGET_OPENED: "$chat_widget_opened",
+    WIDGET_CLOSED: "$chat_widget_closed",
+};

package/lib/types.d.ts

@@ -51,8 +51,11 @@ export 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 */
@@ -75,6 +78,10 @@ export 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 */
@@ -160,6 +167,29 @@ export interface AliasEvent {
     distinct_id: string;
     original: string;
 }
+/** Supported Web Vitals metrics */
+export type SupportedWebVitalsMetric = "LCP" | "CLS" | "FCP" | "INP" | "TTFB";
+/** All supported Web Vitals metrics */
+export declare const ALL_WEB_VITALS_METRICS: SupportedWebVitalsMetric[];
+/** Default Web Vitals metrics (matches PostHog defaults) */
+export declare const DEFAULT_WEB_VITALS_METRICS: SupportedWebVitalsMetric[];
+/**
+ * Web Vitals capture configuration
+ */
+export 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;
+}
 export interface WebVitalMetric {
     name: string;
     value: number;
@@ -167,6 +197,10 @@ export 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>;
 }
 export interface GeolocationData {
     country?: string;
@@ -259,6 +293,29 @@ export interface SessionRecordingOptions {
     /** Internal: Mutation throttler bucket size */
     __mutationThrottlerBucketSize?: number;
 }
+/** Chat widget configuration */
+export 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;
+}
 export interface RemoteConfig {
     /** Default to identified_only mode */
     defaultIdentifiedOnly?: boolean;

package/lib/types.js

@@ -6,3 +6,19 @@
  * Following PostHog's patterns where applicable.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WEB_VITALS_METRICS = exports.ALL_WEB_VITALS_METRICS = void 0;
+/** All supported Web Vitals metrics */
+exports.ALL_WEB_VITALS_METRICS = [
+    "LCP",
+    "CLS",
+    "FCP",
+    "INP",
+    "TTFB",
+];
+/** Default Web Vitals metrics (matches PostHog defaults) */
+exports.DEFAULT_WEB_VITALS_METRICS = [
+    "LCP",
+    "CLS",
+    "FCP",
+    "INP",
+];

package/lib/utils/globals.d.ts

@@ -2,7 +2,7 @@ declare const win: (Window & typeof globalThis) | undefined;
 /**
  * Extension kinds that can be lazy loaded
  */
-export type VTiltExtensionKind = "recorder" | "web-vitals";
+export type VTiltExtensionKind = "recorder" | "web-vitals" | "chat";
 /**
  * Interface for lazy-loaded session recording (set by recorder.ts)
  * Matches LazyLoadedSessionRecordingInterface in session-recording-wrapper.ts
@@ -17,6 +17,139 @@ export interface LazyLoadedSessionRecordingInterface {
     log: (message: string, level: "log" | "warn" | "error") => void;
     updateConfig: (config: any) => void;
 }
+/**
+ * Web Vitals metric callback type
+ */
+export type WebVitalsMetricCallback = (metric: any) => void;
+/**
+ * Options for web vitals callbacks
+ */
+export interface WebVitalsCallbackOptions {
+    /** Report all changes (useful for CLS which updates over time) */
+    reportAllChanges?: boolean;
+}
+/**
+ * Web Vitals callback function type (with optional options)
+ */
+export type WebVitalsCallbackFn = (callback: WebVitalsMetricCallback, options?: WebVitalsCallbackOptions) => void;
+/**
+ * Web Vitals callbacks interface (set by web-vitals.ts entrypoint)
+ */
+export interface WebVitalsCallbacks {
+    onLCP: WebVitalsCallbackFn;
+    onCLS: WebVitalsCallbackFn;
+    onFCP: WebVitalsCallbackFn;
+    onINP: WebVitalsCallbackFn;
+    onTTFB?: WebVitalsCallbackFn;
+}
+/**
+ * Chat message structure (matches PostgreSQL chat_messages table)
+ * Note: Read status is determined by cursor comparison, not per-message
+ */
+export 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)
+ */
+export 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.
+ */
+export 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
+ */
+export interface ChatTheme {
+    primaryColor?: string;
+    fontFamily?: string;
+    borderRadius?: string;
+    headerBgColor?: string;
+    userBubbleColor?: string;
+    agentBubbleColor?: string;
+}
+/**
+ * Interface for lazy-loaded chat widget (set by chat.ts entrypoint)
+ */
+export interface LazyLoadedChatInterface {
+    readonly isOpen: boolean;
+    readonly isConnected: boolean;
+    readonly isLoading: boolean;
+    readonly unreadCount: number;
+    readonly channel: ChatChannel | null;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    show(): void;
+    hide(): void;
+    sendMessage(content: string): Promise<void>;
+    markAsRead(): void;
+    onMessage(callback: (message: ChatMessage) => void): () => void;
+    onTyping(callback: (isTyping: boolean, senderType: string) => void): () => void;
+    onConnectionChange(callback: (connected: boolean) => void): () => void;
+    destroy(): void;
+}
 /**
  * VTilt Extensions interface for dynamically loaded modules
  * This is the contract between lazily loaded extensions and the SDK
@@ -37,6 +170,10 @@ export interface VTiltExtensions {
     };
     /** Factory to create LazyLoadedSessionRecording (set by recorder.ts) */
     initSessionRecording?: (instance: any, config?: any) => LazyLoadedSessionRecordingInterface;
+    /** Web Vitals callbacks (set by web-vitals.ts entrypoint) */
+    webVitalsCallbacks?: WebVitalsCallbacks;
+    /** Factory to create LazyLoadedChat (set by chat.ts entrypoint) */
+    initChat?: (instance: any, config?: ChatConfig) => LazyLoadedChatInterface;
 }
 export type AssignableWindow = Window & typeof globalThis & {
     /** Main VTilt instance */

package/lib/vtilt.d.ts

@@ -1,6 +1,7 @@
 import { VTiltConfig, EventPayload } from "./types";
 import { HistoryAutocapture } from "./extensions/history-autocapture";
 import { SessionRecordingWrapper } from "./extensions/replay";
+import { ChatWrapper } from "./extensions/chat/chat-wrapper";
 import { type QueuedRequest } from "./request-queue";
 export declare class VTilt {
     readonly version = "1.1.5";
@@ -13,6 +14,7 @@ export declare class VTilt {
     private rateLimiter;
     historyAutocapture?: HistoryAutocapture;
     sessionRecording?: SessionRecordingWrapper;
+    chat?: ChatWrapper;
     __loaded: boolean;
     private _initial_pageview_captured;
     private _visibility_state_listener;
@@ -271,11 +273,19 @@ export 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

package/lib/vtilt.js

@@ -9,6 +9,7 @@ const user_manager_1 = require("./user-manager");
 const web_vitals_1 = require("./web-vitals");
 const history_autocapture_1 = require("./extensions/history-autocapture");
 const replay_1 = require("./extensions/replay");
+const chat_wrapper_1 = require("./extensions/chat/chat-wrapper");
 const request_1 = require("./request");
 const request_queue_1 = require("./request-queue");
 const retry_queue_1 = require("./retry-queue");
@@ -137,6 +138,8 @@ class VTilt {
         this.historyAutocapture.startIfEnabled();
         // Initialize session recording if enabled
         this._initSessionRecording();
+        // Initialize chat widget
+        this._initChat();
         // Set up page unload handler to flush queued events
         this._setup_unload_handler();
         // Enable the request queue for batched sending (PostHog pattern)
@@ -825,7 +828,7 @@ class VTilt {
     /**
      * Check if session recording is active
      */
-    isSessionRecordingActive() {
+    isRecordingActive() {
         var _a;
         return ((_a = this.sessionRecording) === null || _a === void 0 ? void 0 : _a.status) === "active";
     }
@@ -836,6 +839,44 @@ class VTilt {
         var _a;
         return ((_a = this.sessionRecording) === null || _a === void 0 ? void 0 : _a.sessionId) || null;
     }
+    // ============================================================================
+    // Chat
+    // ============================================================================
+    /**
+     * Initialize chat widget
+     */
+    _initChat() {
+        const config = this.configManager.getConfig();
+        // Don't initialize if explicitly disabled
+        if (config.disable_chat) {
+            return;
+        }
+        // Build chat config from VTiltConfig
+        const chatConfig = this._buildChatConfig(config);
+        // Create chat wrapper (lightweight - actual chat is lazy-loaded)
+        this.chat = new chat_wrapper_1.ChatWrapper(this, chatConfig);
+        // Start chat if enabled (this will fetch server settings and show bubble)
+        this.chat.startIfEnabled();
+    }
+    /**
+     * Build chat config from VTiltConfig
+     */
+    _buildChatConfig(config) {
+        var _a;
+        const chat = config.chat || {};
+        return {
+            enabled: chat.enabled,
+            autoConfig: (_a = chat.autoConfig) !== null && _a !== void 0 ? _a : true, // Default to auto-config from dashboard
+            position: chat.position,
+            greeting: chat.greeting,
+            color: chat.color,
+            aiMode: chat.aiMode,
+            aiGreeting: chat.aiGreeting,
+            preload: chat.preload,
+            offlineMessage: chat.offlineMessage,
+            collectEmailOffline: chat.collectEmailOffline,
+        };
+    }
     /**
      * _execute_array() deals with processing any vTilt function
      * calls that were called before the vTilt library was loaded