@v-tilt/browser 1.0.11 → 1.1.1

package/lib/retry-queue.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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
+ */
+import type { BatchedRequest } from "./request-queue";
+/**
+ * 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
+ */
+export declare function pickNextRetryDelay(retriesPerformedSoFar: number): number;
+export interface RetryQueueConfig {
+    sendRequest: (req: BatchedRequest) => Promise<{
+        statusCode: number;
+    }>;
+    sendBeacon: (req: BatchedRequest) => void;
+}
+export declare class RetryQueue {
+    private _isPolling;
+    private _poller?;
+    private _pollIntervalMs;
+    private _queue;
+    private _areWeOnline;
+    private _sendRequest;
+    private _sendBeacon;
+    constructor(config: RetryQueueConfig);
+    /**
+     * Get current queue length
+     */
+    get length(): number;
+    /**
+     * Enqueue a failed request for retry
+     */
+    enqueue(request: BatchedRequest, retriesPerformedSoFar?: number): void;
+    /**
+     * Attempt to send a request with retry on failure
+     */
+    retriableRequest(request: BatchedRequest): Promise<void>;
+    /**
+     * Start polling for retries
+     */
+    private _poll;
+    /**
+     * Flush ready items from the queue
+     */
+    private _flush;
+    /**
+     * Flush all queued requests using sendBeacon on page unload
+     */
+    unload(): void;
+}

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/session.d.ts

@@ -1,9 +1,9 @@
-import { StorageMethod } from "./types";
+import { PersistenceMethod } from "./types";
 export declare class SessionManager {
     private storageMethod;
     private domain?;
     private _windowId;
-    constructor(storageMethod?: StorageMethod, domain?: string);
+    constructor(storageMethod?: PersistenceMethod, domain?: string);
     /**
      * Check if using web storage (localStorage or sessionStorage)
      */

package/lib/session.js

@@ -16,8 +16,8 @@ class SessionManager {
      * Check if using web storage (localStorage or sessionStorage)
      */
     _isWebStorage() {
-        return (this.storageMethod === constants_1.STORAGE_METHODS.localStorage ||
-            this.storageMethod === constants_1.STORAGE_METHODS.sessionStorage);
+        return (this.storageMethod === constants_1.PERSISTENCE_METHODS.localStorage ||
+            this.storageMethod === constants_1.PERSISTENCE_METHODS.sessionStorage);
     }
     /**
      * Get storage object (localStorage or sessionStorage)
@@ -26,7 +26,7 @@ class SessionManager {
         if (!this._isWebStorage()) {
             return null;
         }
-        return this.storageMethod === constants_1.STORAGE_METHODS.localStorage
+        return this.storageMethod === constants_1.PERSISTENCE_METHODS.localStorage
             ? localStorage
             : sessionStorage;
     }

package/lib/types.d.ts

@@ -1,68 +1,185 @@
+/**
+ * VTilt Types
+ *
+ * Type definitions for the VTilt tracking SDK.
+ * Following PostHog's patterns where applicable.
+ */
+import type { PersonProfilesMode } from './constants';
 export interface VTiltConfig {
-    projectId: string;
+    /** Project identifier (required) */
     token: string;
-    name?: string;
-    host?: string;
-    scriptHost?: string;
+    /** API host for tracking (default: https://api.vtilt.io) */
+    api_host?: string;
+    /** UI host for dashboard links */
+    ui_host?: string | null;
+    /** Proxy domain for tracking requests */
     proxy?: string;
+    /** Full proxy URL for tracking requests */
     proxyUrl?: string;
+    /** Instance name (for multiple instances) */
+    name?: string;
+    /** Project ID (set via init() first argument) */
+    projectId?: string;
+    /** Domain to track (auto-detected if not provided) */
     domain?: string;
-    storage?: "cookie" | "localStorage" | "sessionStorage";
+    /** Storage method for session data */
+    storage?: PersistenceMethod;
+    /** Persistence method for user data */
+    persistence?: PersistenceMethod;
+    /** Persistence name prefix */
+    persistence_name?: string;
+    /** Enable cross-subdomain cookies */
+    cross_subdomain_cookie?: boolean;
+    /**
+     * Person profiles mode:
+     * - 'always': Always create person profiles (default)
+     * - 'identified_only': Only create when user is identified
+     * - 'never': Never create person profiles
+     */
+    person_profiles?: PersonProfilesMode;
+    /** Enable autocapture */
+    autocapture?: boolean;
+    /** Enable web vitals tracking */
+    capture_performance?: boolean;
+    /** Enable page view tracking */
+    capture_pageview?: boolean | 'auto';
+    /** Enable page leave tracking */
+    capture_pageleave?: boolean | 'if_capture_pageview';
+    /** Disable compression */
+    disable_compression?: boolean;
+    /** Whether to stringify payload before sending */
     stringifyPayload?: boolean;
-    webVitals?: boolean;
+    /** Properties to exclude from events */
+    property_denylist?: string[];
+    /** Mask text in autocapture */
+    mask_all_text?: boolean;
+    /** Mask all element attributes */
+    mask_all_element_attributes?: boolean;
+    /** Respect Do Not Track browser setting */
+    respect_dnt?: boolean;
+    /** Opt users out by default */
+    opt_out_capturing_by_default?: boolean;
+    /** Global attributes added to all events */
     globalAttributes?: Record<string, string>;
-    persistence?: "localStorage" | "cookie";
-    crossSubdomainCookie?: boolean;
-}
-export interface SessionData {
-    value: string;
-    expiry: number;
-}
-export interface WebVitalMetric {
-    name: string;
-    value: number;
-    delta: number;
-    rating: string;
-    id: string;
-    navigationType: string;
-}
-export interface GeolocationData {
-    country?: string;
-    locale?: string;
+    /** Bootstrap data for initialization */
+    bootstrap?: {
+        distinctID?: string;
+        isIdentifiedID?: boolean;
+        featureFlags?: Record<string, boolean | string>;
+    };
+    /** Before send hook for modifying events */
+    before_send?: (event: CaptureResult) => CaptureResult | null;
+    /** Loaded callback */
+    loaded?: (vtilt: any) => void;
 }
 export interface EventPayload {
     [key: string]: any;
 }
+export interface CaptureResult {
+    uuid: string;
+    event: string;
+    properties: Properties;
+    $set?: Properties;
+    $set_once?: Properties;
+    timestamp?: string;
+}
+export interface CaptureOptions {
+    /** Override timestamp */
+    timestamp?: Date;
+    /** Properties to $set on person */
+    $set?: Properties;
+    /** Properties to $set_once on person */
+    $set_once?: Properties;
+    /** Send immediately (skip batching) */
+    send_instantly?: boolean;
+}
 export interface TrackingEvent {
     timestamp: string;
     event: string;
     project_id: string;
     domain: string;
-    payload: EventPayload;
-    distinct_id?: string;
+    distinct_id: string;
     anonymous_id?: string;
+    payload: EventPayload;
 }
-export type StorageMethod = "cookie" | "localStorage" | "sessionStorage";
-export interface StorageMethods {
-    cookie: "cookie";
-    localStorage: "localStorage";
-    sessionStorage: "sessionStorage";
+export type Property = string | number | boolean | null | undefined | Date | any[] | Record<string, any>;
+export interface Properties {
+    [key: string]: Property;
 }
+export interface PropertyOperations {
+    $set?: Properties;
+    $set_once?: Properties;
+    $unset?: string[];
+}
+export interface SessionData {
+    value: string;
+    expiry: number;
+}
+/**
+ * Persistence method for user/session data
+ * Following PostHog's approach:
+ * - 'localStorage+cookie': Stores limited data in cookies, rest in localStorage (default)
+ * - 'cookie': Stores all data in cookies
+ * - 'localStorage': Stores all data in localStorage
+ * - 'sessionStorage': Stores all data in sessionStorage
+ * - 'memory': Stores all data in memory only (no persistence)
+ */
+export type PersistenceMethod = 'localStorage+cookie' | 'cookie' | 'localStorage' | 'sessionStorage' | 'memory';
+/** User identity state */
 export interface UserIdentity {
+    /** Current distinct ID (null if anonymous) */
     distinct_id: string | null;
+    /** Anonymous ID (always present) */
     anonymous_id: string;
+    /** Device ID (persists across sessions) */
     device_id: string;
-    properties: Record<string, any>;
-    user_state: "anonymous" | "identified";
+    /** User properties */
+    properties: Properties;
+    /** Identity state */
+    user_state: 'anonymous' | 'identified';
 }
 export interface UserProperties {
     [key: string]: any;
 }
-export interface PropertyOperations {
-    $set?: Record<string, any>;
-    $set_once?: Record<string, any>;
-}
 export interface AliasEvent {
     distinct_id: string;
     original: string;
 }
+export interface WebVitalMetric {
+    name: string;
+    value: number;
+    delta: number;
+    rating: 'good' | 'needs-improvement' | 'poor';
+    id: string;
+    navigationType: string;
+}
+export interface GeolocationData {
+    country?: string;
+    locale?: string;
+}
+export interface GroupsConfig {
+    [groupType: string]: string;
+}
+export interface FeatureFlagsConfig {
+    [flagKey: string]: boolean | string;
+}
+export type SessionIdChangedCallback = (newSessionId: string, previousSessionId: string | null, changeInfo: {
+    reason: 'timeout' | 'new_session' | 'reset';
+}) => void;
+export interface RequestOptions {
+    method?: 'POST' | 'GET';
+    headers?: Record<string, string>;
+    timeout?: number;
+    retry?: boolean;
+}
+export interface RemoteConfig {
+    /** Default to identified_only mode */
+    defaultIdentifiedOnly?: boolean;
+    /** Feature flags */
+    featureFlags?: FeatureFlagsConfig;
+    /** Session recording config */
+    sessionRecording?: {
+        enabled?: boolean;
+        sampleRate?: number;
+    };
+}

package/lib/types.js

@@ -1,2 +1,8 @@
 "use strict";
+/**
+ * VTilt Types
+ *
+ * Type definitions for the VTilt tracking SDK.
+ * Following PostHog's patterns where applicable.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });

package/lib/user-manager.d.ts

@@ -1,10 +1,10 @@
-import { UserIdentity, AliasEvent, StorageMethod } from "./types";
+import { UserIdentity, AliasEvent, PersistenceMethod } from "./types";
 export declare class UserManager {
     private storageMethod;
     private domain?;
     private userIdentity;
     private _cachedPersonProperties;
-    constructor(storageMethod?: StorageMethod, domain?: string);
+    constructor(storageMethod?: PersistenceMethod, domain?: string);
     /**
      * Get current user identity
      */

package/lib/user-manager.js

@@ -30,7 +30,8 @@ class UserManager {
         if (!this.userIdentity.anonymous_id) {
             // Regenerate if somehow undefined
             this.userIdentity.anonymous_id = this.generateAnonymousId();
-            this.saveUserIdentity();
+            // Save to storage
+            this.setStoredValue(constants_1.ANONYMOUS_ID_KEY, this.userIdentity.anonymous_id);
         }
         return this.userIdentity.anonymous_id;
     }
@@ -467,13 +468,25 @@ class UserManager {
      */
     getStoredValue(key) {
         try {
-            if (this.storageMethod === constants_1.STORAGE_METHODS.localStorage) {
-                return localStorage.getItem(key);
+            // Memory mode doesn't persist - return null (will use in-memory userIdentity)
+            if (this.storageMethod === constants_1.PERSISTENCE_METHODS.memory) {
+                return null;
             }
-            else if (this.storageMethod === constants_1.STORAGE_METHODS.sessionStorage) {
-                return sessionStorage.getItem(key);
+            if (this.storageMethod === constants_1.PERSISTENCE_METHODS.localStorage ||
+                this.storageMethod === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie) {
+                // Try localStorage first for localStorage and localStorage+cookie modes
+                const value = localStorage.getItem(key);
+                if (value !== null) {
+                    return value;
+                }
+                // Fall back to cookie for localStorage+cookie mode
+                if (this.storageMethod === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie) {
+                    return this.getCookieValue(key);
+                }
+                return null;
             }
             else {
+                // Cookie-only mode
                 return this.getCookieValue(key);
             }
         }
@@ -488,13 +501,20 @@ class UserManager {
      */
     setStoredValue(key, value) {
         try {
-            if (this.storageMethod === constants_1.STORAGE_METHODS.localStorage) {
+            // Memory mode doesn't persist
+            if (this.storageMethod === constants_1.PERSISTENCE_METHODS.memory) {
+                return;
+            }
+            if (this.storageMethod === constants_1.PERSISTENCE_METHODS.localStorage) {
                 localStorage.setItem(key, value);
             }
-            else if (this.storageMethod === constants_1.STORAGE_METHODS.sessionStorage) {
-                sessionStorage.setItem(key, value);
+            else if (this.storageMethod === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie) {
+                // Store in both localStorage and cookie
+                localStorage.setItem(key, value);
+                this.setCookieValue(key, value);
             }
             else {
+                // Cookie-only mode
                 this.setCookieValue(key, value);
             }
         }
@@ -507,13 +527,20 @@ class UserManager {
      * Remove stored value from storage
      */
     removeStoredValue(key) {
-        if (this.storageMethod === constants_1.STORAGE_METHODS.localStorage) {
+        // Memory mode doesn't persist
+        if (this.storageMethod === constants_1.PERSISTENCE_METHODS.memory) {
+            return;
+        }
+        if (this.storageMethod === constants_1.PERSISTENCE_METHODS.localStorage) {
             localStorage.removeItem(key);
         }
-        else if (this.storageMethod === constants_1.STORAGE_METHODS.sessionStorage) {
-            sessionStorage.removeItem(key);
+        else if (this.storageMethod === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie) {
+            // Remove from both localStorage and cookie
+            localStorage.removeItem(key);
+            this.removeCookieValue(key);
         }
         else {
+            // Cookie-only mode
             this.removeCookieValue(key);
         }
     }