@v-tilt/browser 1.0.11 → 1.1.0

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.
@@ -99,10 +125,30 @@ class VTilt {
         // 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
@@ -177,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)
@@ -193,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)
@@ -213,8 +319,9 @@ class VTilt {
      *
      * @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) {
@@ -223,6 +330,12 @@ 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, $os, $device, $timezone, etc.
@@ -241,14 +354,16 @@ 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 and $set_once from initial props
-        // Initial props are added to $set_once (only first time, preserves first values)
-        // Regular event properties that match EVENT_TO_PERSON_PROPERTIES will be added to $set by server
+        // 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 = {};
-        if (Object.keys(initialProps).length > 0) {
+        // 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);
         }
-        // Merge with user-provided $set_once if present
+        // Always merge with user-provided $set_once if present
         if (payload.$set_once) {
             Object.assign(setOnce, payload.$set_once);
         }
@@ -260,12 +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
+            // 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;
@@ -313,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)
      */
@@ -614,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,6 +1,6 @@
 {
   "name": "@v-tilt/browser",
-  "version": "1.0.11",
+  "version": "1.1.0",
   "description": "vTilt browser tracking library",
   "main": "dist/main.js",
   "module": "dist/module.js",
@@ -12,15 +12,6 @@
   "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",
@@ -38,16 +29,17 @@
     "@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"
+    "typescript": "^5.3.3",
+    "@v-tilt/eslint-config": "1.0.0"
   },
   "dependencies": {
+    "fflate": "^0.8.2",
     "web-vitals": "^3.5.0"
   },
   "peerDependencies": {
@@ -57,5 +49,13 @@
     "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"
   }
-}
+}