@v-tilt/browser 1.0.11 → 1.1.1

package/lib/vtilt.js

@@ -8,18 +8,35 @@ 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");
+/*
+STYLE GUIDE:
+
+Naming conventions:
+- snake_case: Config options and public API methods (e.g., capture_pageview, get_distinct_id)
+- camelCase: Internal variables and class properties (e.g., sessionManager, requestQueue)
+- _snake_case: Private methods that can be mangled/minified (e.g., _init, _dom_loaded)
+- __snake_case: Internal but not minified, signals internal use (e.g., __loaded, __request_queue)
+- UPPER_CASE: Constants and globals (e.g., PRIMARY_INSTANCE_NAME, ENQUEUE_REQUESTS)
+
+Use TypeScript accessibility modifiers (private/protected) for non-public members.
+*/
 // Helper to check if value is an array
 const isArray = Array.isArray;
 class VTilt {
     constructor(config = {}) {
         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._hasWarnedAboutConfig = false; // Track if we've already warned about missing config
+        this._initial_pageview_captured = false;
+        this._visibility_state_listener = null;
+        this.__request_queue = []; // Legacy queue for DOM loaded handler (pre-init)
+        this._has_warned_about_config = false; // Track if we've already warned about missing config
+        this._set_once_properties_sent = 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 +47,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._capture_internal(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._send_http_request(req),
+            sendBeacon: (req) => this._send_beacon_request(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._send_batched_request(req), { flush_interval_ms: 3000 });
     }
     /**
      * Initializes a new instance of the VTilt tracking object.
@@ -99,10 +137,46 @@ 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._setup_unload_handler();
+        // Enable the request queue for batched sending (PostHog pattern)
+        this._start_queue_if_opted_in();
         // Capture initial pageview (with visibility check)
-        this._captureInitialPageview();
+        // Only if capture_pageview is enabled (default: true)
+        if (fullConfig.capture_pageview !== false) {
+            this._capture_initial_pageview();
+        }
         return this;
     }
+    /**
+     * Start the request queue if user hasn't opted out
+     * Following PostHog's pattern - called from both _init() and _dom_loaded()
+     * Safe to call multiple times as enable() is idempotent
+     */
+    _start_queue_if_opted_in() {
+        // TODO: Add opt-out check when consent management is implemented
+        // if (!this.is_capturing()) return;
+        // Enable batched sending
+        this.requestQueue.enable();
+    }
+    /**
+     * Set up handler to flush event queue on page unload
+     * Uses both beforeunload and pagehide for maximum compatibility
+     */
+    _setup_unload_handler() {
+        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
@@ -137,16 +211,16 @@ class VTilt {
      * Returns true if projectId and token are present, false otherwise
      * Logs a warning only once per instance if not configured
      */
-    _isConfigured() {
+    _is_configured() {
         const config = this.configManager.getConfig();
         if (config.projectId && config.token) {
             return true;
         }
         // Only warn once to avoid console spam
-        if (!this._hasWarnedAboutConfig) {
+        if (!this._has_warned_about_config) {
             console.warn("VTilt: projectId and token are required for tracking. " +
                 "Events will be skipped until init() or updateConfig() is called with these fields.");
-            this._hasWarnedAboutConfig = true;
+            this._has_warned_about_config = true;
         }
         return false;
     }
@@ -155,8 +229,8 @@ class VTilt {
      */
     buildUrl() {
         const config = this.configManager.getConfig();
-        const { proxyUrl, proxy, host, token } = config;
-        // Use proxy endpoint to handle Tinybird authentication
+        const { proxyUrl, proxy, api_host, token } = config;
+        // Use proxy endpoint to handle backend authentication
         if (proxyUrl) {
             // Use the full proxy URL as provided
             return proxyUrl;
@@ -165,8 +239,8 @@ class VTilt {
             // Construct the proxy URL from the proxy domain with token
             return `${proxy}/api/tracking?token=${token}`;
         }
-        else if (host) {
-            const cleanHost = host.replace(/\/+$/gm, "");
+        else if (api_host) {
+            const cleanHost = api_host.replace(/\/+$/gm, "");
             return `${cleanHost}/api/tracking?token=${token}`;
         }
         else {
@@ -177,11 +251,12 @@ 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)
         // This is the single place where validation happens for all sending methods
-        if (!this._isConfigured()) {
+        if (!this._is_configured()) {
             return;
         }
         // Check if we should queue requests (for older browsers before DOM is loaded)
@@ -193,10 +268,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
+     */
+    _send_batched_request(req) {
+        const { transport } = req;
+        // Use sendBeacon for reliable delivery on page unload
+        if (transport === "sendBeacon") {
+            this._send_beacon_request(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
+     */
+    _send_http_request(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
+     */
+    _send_beacon_request(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 +347,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 +358,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 +382,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._set_once_properties_sent && 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 +403,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._set_once_properties_sent && Object.keys(initialProps).length > 0) {
+            this._set_once_properties_sent = true;
+        }
         // Add title only to $pageview events
         if (name === "$pageview" && globals_1.document) {
             enrichedPayload.title = globals_1.document.title;
@@ -313,6 +460,13 @@ class VTilt {
         };
         this.sendRequest(url, trackingEvent, true);
     }
+    /**
+     * Internal capture method that bypasses rate limiting
+     * Used for system events like rate limit warnings
+     */
+    _capture_internal(name, payload) {
+        this.capture(name, payload, { skip_client_rate_limiting: true });
+    }
     /**
      * Track a custom event (alias for capture)
      */
@@ -380,7 +534,7 @@ class VTilt {
             // New distinct_id and properties go in payload
             this.capture("$identify", {
                 distinct_id: newDistinctId, // New distinct_id in payload
-                $anon_distinct_id: previousDistinctId || anonymousId, // Previous ID in payload
+                $anon_distinct_id: anonymousId, // Previous ID in payload
                 $set: userPropertiesToSet || {},
                 $set_once: userPropertiesToSetOnce || {},
             });
@@ -515,8 +669,9 @@ class VTilt {
     }
     /**
      * Capture initial pageview with visibility check
+     * Note: The capture_pageview config check happens at the call site (in _init)
      */
-    _captureInitialPageview() {
+    _capture_initial_pageview() {
         if (!globals_1.document) {
             return;
         }
@@ -525,17 +680,17 @@ class VTilt {
         // This is useful to avoid `prerender` calls from Chrome/Wordpress/SPAs
         // that are not visible to the user
         if (globals_1.document.visibilityState !== "visible") {
-            if (!this._visibilityStateListener) {
-                this._visibilityStateListener = () => {
-                    this._captureInitialPageview();
+            if (!this._visibility_state_listener) {
+                this._visibility_state_listener = () => {
+                    this._capture_initial_pageview();
                 };
-                (0, utils_1.addEventListener)(globals_1.document, "visibilitychange", this._visibilityStateListener);
+                (0, utils_1.addEventListener)(globals_1.document, "visibilitychange", this._visibility_state_listener);
             }
             return;
         }
         // Extra check here to guarantee we only ever trigger a single initial pageview event
-        if (!this._initialPageviewCaptured) {
-            this._initialPageviewCaptured = true;
+        if (!this._initial_pageview_captured) {
+            this._initial_pageview_captured = true;
             // Wait a bit for SPA routers
             setTimeout(() => {
                 // Double-check we're still in browser environment (defensive check)
@@ -550,9 +705,9 @@ class VTilt {
                 this.capture("$pageview", payload);
             }, 300);
             // After we've captured the initial pageview, we can remove the listener
-            if (this._visibilityStateListener) {
-                globals_1.document.removeEventListener("visibilitychange", this._visibilityStateListener);
-                this._visibilityStateListener = null;
+            if (this._visibility_state_listener) {
+                globals_1.document.removeEventListener("visibilitychange", this._visibility_state_listener);
+                this._visibility_state_listener = null;
             }
         }
     }
@@ -614,15 +769,18 @@ class VTilt {
         });
     }
     /**
-     * Called when DOM is loaded - processes queued requests
+     * Called when DOM is loaded - processes queued requests and enables batching
+     * Following PostHog's pattern in _dom_loaded()
      */
     _dom_loaded() {
-        // Process all queued requests
+        // 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 = [];
+        // Enable the request queue for batched sending (PostHog pattern)
+        this._start_queue_if_opted_in();
     }
 }
 exports.VTilt = VTilt;
@@ -637,7 +795,8 @@ let ENQUEUE_REQUESTS = !SUPPORTS_REQUEST &&
     (globals_1.userAgent === null || globals_1.userAgent === void 0 ? void 0 : globals_1.userAgent.indexOf("MSIE")) === -1 &&
     (globals_1.userAgent === null || globals_1.userAgent === void 0 ? void 0 : globals_1.userAgent.indexOf("Mozilla")) === -1;
 // Expose ENQUEUE_REQUESTS to window for request queuing
-if (globals_1.window) {
+// Use typeof check to safely access global window object
+if (typeof globals_1.window !== "undefined" && globals_1.window !== null) {
     globals_1.window.__VTILT_ENQUEUE_REQUESTS = ENQUEUE_REQUESTS;
 }
 /**
@@ -653,7 +812,7 @@ const add_dom_loaded_handler = function () {
         dom_loaded_handler.done = true;
         // Disable request queuing now that DOM is loaded
         ENQUEUE_REQUESTS = false;
-        if (typeof globals_1.window !== "undefined") {
+        if (typeof globals_1.window !== "undefined" && globals_1.window !== null) {
             globals_1.window.__VTILT_ENQUEUE_REQUESTS = false;
         }
         // Process queued requests for all instances

package/lib/web-vitals.js

@@ -7,7 +7,7 @@ class WebVitalsManager {
     constructor(config, instance) {
         this.instance = instance;
         // Load web-vitals if enabled and in browser environment (not SSR)
-        if (config.webVitals && globals_1.window) {
+        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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v-tilt/browser",
-  "version": "1.0.11",
+  "version": "1.1.1",
   "description": "vTilt browser tracking library",
   "main": "dist/main.js",
   "module": "dist/module.js",
@@ -48,6 +48,7 @@
     "typescript": "^5.3.3"
   },
   "dependencies": {
+    "fflate": "^0.8.2",
     "web-vitals": "^3.5.0"
   },
   "peerDependencies": {