@v-tilt/browser 1.2.0 → 1.4.0

package/lib/web-vitals.d.ts

@@ -1,11 +1,95 @@
-import { VTiltConfig } from "./types";
+import { VTiltConfig, SupportedWebVitalsMetric } from "./types";
 import { VTilt } from "./vtilt";
+/**
+ * Web Vitals Manager
+ *
+ * Captures Core Web Vitals (LCP, CLS, FCP, INP, TTFB) and sends them
+ * as batched $web_vitals events. Follows PostHog's approach with:
+ *
+ * 1. Extension pattern - checks for callbacks registered on __VTiltExtensions__
+ * 2. Lazy loading - loads web-vitals.js on demand if not bundled
+ * 3. Configurable metrics - choose which metrics to capture
+ * 4. Smart buffering - collects metrics per page, flushes on navigation or timeout
+ * 5. Session context - includes session_id and window_id for correlation
+ *
+ * Event structure:
+ * - event: "$web_vitals"
+ * - properties:
+ *   - $web_vitals_LCP_value: number
+ *   - $web_vitals_LCP_event: { name, value, delta, rating, ... }
+ *   - $pathname: string
+ *   - $current_url: string
+ */
 export declare class WebVitalsManager {
     private instance;
-    private webVitals;
-    constructor(config: VTiltConfig, instance: VTilt);
+    private buffer;
+    private flushTimer;
+    private initialized;
+    private config;
+    constructor(vtiltConfig: VTiltConfig, instance: VTilt);
     /**
-     * Initialize web vitals tracking
+     * Parse capture_performance config (boolean or object)
      */
-    private initializeWebVitals;
+    private parseConfig;
+    /**
+     * Check if web vitals capture is enabled
+     */
+    get isEnabled(): boolean;
+    /**
+     * Get the list of metrics to capture
+     */
+    get allowedMetrics(): SupportedWebVitalsMetric[];
+    /**
+     * Get flush timeout in ms
+     */
+    get flushTimeoutMs(): number;
+    /**
+     * Get maximum allowed metric value
+     */
+    get maxAllowedValue(): number;
+    private createEmptyBuffer;
+    /**
+     * Check if web vitals callbacks are available
+     */
+    private getWebVitalsCallbacks;
+    /**
+     * Start capturing if enabled and callbacks are available
+     */
+    startIfEnabled(): void;
+    /**
+     * Lazy load web-vitals extension
+     */
+    private loadWebVitals;
+    /**
+     * Start capturing web vitals using the provided callbacks
+     */
+    private startCapturing;
+    /**
+     * Get current URL
+     */
+    private getCurrentUrl;
+    /**
+     * Get current pathname
+     */
+    private getCurrentPathname;
+    /**
+     * Add a metric to the buffer
+     */
+    private addToBuffer;
+    /**
+     * Clean attribution data by removing large elements
+     */
+    private cleanAttribution;
+    /**
+     * Get window ID from instance
+     */
+    private getWindowId;
+    /**
+     * Schedule a delayed flush
+     */
+    private scheduleFlush;
+    /**
+     * Flush buffered metrics as a single event
+     */
+    private flush;
 }

package/lib/web-vitals.js

@@ -1,72 +1,380 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebVitalsManager = void 0;
-const geolocation_1 = require("./geolocation");
+const types_1 = require("./types");
 const globals_1 = require("./utils/globals");
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default timeout before flushing metrics (ms) */
+const DEFAULT_FLUSH_TIMEOUT_MS = 5000;
+/** Default maximum metric value (15 minutes in ms) - filters anomalies */
+const DEFAULT_MAX_METRIC_VALUE_MS = 15 * 60 * 1000;
+/** Minimum sensible max value (1 minute) - values below this use default */
+const MIN_SENSIBLE_MAX_VALUE_MS = 60 * 1000;
+const LOGGER_PREFIX = "[WebVitals]";
+// ============================================================================
+// WebVitalsManager
+// ============================================================================
+/**
+ * Web Vitals Manager
+ *
+ * Captures Core Web Vitals (LCP, CLS, FCP, INP, TTFB) and sends them
+ * as batched $web_vitals events. Follows PostHog's approach with:
+ *
+ * 1. Extension pattern - checks for callbacks registered on __VTiltExtensions__
+ * 2. Lazy loading - loads web-vitals.js on demand if not bundled
+ * 3. Configurable metrics - choose which metrics to capture
+ * 4. Smart buffering - collects metrics per page, flushes on navigation or timeout
+ * 5. Session context - includes session_id and window_id for correlation
+ *
+ * Event structure:
+ * - event: "$web_vitals"
+ * - properties:
+ *   - $web_vitals_LCP_value: number
+ *   - $web_vitals_LCP_event: { name, value, delta, rating, ... }
+ *   - $pathname: string
+ *   - $current_url: string
+ */
 class WebVitalsManager {
-    constructor(config, instance) {
+    constructor(vtiltConfig, instance) {
+        this.initialized = false;
         this.instance = instance;
-        // Load web-vitals if enabled and in browser environment (not SSR)
-        if (config.capture_performance && globals_1.window) {
-            try {
-                // Dynamically require web-vitals, ignore type error since it's a runtime import
-                // eslint-disable-next-line
-                this.webVitals = require("web-vitals");
-                this.initializeWebVitals();
+        this.buffer = this.createEmptyBuffer();
+        this.config = this.parseConfig(vtiltConfig.capture_performance);
+        if (this.isEnabled && globals_1.window) {
+            this.startIfEnabled();
+        }
+    }
+    // ==========================================================================
+    // Configuration
+    // ==========================================================================
+    /**
+     * Parse capture_performance config (boolean or object)
+     */
+    parseConfig(config) {
+        if (typeof config === "boolean") {
+            return { web_vitals: config };
+        }
+        if (typeof config === "object" && config !== null) {
+            return config;
+        }
+        return { web_vitals: false };
+    }
+    /**
+     * Check if web vitals capture is enabled
+     */
+    get isEnabled() {
+        // Always disable on non-http/https protocols (file://, chrome-extension://, etc.)
+        const protocol = globals_1.location === null || globals_1.location === void 0 ? void 0 : globals_1.location.protocol;
+        if (protocol !== "http:" && protocol !== "https:") {
+            return false;
+        }
+        return this.config.web_vitals !== false;
+    }
+    /**
+     * Get the list of metrics to capture
+     */
+    get allowedMetrics() {
+        return this.config.web_vitals_allowed_metrics || types_1.DEFAULT_WEB_VITALS_METRICS;
+    }
+    /**
+     * Get flush timeout in ms
+     */
+    get flushTimeoutMs() {
+        return this.config.web_vitals_delayed_flush_ms || DEFAULT_FLUSH_TIMEOUT_MS;
+    }
+    /**
+     * Get maximum allowed metric value
+     */
+    get maxAllowedValue() {
+        const configured = this.config.__web_vitals_max_value;
+        // If not configured, use default
+        if (configured === undefined) {
+            return DEFAULT_MAX_METRIC_VALUE_MS;
+        }
+        // 0 disables the check
+        if (configured === 0) {
+            return 0;
+        }
+        // Values below 1 minute are too aggressive, use default instead
+        if (configured < MIN_SENSIBLE_MAX_VALUE_MS) {
+            return DEFAULT_MAX_METRIC_VALUE_MS;
+        }
+        return configured;
+    }
+    // ==========================================================================
+    // Buffer Management
+    // ==========================================================================
+    createEmptyBuffer() {
+        return {
+            url: undefined,
+            pathname: undefined,
+            metrics: [],
+            firstMetricTimestamp: undefined,
+        };
+    }
+    // ==========================================================================
+    // Initialization
+    // ==========================================================================
+    /**
+     * Check if web vitals callbacks are available
+     */
+    getWebVitalsCallbacks() {
+        var _a;
+        return (_a = globals_1.assignableWindow.__VTiltExtensions__) === null || _a === void 0 ? void 0 : _a.webVitalsCallbacks;
+    }
+    /**
+     * Start capturing if enabled and callbacks are available
+     */
+    startIfEnabled() {
+        if (!this.isEnabled || this.initialized) {
+            return;
+        }
+        const callbacks = this.getWebVitalsCallbacks();
+        if (callbacks) {
+            // Callbacks already loaded (from array.full.ts bundle)
+            this.startCapturing(callbacks);
+        }
+        else {
+            // Try to lazy load web-vitals
+            this.loadWebVitals();
+        }
+    }
+    /**
+     * Lazy load web-vitals extension
+     */
+    loadWebVitals() {
+        var _a;
+        const loadExternalDependency = (_a = globals_1.assignableWindow.__VTiltExtensions__) === null || _a === void 0 ? void 0 : _a.loadExternalDependency;
+        if (!loadExternalDependency) {
+            console.warn(`${LOGGER_PREFIX} External dependency loader not available. ` +
+                `Include web-vitals.ts entrypoint or use array.full.js bundle.`);
+            return;
+        }
+        loadExternalDependency(this.instance, "web-vitals", (error) => {
+            if (error) {
+                console.error(`${LOGGER_PREFIX} Failed to load web-vitals:`, error);
+                return;
+            }
+            const callbacks = this.getWebVitalsCallbacks();
+            if (callbacks) {
+                this.startCapturing(callbacks);
+            }
+            else {
+                console.error(`${LOGGER_PREFIX} web-vitals loaded but callbacks not registered`);
+            }
+        });
+    }
+    /**
+     * Start capturing web vitals using the provided callbacks
+     */
+    startCapturing(callbacks) {
+        if (this.initialized) {
+            return;
+        }
+        const allowed = this.allowedMetrics;
+        const addMetric = this.addToBuffer.bind(this);
+        // Register callbacks only for allowed metrics
+        // Use reportAllChanges: true for CLS to get accurate final values
+        if (allowed.includes("LCP") && callbacks.onLCP) {
+            callbacks.onLCP(addMetric);
+        }
+        if (allowed.includes("CLS") && callbacks.onCLS) {
+            // CLS updates over time, so we want all changes
+            callbacks.onCLS(addMetric, { reportAllChanges: true });
+        }
+        if (allowed.includes("FCP") && callbacks.onFCP) {
+            callbacks.onFCP(addMetric);
+        }
+        if (allowed.includes("INP") && callbacks.onINP) {
+            callbacks.onINP(addMetric);
+        }
+        if (allowed.includes("TTFB") && callbacks.onTTFB) {
+            callbacks.onTTFB(addMetric);
+        }
+        this.initialized = true;
+    }
+    // ==========================================================================
+    // Metric Collection
+    // ==========================================================================
+    /**
+     * Get current URL
+     */
+    getCurrentUrl() {
+        var _a;
+        return (_a = globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.location) === null || _a === void 0 ? void 0 : _a.href;
+    }
+    /**
+     * Get current pathname
+     */
+    getCurrentPathname() {
+        return globals_1.location === null || globals_1.location === void 0 ? void 0 : globals_1.location.pathname;
+    }
+    /**
+     * Add a metric to the buffer
+     */
+    addToBuffer(metric) {
+        try {
+            // Only capture in browser environment
+            if (!globals_1.window || !globals_1.document || !globals_1.location) {
+                return;
+            }
+            // Validate metric
+            if (!(metric === null || metric === void 0 ? void 0 : metric.name) || (metric === null || metric === void 0 ? void 0 : metric.value) === undefined) {
+                console.warn(`${LOGGER_PREFIX} Invalid metric received`, metric);
+                return;
+            }
+            // Filter out anomalously large values (likely errors)
+            // CLS is unitless and typically < 1, so skip this check for CLS
+            if (this.maxAllowedValue > 0 &&
+                metric.value >= this.maxAllowedValue &&
+                metric.name !== "CLS") {
+                console.warn(`${LOGGER_PREFIX} Ignoring ${metric.name} with value >= ${this.maxAllowedValue}ms`);
+                return;
+            }
+            const currentUrl = this.getCurrentUrl();
+            const currentPathname = this.getCurrentPathname();
+            if (!currentUrl) {
+                console.warn(`${LOGGER_PREFIX} Could not determine current URL`);
+                return;
+            }
+            // If URL changed, flush existing buffer first
+            const urlChanged = this.buffer.url && this.buffer.url !== currentUrl;
+            if (urlChanged) {
+                this.flush();
+            }
+            // Initialize buffer URL if empty
+            if (!this.buffer.url) {
+                this.buffer.url = currentUrl;
+                this.buffer.pathname = currentPathname;
+            }
+            // Set first metric timestamp
+            if (!this.buffer.firstMetricTimestamp) {
+                this.buffer.firstMetricTimestamp = Date.now();
+            }
+            // Clean attribution data - remove large interactionTargetElement
+            const cleanedAttribution = this.cleanAttribution(metric.attribution);
+            // Get session context
+            const sessionId = this.instance.getSessionId();
+            const windowId = this.getWindowId();
+            // Create buffered metric with session context
+            const bufferedMetric = {
+                ...metric,
+                attribution: cleanedAttribution,
+                timestamp: Date.now(),
+                $current_url: currentUrl,
+                $session_id: sessionId,
+                $window_id: windowId,
+            };
+            // Find existing metric with same name and replace (later values are more accurate)
+            const existingIndex = this.buffer.metrics.findIndex((m) => m.name === metric.name);
+            if (existingIndex >= 0) {
+                this.buffer.metrics[existingIndex] = bufferedMetric;
             }
-            catch (error) {
-                console.warn("web-vitals library not found. Please install it to enable web vitals tracking.", error);
+            else {
+                this.buffer.metrics.push(bufferedMetric);
             }
+            // Schedule flush
+            this.scheduleFlush();
+            // If we have all expected metrics, flush immediately
+            if (this.buffer.metrics.length >= this.allowedMetrics.length) {
+                this.flush();
+            }
+        }
+        catch (error) {
+            console.error(`${LOGGER_PREFIX} Error adding metric to buffer:`, error);
+        }
+    }
+    /**
+     * Clean attribution data by removing large elements
+     */
+    cleanAttribution(attribution) {
+        if (!attribution) {
+            return undefined;
+        }
+        // Remove interactionTargetElement - it can be very large
+        // and isn't useful for analytics
+        const cleaned = { ...attribution };
+        if ("interactionTargetElement" in cleaned) {
+            delete cleaned.interactionTargetElement;
+        }
+        return cleaned;
+    }
+    /**
+     * Get window ID from instance
+     */
+    getWindowId() {
+        var _a;
+        // Access via internal session manager if available
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return ((_a = this.instance.sessionManager) === null || _a === void 0 ? void 0 : _a.getWindowId()) || null;
         }
+        catch (_b) {
+            return null;
+        }
+    }
+    // ==========================================================================
+    // Flushing
+    // ==========================================================================
+    /**
+     * Schedule a delayed flush
+     */
+    scheduleFlush() {
+        // Clear existing timer
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+        }
+        // Schedule new flush
+        this.flushTimer = setTimeout(() => {
+            this.flush();
+        }, this.flushTimeoutMs);
     }
     /**
-     * Initialize web vitals tracking
+     * Flush buffered metrics as a single event
      */
-    initializeWebVitals() {
-        if (!this.webVitals) {
+    flush() {
+        // Clear timer
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        // Check if we have any metrics to flush
+        if (this.buffer.metrics.length === 0) {
             return;
         }
-        const sendMetric = (metric) => {
-            try {
-                // Only send web vitals in browser environment (not SSR)
-                if (!globals_1.window || !globals_1.document || !globals_1.navigator || !globals_1.location) {
-                    return;
-                }
-                const { country, locale } = (0, geolocation_1.getCountryAndLocale)();
-                this.instance.capture("web_vital", {
+        try {
+            // Build event properties following PostHog's format
+            const properties = {
+                $pathname: this.buffer.pathname,
+                $current_url: this.buffer.url,
+            };
+            // Add each metric's value and full event object
+            for (const metric of this.buffer.metrics) {
+                // Add the numeric value (for easy percentile calculations)
+                properties[`$web_vitals_${metric.name}_value`] = metric.value;
+                // Add the full metric object (includes rating, delta, attribution, etc.)
+                properties[`$web_vitals_${metric.name}_event`] = {
                     name: metric.name,
                     value: metric.value,
                     delta: metric.delta,
                     rating: metric.rating,
                     id: metric.id,
                     navigationType: metric.navigationType,
-                    pathname: globals_1.location.pathname,
-                    href: globals_1.location.href,
-                    "user-agent": globals_1.navigator.userAgent,
-                    locale,
-                    location: country,
-                    referrer: globals_1.document.referrer,
-                });
+                    attribution: metric.attribution,
+                    $session_id: metric.$session_id,
+                    $window_id: metric.$window_id,
+                };
             }
-            catch (error) {
-                console.error("Error sending web vital:", error);
-            }
-        };
-        if (this.webVitals.onCLS) {
-            this.webVitals.onCLS(sendMetric);
-        }
-        if (this.webVitals.onFCP) {
-            this.webVitals.onFCP(sendMetric);
-        }
-        if (this.webVitals.onLCP) {
-            this.webVitals.onLCP(sendMetric);
-        }
-        if (this.webVitals.onTTFB) {
-            this.webVitals.onTTFB(sendMetric);
+            // Send the event
+            this.instance.capture("$web_vitals", properties);
         }
-        if (this.webVitals.onINP) {
-            this.webVitals.onINP(sendMetric);
+        catch (error) {
+            console.error(`${LOGGER_PREFIX} Error flushing metrics:`, error);
         }
+        // Reset buffer
+        this.buffer = this.createEmptyBuffer();
     }
 }
 exports.WebVitalsManager = WebVitalsManager;

package/package.json

@@ -1,65 +1,66 @@
-{
-  "name": "@v-tilt/browser",
-  "version": "1.2.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
+    }
+  }
+}