@v-tilt/browser 1.0.10 → 1.1.0

package/lib/retry-queue.js

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * Retry Queue - Exponential Backoff (PostHog-style)
+ *
+ * Retries failed requests with jittered exponential backoff.
+ * Detects online/offline status and pauses retries when offline.
+ *
+ * Features:
+ * - Exponential backoff: 3s, 6s, 12s, 24s... up to 30 minutes
+ * - Jitter: +/- 50% to prevent thundering herd
+ * - Online/offline detection
+ * - Max 10 retries before giving up
+ * - Uses sendBeacon on page unload for final attempt
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryQueue = void 0;
+exports.pickNextRetryDelay = pickNextRetryDelay;
+const utils_1 = require("./utils");
+const globals_1 = require("./utils/globals");
+const THIRTY_MINUTES = 30 * 60 * 1000;
+const MAX_RETRIES = 10;
+/**
+ * Generates a jittered exponential backoff delay in milliseconds
+ *
+ * Base value is 3 seconds, doubled with each retry up to 30 minutes max.
+ * Each value has +/- 50% jitter.
+ *
+ * @param retriesPerformedSoFar - Number of retries already attempted
+ * @returns Delay in milliseconds
+ */
+function pickNextRetryDelay(retriesPerformedSoFar) {
+    const rawBackoffTime = 3000 * 2 ** retriesPerformedSoFar;
+    const minBackoff = rawBackoffTime / 2;
+    const cappedBackoffTime = Math.min(THIRTY_MINUTES, rawBackoffTime);
+    const jitterFraction = Math.random() - 0.5; // Random between -0.5 and 0.5
+    const jitter = jitterFraction * (cappedBackoffTime - minBackoff);
+    return Math.ceil(cappedBackoffTime + jitter);
+}
+class RetryQueue {
+    constructor(config) {
+        this._isPolling = false;
+        this._pollIntervalMs = 3000;
+        this._queue = [];
+        this._areWeOnline = true;
+        this._sendRequest = config.sendRequest;
+        this._sendBeacon = config.sendBeacon;
+        // Set up online/offline detection
+        if (globals_1.window && typeof globals_1.navigator !== "undefined" && "onLine" in globals_1.navigator) {
+            this._areWeOnline = globals_1.navigator.onLine;
+            (0, utils_1.addEventListener)(globals_1.window, "online", () => {
+                this._areWeOnline = true;
+                this._flush();
+            });
+            (0, utils_1.addEventListener)(globals_1.window, "offline", () => {
+                this._areWeOnline = false;
+            });
+        }
+    }
+    /**
+     * Get current queue length
+     */
+    get length() {
+        return this._queue.length;
+    }
+    /**
+     * Enqueue a failed request for retry
+     */
+    enqueue(request, retriesPerformedSoFar = 0) {
+        // Don't retry if we've exceeded max retries
+        if (retriesPerformedSoFar >= MAX_RETRIES) {
+            console.warn(`VTilt: Request failed after ${MAX_RETRIES} retries, giving up`);
+            return;
+        }
+        const msToNextRetry = pickNextRetryDelay(retriesPerformedSoFar);
+        const retryAt = Date.now() + msToNextRetry;
+        this._queue.push({
+            retryAt,
+            request,
+            retriesPerformedSoFar: retriesPerformedSoFar + 1,
+        });
+        let logMessage = `VTilt: Enqueued failed request for retry in ${Math.round(msToNextRetry / 1000)}s`;
+        if (!this._areWeOnline) {
+            logMessage += " (Browser is offline)";
+        }
+        console.warn(logMessage);
+        // Start polling if not already
+        if (!this._isPolling) {
+            this._isPolling = true;
+            this._poll();
+        }
+    }
+    /**
+     * Attempt to send a request with retry on failure
+     */
+    async retriableRequest(request) {
+        try {
+            const response = await this._sendRequest(request);
+            // Retry on server errors (5xx) or network errors (0)
+            // Don't retry on client errors (4xx)
+            if (response.statusCode !== 200 &&
+                (response.statusCode < 400 || response.statusCode >= 500)) {
+                this.enqueue(request, 0);
+            }
+        }
+        catch (_a) {
+            // Network error - enqueue for retry
+            this.enqueue(request, 0);
+        }
+    }
+    /**
+     * Start polling for retries
+     */
+    _poll() {
+        if (this._poller) {
+            clearTimeout(this._poller);
+        }
+        this._poller = setTimeout(() => {
+            if (this._areWeOnline && this._queue.length > 0) {
+                this._flush();
+            }
+            // Continue polling if there are items in queue
+            if (this._queue.length > 0) {
+                this._poll();
+            }
+            else {
+                this._isPolling = false;
+            }
+        }, this._pollIntervalMs);
+    }
+    /**
+     * Flush ready items from the queue
+     */
+    _flush() {
+        const now = Date.now();
+        const notReady = [];
+        const ready = [];
+        this._queue.forEach((item) => {
+            if (item.retryAt < now) {
+                ready.push(item);
+            }
+            else {
+                notReady.push(item);
+            }
+        });
+        this._queue = notReady;
+        // Retry ready items
+        ready.forEach(async ({ request, retriesPerformedSoFar }) => {
+            try {
+                const response = await this._sendRequest(request);
+                // If still failing, re-enqueue
+                if (response.statusCode !== 200 &&
+                    (response.statusCode < 400 || response.statusCode >= 500)) {
+                    this.enqueue(request, retriesPerformedSoFar);
+                }
+            }
+            catch (_a) {
+                // Network error - re-enqueue
+                this.enqueue(request, retriesPerformedSoFar);
+            }
+        });
+    }
+    /**
+     * Flush all queued requests using sendBeacon on page unload
+     */
+    unload() {
+        if (this._poller) {
+            clearTimeout(this._poller);
+            this._poller = undefined;
+        }
+        // Attempt final send of all queued requests
+        this._queue.forEach(({ request }) => {
+            try {
+                this._sendBeacon(request);
+            }
+            catch (e) {
+                console.error("VTilt: Failed to send beacon on unload", e);
+            }
+        });
+        this._queue = [];
+    }
+}
+exports.RetryQueue = RetryQueue;

package/lib/types.d.ts

@@ -13,6 +13,7 @@ export interface VTiltConfig {
     globalAttributes?: Record<string, string>;
     persistence?: "localStorage" | "cookie";
     crossSubdomainCookie?: boolean;
+    disable_compression?: boolean;
 }
 export interface SessionData {
     value: string;

package/lib/user-manager.d.ts

@@ -159,4 +159,25 @@ export declare class UserManager {
      * Remove cookie value
      */
     private removeCookieValue;
+    /**
+     * Register a value once (only if not already set)
+     * Stores properties in localStorage only if they don't already exist
+     */
+    private register_once;
+    /**
+     * Set initial person info
+     * Stores referrer and URL info on first visit for generating $initial_* properties
+     */
+    set_initial_person_info(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): void;
+    /**
+     * Get initial props
+     * Generates $initial_* properties from stored initial person info
+     * These are sent with events as $set_once to preserve first values
+     */
+    get_initial_props(): Record<string, any>;
+    /**
+     * Update referrer info
+     * Stores current referrer information if not already stored
+     */
+    update_referrer_info(): void;
 }

package/lib/user-manager.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.UserManager = void 0;
 const constants_1 = require("./constants");
 const utils_1 = require("./utils");
+const event_utils_1 = require("./utils/event-utils");
 class UserManager {
     constructor(storageMethod = "localStorage", domain) {
         this._cachedPersonProperties = null; // Cache for deduplication
@@ -570,5 +571,70 @@ class UserManager {
         }
         document.cookie = cookieValue;
     }
+    /**
+     * Register a value once (only if not already set)
+     * Stores properties in localStorage only if they don't already exist
+     */
+    register_once(props, defaultValues) {
+        const stored = this.getStoredUserProperties();
+        let changed = false;
+        for (const key in props) {
+            if (Object.prototype.hasOwnProperty.call(props, key)) {
+                if (!(key in stored)) {
+                    stored[key] = props[key];
+                    changed = true;
+                }
+            }
+        }
+        if (defaultValues) {
+            for (const key in defaultValues) {
+                if (Object.prototype.hasOwnProperty.call(defaultValues, key)) {
+                    if (!(key in stored)) {
+                        stored[key] = defaultValues[key];
+                        changed = true;
+                    }
+                }
+            }
+        }
+        if (changed) {
+            this.setStoredUserProperties(stored);
+        }
+    }
+    /**
+     * Set initial person info
+     * Stores referrer and URL info on first visit for generating $initial_* properties
+     */
+    set_initial_person_info(maskPersonalDataProperties, customPersonalDataProperties) {
+        const stored = this.getStoredUserProperties();
+        // Check if already set (backwards compatibility check)
+        if (stored[constants_1.INITIAL_PERSON_INFO]) {
+            return;
+        }
+        const personInfo = (0, event_utils_1.getPersonInfo)(maskPersonalDataProperties, customPersonalDataProperties);
+        this.register_once({
+            [constants_1.INITIAL_PERSON_INFO]: personInfo,
+        }, undefined);
+    }
+    /**
+     * Get initial props
+     * Generates $initial_* properties from stored initial person info
+     * These are sent with events as $set_once to preserve first values
+     */
+    get_initial_props() {
+        const stored = this.getStoredUserProperties();
+        const initialPersonInfo = stored[constants_1.INITIAL_PERSON_INFO];
+        if (!initialPersonInfo) {
+            return {};
+        }
+        return (0, event_utils_1.getInitialPersonPropsFromInfo)(initialPersonInfo);
+    }
+    /**
+     * Update referrer info
+     * Stores current referrer information if not already stored
+     */
+    update_referrer_info() {
+        const referrerInfo = (0, event_utils_1.getReferrerInfo)();
+        this.register_once(referrerInfo, undefined);
+    }
 }
 exports.UserManager = UserManager;

package/lib/utils/event-utils.d.ts

@@ -1,34 +1,52 @@
 /**
- * Get browser language
- * Returns the browser's language setting (e.g., "en-US")
+ * Event utilities
+ * Functions for extracting event properties, campaign parameters, and person info
  */
-export declare function getBrowserLanguage(): string | undefined;
+export declare const PERSONAL_DATA_CAMPAIGN_PARAMS: string[];
+export declare const CAMPAIGN_PARAMS: string[];
+export declare const EVENT_TO_PERSON_PROPERTIES: string[];
+export declare const MASKED = "<masked>";
+export declare const COOKIE_CAMPAIGN_PARAMS: string[];
 /**
- * Get browser language prefix
- * Returns the language code without region (e.g., "en" from "en-US")
+ * Get campaign parameters from URL
+ * Extracts UTM and other campaign tracking parameters from current page URL
+ * Masks personal data parameters if configured
  */
+export declare function getCampaignParams(customTrackedParams?: string[], maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[] | undefined): Record<string, string>;
+export declare function getSearchInfo(): Record<string, any>;
+export declare function getBrowserLanguage(): string | undefined;
 export declare function getBrowserLanguagePrefix(): string | undefined;
+export declare function getReferrer(): string;
+export declare function getReferringDomain(): string;
 /**
- * Get referrer
- * Returns document.referrer or '$direct' if no referrer
+ * Get referrer information
+ * Returns current referrer and referring domain
  */
-export declare function getReferrer(): string;
+export declare function getReferrerInfo(): Record<string, any>;
 /**
- * Get referring domain
- * Returns the hostname of the referrer URL or '$direct' if no referrer
+ * Get person info for initial storage
+ * Extracts referrer and URL info, masks personal data if configured
+ * Returns compact format (r: referrer, u: url) for storage efficiency
  */
-export declare function getReferringDomain(): string;
+export declare function getPersonInfo(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): {
+    r: string;
+    u: string | undefined;
+};
 /**
- * Get timezone
- * Returns the timezone (e.g., "America/New_York")
+ * Convert person info to person properties
+ * Extracts referrer, URL, campaign params, and search info from stored person info
  */
-export declare function getTimezone(): string | undefined;
+export declare function getPersonPropsFromInfo(info: Record<string, any>): Record<string, any>;
 /**
- * Get timezone offset
- * Returns the timezone offset in minutes
+ * Convert person info to initial person properties
+ * Generates $initial_* properties from person info (preserves first values)
  */
+export declare function getInitialPersonPropsFromInfo(info: Record<string, any>): Record<string, any>;
+export declare function getTimezone(): string | undefined;
 export declare function getTimezoneOffset(): number | undefined;
 /**
  * Get event properties that should be added to all events
+ * Returns all event context properties (browser, device, URL, etc.) plus event metadata
+ * Note: Only properties in EVENT_TO_PERSON_PROPERTIES are copied to person properties
  */
-export declare function getEventProperties(): Record<string, any>;
+export declare function getEventProperties(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): Record<string, any>;