@v-tilt/browser 1.1.0 → 1.1.1

package/lib/vtilt.js

@@ -15,16 +15,28 @@ 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._initial_pageview_captured = false;
+        this._visibility_state_listener = null;
         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._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
@@ -42,7 +54,7 @@ class VTilt {
             eventsBurstLimit: 100,
             captureWarning: (message) => {
                 // Send rate limit warning event (bypasses rate limiting)
-                this._captureInternal(rate_limiter_1.RATE_LIMIT_WARNING_EVENT, {
+                this._capture_internal(rate_limiter_1.RATE_LIMIT_WARNING_EVENT, {
                     $$client_ingestion_warning_message: message,
                 });
             },
@@ -50,12 +62,12 @@ class VTilt {
         // 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),
+            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._sendBatchedRequest(req), { flush_interval_ms: 3000 });
+        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.
@@ -126,16 +138,32 @@ class VTilt {
         this.historyAutocapture = new history_autocapture_1.HistoryAutocapture(this);
         this.historyAutocapture.startIfEnabled();
         // Set up page unload handler to flush queued events
-        this._setupUnloadHandler();
+        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
      */
-    _setupUnloadHandler() {
+    _setup_unload_handler() {
         if (!globals_1.window) {
             return;
         }
@@ -183,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;
     }
@@ -201,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;
@@ -211,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 {
@@ -228,7 +256,7 @@ class VTilt {
     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)
@@ -248,11 +276,11 @@ class VTilt {
      * Called by RequestQueue when flushing
      * Uses RetryQueue for automatic retry on failure
      */
-    _sendBatchedRequest(req) {
+    _send_batched_request(req) {
         const { transport } = req;
         // Use sendBeacon for reliable delivery on page unload
         if (transport === "sendBeacon") {
-            this._sendBeaconRequest(req);
+            this._send_beacon_request(req);
             return;
         }
         // Use retry queue for normal requests (handles failures automatically)
@@ -263,7 +291,7 @@ class VTilt {
      * Uses GZip compression for payloads > 1KB
      * Used by RetryQueue for retryable requests
      */
-    _sendHttpRequest(req) {
+    _send_http_request(req) {
         return new Promise((resolve) => {
             const { url, events } = req;
             // Prepare payload (single event or batch)
@@ -288,7 +316,7 @@ class VTilt {
      * Send request using sendBeacon for reliable delivery on page unload
      * Uses GZip compression for payloads > 1KB
      */
-    _sendBeaconRequest(req) {
+    _send_beacon_request(req) {
         const { url, events } = req;
         // Prepare payload (single event or batch)
         const payload = events.length === 1 ? events[0] : { events };
@@ -360,7 +388,7 @@ class VTilt {
         // 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) {
+        if (!this._set_once_properties_sent && Object.keys(initialProps).length > 0) {
             Object.assign(setOnce, initialProps);
         }
         // Always merge with user-provided $set_once if present
@@ -382,8 +410,8 @@ class VTilt {
             ...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;
+        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) {
@@ -436,7 +464,7 @@ class VTilt {
      * Internal capture method that bypasses rate limiting
      * Used for system events like rate limit warnings
      */
-    _captureInternal(name, payload) {
+    _capture_internal(name, payload) {
         this.capture(name, payload, { skip_client_rate_limiting: true });
     }
     /**
@@ -506,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 || {},
             });
@@ -641,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;
         }
@@ -651,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)
@@ -676,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;
             }
         }
     }
@@ -741,16 +770,17 @@ class VTilt {
     }
     /**
      * Called when DOM is loaded - processes queued requests and enables batching
+     * Following PostHog's pattern in _dom_loaded()
      */
     _dom_loaded() {
-        // 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 legacy queue
         this.__request_queue = [];
+        // Enable the request queue for batched sending (PostHog pattern)
+        this._start_queue_if_opted_in();
     }
 }
 exports.VTilt = VTilt;
@@ -765,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;
 }
 /**
@@ -781,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.1.0",
+  "version": "1.1.1",
   "description": "vTilt browser tracking library",
   "main": "dist/main.js",
   "module": "dist/module.js",
@@ -12,6 +12,15 @@
   "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",
@@ -29,14 +38,14 @@
     "@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",
-    "@v-tilt/eslint-config": "1.0.0"
+    "typescript": "^5.3.3"
   },
   "dependencies": {
     "fflate": "^0.8.2",
@@ -49,13 +58,5 @@
     "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"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 Tinybird.co
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.