@v-tilt/browser 1.3.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

@@ -78,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 */
@@ -289,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/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
@@ -42,6 +42,114 @@ export interface WebVitalsCallbacks {
     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
@@ -64,6 +172,8 @@ export interface VTiltExtensions {
     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

package/package.json

@@ -1,65 +1,66 @@
-{
-  "name": "@v-tilt/browser",
-  "version": "1.3.0",
-  "description": "vTilt browser tracking library",
-  "main": "dist/main.js",
-  "module": "dist/module.js",
-  "types": "dist/module.d.ts",
-  "files": [
-    "lib/*",
-    "dist/*"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -b && rollup -c",
-    "dev": "rollup -c -w",
-    "type-check": "tsc --noEmit",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
-    "clean": "rimraf lib dist",
-    "prepublishOnly": "pnpm run build"
-  },
-  "keywords": [
-    "analytics",
-    "tracking",
-    "web-vitals",
-    "performance"
-  ],
-  "author": "vTilt",
-  "license": "MIT",
-  "devDependencies": {
-    "@babel/preset-env": "^7.28.3",
-    "@rollup/plugin-babel": "^6.0.4",
-    "@rollup/plugin-commonjs": "^25.0.8",
-    "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^15.3.1",
-    "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^11.1.6",
-    "@types/node": "^20.10.5",
-    "@v-tilt/eslint-config": "workspace:*",
-    "eslint": "^9.0.0",
-    "rimraf": "^5.0.5",
-    "rollup": "^4.9.1",
-    "rollup-plugin-dts": "^6.2.3",
-    "rollup-plugin-terser": "^7.0.2",
-    "rollup-plugin-visualizer": "^6.0.3",
-    "typescript": "^5.3.3"
-  },
-  "dependencies": {
-    "@rrweb/record": "2.0.0-alpha.17",
-    "@rrweb/rrweb-plugin-console-record": "2.0.0-alpha.17",
-    "@rrweb/types": "2.0.0-alpha.17",
-    "fflate": "^0.8.2",
-    "web-vitals": "^3.5.0"
-  },
-  "peerDependencies": {
-    "web-vitals": "^3.0.0"
-  },
-  "peerDependenciesMeta": {
-    "web-vitals": {
-      "optional": true
-    }
-  }
-}
+{
+  "name": "@v-tilt/browser",
+  "version": "1.4.0",
+  "description": "vTilt browser tracking library",
+  "main": "dist/main.js",
+  "module": "dist/module.js",
+  "types": "dist/module.d.ts",
+  "files": [
+    "lib/*",
+    "dist/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b && rollup -c",
+    "dev": "rollup -c -w",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "clean": "rimraf lib dist",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": [
+    "analytics",
+    "tracking",
+    "web-vitals",
+    "performance"
+  ],
+  "author": "vTilt",
+  "license": "MIT",
+  "devDependencies": {
+    "@babel/preset-env": "^7.28.3",
+    "@rollup/plugin-babel": "^6.0.4",
+    "@rollup/plugin-commonjs": "^25.0.8",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.3.1",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/node": "^20.10.5",
+    "@v-tilt/eslint-config": "workspace:*",
+    "eslint": "^9.0.0",
+    "rimraf": "^5.0.5",
+    "rollup": "^4.9.1",
+    "rollup-plugin-dts": "^6.2.3",
+    "rollup-plugin-terser": "^7.0.2",
+    "rollup-plugin-visualizer": "^6.0.3",
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "@rrweb/record": "2.0.0-alpha.17",
+    "@rrweb/rrweb-plugin-console-record": "2.0.0-alpha.17",
+    "@rrweb/types": "2.0.0-alpha.17",
+    "ably": "^2.4.0",
+    "fflate": "^0.8.2",
+    "web-vitals": "^3.5.0"
+  },
+  "peerDependencies": {
+    "web-vitals": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "web-vitals": {
+      "optional": true
+    }
+  }
+}