@v-tilt/browser 1.0.10 → 1.1.0

package/lib/vtilt.d.ts

@@ -1,20 +1,21 @@
 import { VTiltConfig, EventPayload } from "./types";
 import { HistoryAutocapture } from "./extensions/history-autocapture";
-interface QueuedRequest {
-    url: string;
-    event: any;
-}
+import { type QueuedRequest } from "./request-queue";
 export declare class VTilt {
     private configManager;
     private sessionManager;
     private userManager;
     private webVitalsManager;
+    private requestQueue;
+    private retryQueue;
+    private rateLimiter;
     historyAutocapture?: HistoryAutocapture;
     __loaded: boolean;
     private _initialPageviewCaptured;
     private _visibilityStateListener;
     __request_queue: QueuedRequest[];
     private _hasWarnedAboutConfig;
+    private _setOncePropertiesSent;
     constructor(config?: Partial<VTiltConfig>);
     /**
      * Initializes a new instance of the VTilt tracking object.
@@ -52,6 +53,11 @@ export declare class VTilt {
      * This internal method should only be called by `init()`.
      */
     private _init;
+    /**
+     * Set up handler to flush event queue on page unload
+     * Uses both beforeunload and pagehide for maximum compatibility
+     */
+    private _setupUnloadHandler;
     /**
      * Returns a string representation of the instance name
      * Used for debugging and logging
@@ -77,8 +83,26 @@ export declare class VTilt {
     /**
      * Send HTTP request
      * This is the central entry point for all tracking requests
+     * Events are batched and sent every 3 seconds for better performance
      */
     private sendRequest;
+    /**
+     * Send a batched request with multiple events
+     * Called by RequestQueue when flushing
+     * Uses RetryQueue for automatic retry on failure
+     */
+    private _sendBatchedRequest;
+    /**
+     * Send HTTP request and return status code
+     * Uses GZip compression for payloads > 1KB
+     * Used by RetryQueue for retryable requests
+     */
+    private _sendHttpRequest;
+    /**
+     * Send request using sendBeacon for reliable delivery on page unload
+     * Uses GZip compression for payloads > 1KB
+     */
+    private _sendBeaconRequest;
     /**
      * Send a queued request (called after DOM is loaded)
      */
@@ -86,13 +110,22 @@ export declare class VTilt {
     /**
      * Capture an event
      * Automatically adds common properties to all events
-     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser_language, etc.)
+     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser, $os, $device, $timezone, etc.)
+     * Only properties in EVENT_TO_PERSON_PROPERTIES are copied to person properties
      * Also adds title property for $pageview events only
      *
      * @param name - Event name
      * @param payload - Event payload
+     * @param options - Optional capture options
+     */
+    capture(name: string, payload: EventPayload, options?: {
+        skip_client_rate_limiting?: boolean;
+    }): void;
+    /**
+     * Internal capture method that bypasses rate limiting
+     * Used for system events like rate limit warnings
      */
-    capture(name: string, payload: EventPayload): void;
+    private _captureInternal;
     /**
      * Track a custom event (alias for capture)
      */
@@ -213,7 +246,7 @@ export declare class VTilt {
      */
     _execute_array(array: any[]): void;
     /**
-     * Called when DOM is loaded - processes queued requests
+     * Called when DOM is loaded - processes queued requests and enables batching
      */
     _dom_loaded(): void;
 }
@@ -253,4 +286,3 @@ export declare function init_as_module(): VTilt;
  * ]
  */
 export declare function init_from_snippet(): void;
-export {};

package/lib/vtilt.js

@@ -8,6 +8,10 @@ const session_1 = require("./session");
 const user_manager_1 = require("./user-manager");
 const web_vitals_1 = require("./web-vitals");
 const history_autocapture_1 = require("./extensions/history-autocapture");
+const request_1 = require("./request");
+const request_queue_1 = require("./request-queue");
+const retry_queue_1 = require("./retry-queue");
+const rate_limiter_1 = require("./rate-limiter");
 const utils_1 = require("./utils");
 const event_utils_1 = require("./utils/event-utils");
 const globals_1 = require("./utils/globals");
@@ -18,8 +22,9 @@ class VTilt {
         this.__loaded = false; // Matches snippet's window.vt.__loaded check
         this._initialPageviewCaptured = false;
         this._visibilityStateListener = null;
-        this.__request_queue = []; // Public for DOM loaded handler
+        this.__request_queue = []; // Legacy queue for DOM loaded handler (pre-init)
         this._hasWarnedAboutConfig = false; // Track if we've already warned about missing config
+        this._setOncePropertiesSent = false; // Track if $set_once with initial props has been sent (only send once per page load)
         this.configManager = new config_1.ConfigManager(config);
         const fullConfig = this.configManager.getConfig();
         // Auto-detect domain from location if not provided
@@ -30,6 +35,27 @@ class VTilt {
         this.sessionManager = new session_1.SessionManager(fullConfig.storage || "cookie", domain);
         this.userManager = new user_manager_1.UserManager(fullConfig.persistence || "localStorage", domain);
         this.webVitalsManager = new web_vitals_1.WebVitalsManager(fullConfig, this);
+        // Initialize rate limiter to prevent flooding
+        // Default: 10 events/second with burst of 100
+        this.rateLimiter = new rate_limiter_1.RateLimiter({
+            eventsPerSecond: 10,
+            eventsBurstLimit: 100,
+            captureWarning: (message) => {
+                // Send rate limit warning event (bypasses rate limiting)
+                this._captureInternal(rate_limiter_1.RATE_LIMIT_WARNING_EVENT, {
+                    $$client_ingestion_warning_message: message,
+                });
+            },
+        });
+        // Initialize retry queue for failed requests
+        // Retries with exponential backoff: 3s, 6s, 12s... up to 30 minutes
+        this.retryQueue = new retry_queue_1.RetryQueue({
+            sendRequest: (req) => this._sendHttpRequest(req),
+            sendBeacon: (req) => this._sendBeaconRequest(req),
+        });
+        // Initialize request queue for event batching
+        // Events are batched and sent every 3 seconds (configurable)
+        this.requestQueue = new request_queue_1.RequestQueue((req) => this._sendBatchedRequest(req), { flush_interval_ms: 3000 });
     }
     /**
      * Initializes a new instance of the VTilt tracking object.
@@ -93,13 +119,36 @@ class VTilt {
             name: name,
         });
         this.__loaded = true;
+        // Set initial person info: stores referrer and URL on first visit
+        const fullConfig = this.configManager.getConfig();
+        this.userManager.set_initial_person_info(fullConfig.mask_personal_data_properties, fullConfig.custom_personal_data_properties);
         // Initialize history autocapture
         this.historyAutocapture = new history_autocapture_1.HistoryAutocapture(this);
         this.historyAutocapture.startIfEnabled();
+        // Set up page unload handler to flush queued events
+        this._setupUnloadHandler();
         // Capture initial pageview (with visibility check)
         this._captureInitialPageview();
         return this;
     }
+    /**
+     * Set up handler to flush event queue on page unload
+     * Uses both beforeunload and pagehide for maximum compatibility
+     */
+    _setupUnloadHandler() {
+        if (!globals_1.window) {
+            return;
+        }
+        const unloadHandler = () => {
+            // Flush all queued events using sendBeacon for reliable delivery
+            this.requestQueue.unload();
+            // Also flush any pending retries
+            this.retryQueue.unload();
+        };
+        // beforeunload is more reliable but pagehide works better on mobile
+        (0, utils_1.addEventListener)(globals_1.window, "beforeunload", unloadHandler);
+        (0, utils_1.addEventListener)(globals_1.window, "pagehide", unloadHandler);
+    }
     /**
      * Returns a string representation of the instance name
      * Used for debugging and logging
@@ -174,6 +223,7 @@ class VTilt {
     /**
      * Send HTTP request
      * This is the central entry point for all tracking requests
+     * Events are batched and sent every 3 seconds for better performance
      */
     sendRequest(url, event, shouldEnqueue) {
         // Validate configuration (only warns once per instance)
@@ -190,10 +240,69 @@ class VTilt {
                 return;
             }
         }
-        const request = new XMLHttpRequest();
-        request.open("POST", url, true);
-        request.setRequestHeader("Content-Type", "application/json");
-        request.send(JSON.stringify(event));
+        // Enqueue event for batched sending
+        this.requestQueue.enqueue({ url, event });
+    }
+    /**
+     * Send a batched request with multiple events
+     * Called by RequestQueue when flushing
+     * Uses RetryQueue for automatic retry on failure
+     */
+    _sendBatchedRequest(req) {
+        const { transport } = req;
+        // Use sendBeacon for reliable delivery on page unload
+        if (transport === "sendBeacon") {
+            this._sendBeaconRequest(req);
+            return;
+        }
+        // Use retry queue for normal requests (handles failures automatically)
+        this.retryQueue.retriableRequest(req);
+    }
+    /**
+     * Send HTTP request and return status code
+     * Uses GZip compression for payloads > 1KB
+     * Used by RetryQueue for retryable requests
+     */
+    _sendHttpRequest(req) {
+        return new Promise((resolve) => {
+            const { url, events } = req;
+            // Prepare payload (single event or batch)
+            const payload = events.length === 1 ? events[0] : { events };
+            // Determine compression
+            const compression = this.configManager.getConfig().disable_compression
+                ? request_1.Compression.None
+                : request_1.Compression.GZipJS;
+            (0, request_1.request)({
+                url,
+                data: payload,
+                method: "POST",
+                transport: "XHR",
+                compression,
+                callback: (response) => {
+                    resolve({ statusCode: response.statusCode });
+                },
+            });
+        });
+    }
+    /**
+     * Send request using sendBeacon for reliable delivery on page unload
+     * Uses GZip compression for payloads > 1KB
+     */
+    _sendBeaconRequest(req) {
+        const { url, events } = req;
+        // Prepare payload (single event or batch)
+        const payload = events.length === 1 ? events[0] : { events };
+        // Determine compression
+        const compression = this.configManager.getConfig().disable_compression
+            ? request_1.Compression.None
+            : request_1.Compression.GZipJS;
+        (0, request_1.request)({
+            url,
+            data: payload,
+            method: "POST",
+            transport: "sendBeacon",
+            compression,
+        });
     }
     /**
      * Send a queued request (called after DOM is loaded)
@@ -204,13 +313,15 @@ class VTilt {
     /**
      * Capture an event
      * Automatically adds common properties to all events
-     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser_language, etc.)
+     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser, $os, $device, $timezone, etc.)
+     * Only properties in EVENT_TO_PERSON_PROPERTIES are copied to person properties
      * Also adds title property for $pageview events only
      *
      * @param name - Event name
      * @param payload - Event payload
+     * @param options - Optional capture options
      */
-    capture(name, payload) {
+    capture(name, payload, options) {
         this.sessionManager.setSessionId();
         // Only send events in browser environment (not SSR)
         if (!globals_1.navigator || !globals_1.navigator.userAgent) {
@@ -219,13 +330,22 @@ class VTilt {
         if (!(0, utils_1.isValidUserAgent)(globals_1.navigator.userAgent)) {
             return;
         }
+        // Check rate limiting (unless explicitly skipped)
+        if (!(options === null || options === void 0 ? void 0 : options.skip_client_rate_limiting) &&
+            !this.rateLimiter.shouldAllowEvent()) {
+            // Event is rate limited - drop it silently
+            return;
+        }
         const url = this.buildUrl();
         // Add properties to all events
-        // This includes: $current_url, $host, $pathname, $referrer, $referring_domain, $browser_language, etc.
+        // This includes: $current_url, $host, $pathname, $referrer, $referring_domain, $browser, $os, $device, $timezone, etc.
+        // (Only properties in EVENT_TO_PERSON_PROPERTIES are copied to person properties)
         const eventProperties = (0, event_utils_1.getEventProperties)();
         // Get person properties (includes $device_id and other user properties)
         // These are automatically included in all events
         const personProperties = this.userManager.getUserProperties();
+        // Get initial props: $initial_* properties from stored initial person info
+        const initialProps = this.userManager.get_initial_props();
         // Get session and window IDs
         // Both methods ensure IDs always exist (generate if needed)
         const session_id = this.sessionManager.getSessionId();
@@ -234,6 +354,19 @@ class VTilt {
         // This allows linking events with different distinct_ids that share the same anonymous_id
         // This is especially important for handling race conditions when $identify events arrive
         const anonymousId = this.userManager.getAnonymousId();
+        // Build $set_once from initial props (only on first event per page load)
+        // This optimization follows PostHog's pattern: initial props only need to be sent once
+        // since $set_once preserves first values. Sending them on every event would be redundant
+        // and cause unnecessary server processing for identity creation/updates.
+        const setOnce = {};
+        // Only include initial props if we haven't sent them yet this page load
+        if (!this._setOncePropertiesSent && Object.keys(initialProps).length > 0) {
+            Object.assign(setOnce, initialProps);
+        }
+        // Always merge with user-provided $set_once if present
+        if (payload.$set_once) {
+            Object.assign(setOnce, payload.$set_once);
+        }
         const enrichedPayload = {
             ...eventProperties, // Base properties for all events
             ...personProperties, // Person properties (includes $device_id)
@@ -242,8 +375,16 @@ class VTilt {
             // Always include $anon_distinct_id for identity linking (even for identified users)
             // This allows the server to merge identities proactively when events arrive out of order
             ...(anonymousId ? { $anon_distinct_id: anonymousId } : {}),
+            // Add $set_once with initial props (only if there are properties to set)
+            ...(Object.keys(setOnce).length > 0 ? { $set_once: setOnce } : {}),
+            // Merge user-provided $set if present
+            ...(payload.$set ? { $set: payload.$set } : {}),
             ...payload, // User-provided payload (can override base and person properties)
         };
+        // Mark that $set_once with initial props has been sent (only do this once per page load)
+        if (!this._setOncePropertiesSent && Object.keys(initialProps).length > 0) {
+            this._setOncePropertiesSent = true;
+        }
         // Add title only to $pageview events
         if (name === "$pageview" && globals_1.document) {
             enrichedPayload.title = globals_1.document.title;
@@ -291,6 +432,13 @@ class VTilt {
         };
         this.sendRequest(url, trackingEvent, true);
     }
+    /**
+     * Internal capture method that bypasses rate limiting
+     * Used for system events like rate limit warnings
+     */
+    _captureInternal(name, payload) {
+        this.capture(name, payload, { skip_client_rate_limiting: true });
+    }
     /**
      * Track a custom event (alias for capture)
      */
@@ -592,14 +740,16 @@ class VTilt {
         });
     }
     /**
-     * Called when DOM is loaded - processes queued requests
+     * Called when DOM is loaded - processes queued requests and enables batching
      */
     _dom_loaded() {
-        // Process all queued requests
+        // Enable the request queue for batched sending
+        this.requestQueue.enable();
+        // Process all pre-init queued requests
         this.__request_queue.forEach((item) => {
             this._send_retriable_request(item);
         });
-        // Clear the queue
+        // Clear the legacy queue
         this.__request_queue = [];
     }
 }

package/package.json

@@ -1,61 +1,61 @@
-{
-  "name": "@v-tilt/browser",
-  "version": "1.0.10",
-  "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": {
-    "web-vitals": "^3.5.0"
-  },
-  "peerDependencies": {
-    "web-vitals": "^3.0.0"
-  },
-  "peerDependenciesMeta": {
-    "web-vitals": {
-      "optional": true
-    }
-  }
-}
+{
+  "name": "@v-tilt/browser",
+  "version": "1.1.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"
+  },
+  "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",
+    "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",
+    "@v-tilt/eslint-config": "1.0.0"
+  },
+  "dependencies": {
+    "fflate": "^0.8.2",
+    "web-vitals": "^3.5.0"
+  },
+  "peerDependencies": {
+    "web-vitals": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "web-vitals": {
+      "optional": true
+    }
+  },
+  "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"
+  }
+}