@v-tilt/browser 1.0.10 → 1.1.0

package/dist/request-queue.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Request Queue - Event Batching (PostHog-style)
+ *
+ * Batches multiple events together and sends them at configurable intervals.
+ * This reduces the number of HTTP requests significantly for active users.
+ *
+ * Features:
+ * - Configurable flush interval (default 3 seconds)
+ * - Batches events by URL/batchKey
+ * - Uses sendBeacon on page unload for reliable delivery
+ * - Converts absolute timestamps to relative offsets before sending
+ */
+import type { TrackingEvent } from "./types";
+export declare const DEFAULT_FLUSH_INTERVAL_MS = 3000;
+export interface QueuedRequest {
+    url: string;
+    event: TrackingEvent;
+    batchKey?: string;
+    transport?: "xhr" | "sendBeacon";
+}
+export interface BatchedRequest {
+    url: string;
+    events: TrackingEvent[];
+    batchKey?: string;
+    transport?: "xhr" | "sendBeacon";
+}
+export interface RequestQueueConfig {
+    flush_interval_ms?: number;
+}
+export declare class RequestQueue {
+    private _isPaused;
+    private _queue;
+    private _flushTimeout?;
+    private _flushTimeoutMs;
+    private _sendRequest;
+    constructor(sendRequest: (req: BatchedRequest) => void, config?: RequestQueueConfig);
+    /**
+     * Get the current queue length
+     */
+    get length(): number;
+    /**
+     * Enqueue an event for batched sending
+     */
+    enqueue(req: QueuedRequest): void;
+    /**
+     * Flush all queued events immediately using sendBeacon
+     * Called on page unload to ensure events are delivered
+     */
+    unload(): void;
+    /**
+     * Enable the queue and start flushing
+     */
+    enable(): void;
+    /**
+     * Pause the queue (stops flushing but keeps events)
+     */
+    pause(): void;
+    /**
+     * Force an immediate flush
+     */
+    flush(): void;
+    /**
+     * Set up the flush timeout
+     */
+    private _setFlushTimeout;
+    /**
+     * Clear the flush timeout
+     */
+    private _clearFlushTimeout;
+    /**
+     * Flush all queued events now
+     */
+    private _flushNow;
+    /**
+     * Format the queue into batched requests by URL/batchKey
+     */
+    private _formatQueue;
+}

package/dist/request.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Request utilities for vTilt tracking
+ *
+ * Handles HTTP requests with:
+ * - GZip compression (via fflate)
+ * - Multiple transport methods (fetch, XHR, sendBeacon)
+ * - Automatic fallback between transports
+ *
+ * Based on PostHog's request.ts pattern
+ */
+/**
+ * Compression methods supported by the SDK
+ */
+export declare enum Compression {
+    GZipJS = "gzip-js",
+    None = "none"
+}
+/**
+ * Response from a request
+ */
+export interface RequestResponse {
+    statusCode: number;
+    text?: string;
+    json?: any;
+}
+/**
+ * Options for making a request
+ */
+export interface RequestOptions {
+    url: string;
+    data?: any;
+    method?: "POST" | "GET";
+    headers?: Record<string, string>;
+    transport?: "XHR" | "fetch" | "sendBeacon";
+    compression?: Compression;
+    timeout?: number;
+    callback?: (response: RequestResponse) => void;
+}
+/**
+ * JSON stringify with BigInt support
+ */
+export declare const jsonStringify: (data: any) => string;
+/**
+ * Main request function - handles transport selection and dispatching
+ */
+export declare const request: (options: RequestOptions) => void;
+/**
+ * Promise-based request wrapper
+ */
+export declare const requestAsync: (options: Omit<RequestOptions, "callback">) => Promise<RequestResponse>;
+/**
+ * Check if compression is supported and beneficial
+ */
+export declare const shouldCompress: (data: any) => boolean;

package/dist/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/dist/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/dist/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/dist/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>;

package/dist/utils/index.d.ts

@@ -23,3 +23,24 @@ export declare function each<T>(obj: T[] | Record<string, T> | null | undefined,
  * This properly implements the default options for passive event listeners
  */
 export declare function addEventListener(element: Window | Document | Element | undefined, event: string, callback: EventListener, options?: AddEventListenerOptions): void;
+/**
+ * Extend object with properties from another object
+ */
+export declare function extend<T extends Record<string, any>>(target: T, source: Record<string, any> | null | undefined): T;
+/**
+ * Extend array with additional items
+ * Mutates the base array and returns it (matches PostHog's behavior)
+ */
+export declare function extendArray<T>(base: T[], ...additional: T[][]): T[];
+/**
+ * Strip properties with empty values (null, undefined, empty string)
+ */
+export declare function stripEmptyProperties<T extends Record<string, any>>(obj: T): Partial<T>;
+/**
+ * Strip leading dollar sign from string
+ */
+export declare function stripLeadingDollar(str: string): string;
+/**
+ * Check if value is null
+ */
+export declare function isNull(value: any): boolean;

package/dist/utils/request-utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Request utilities
+ * Functions for parsing URLs, query parameters, and masking sensitive data
+ */
+/**
+ * Convert string URL to HTMLAnchorElement for parsing
+ * IE11 doesn't support `new URL`, so we use anchor element
+ */
+export declare function convertToURL(url: string): HTMLAnchorElement | null;
+/**
+ * Get query parameter from URL
+ */
+export declare function getQueryParam(url: string, param: string): string;
+/**
+ * Mask query parameters in URL
+ */
+export declare function maskQueryParams<T extends string | undefined>(url: T, maskedParams: string[] | undefined, mask: string): T extends string ? string : undefined;

package/dist/vtilt.d.ts

@@ -1,20 +1,21 @@
 import { VTiltConfig, EventPayload } from "./types";
 import { HistoryAutocapture } from "./extensions/history-autocapture";
-interface QueuedRequest {
-    url: string;
-    event: any;
-}
+import { type QueuedRequest } from "./request-queue";
 export declare class VTilt {
     private configManager;
     private sessionManager;
     private userManager;
     private webVitalsManager;
+    private requestQueue;
+    private retryQueue;
+    private rateLimiter;
     historyAutocapture?: HistoryAutocapture;
     __loaded: boolean;
     private _initialPageviewCaptured;
     private _visibilityStateListener;
     __request_queue: QueuedRequest[];
     private _hasWarnedAboutConfig;
+    private _setOncePropertiesSent;
     constructor(config?: Partial<VTiltConfig>);
     /**
      * Initializes a new instance of the VTilt tracking object.
@@ -52,6 +53,11 @@ export declare class VTilt {
      * This internal method should only be called by `init()`.
      */
     private _init;
+    /**
+     * Set up handler to flush event queue on page unload
+     * Uses both beforeunload and pagehide for maximum compatibility
+     */
+    private _setupUnloadHandler;
     /**
      * Returns a string representation of the instance name
      * Used for debugging and logging
@@ -77,8 +83,26 @@ export declare 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
      */
     private sendRequest;
+    /**
+     * Send a batched request with multiple events
+     * Called by RequestQueue when flushing
+     * Uses RetryQueue for automatic retry on failure
+     */
+    private _sendBatchedRequest;
+    /**
+     * Send HTTP request and return status code
+     * Uses GZip compression for payloads > 1KB
+     * Used by RetryQueue for retryable requests
+     */
+    private _sendHttpRequest;
+    /**
+     * Send request using sendBeacon for reliable delivery on page unload
+     * Uses GZip compression for payloads > 1KB
+     */
+    private _sendBeaconRequest;
     /**
      * Send a queued request (called after DOM is loaded)
      */
@@ -86,13 +110,22 @@ export declare class VTilt {
     /**
      * Capture an event
      * Automatically adds common properties to all events
-     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser_language, etc.)
+     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser, $os, $device, $timezone, etc.)
+     * Only properties in EVENT_TO_PERSON_PROPERTIES are copied to person properties
      * Also adds title property for $pageview events only
      *
      * @param name - Event name
      * @param payload - Event payload
+     * @param options - Optional capture options
+     */
+    capture(name: string, payload: EventPayload, options?: {
+        skip_client_rate_limiting?: boolean;
+    }): void;
+    /**
+     * Internal capture method that bypasses rate limiting
+     * Used for system events like rate limit warnings
      */
-    capture(name: string, payload: EventPayload): void;
+    private _captureInternal;
     /**
      * Track a custom event (alias for capture)
      */
@@ -213,7 +246,7 @@ export declare class VTilt {
      */
     _execute_array(array: any[]): void;
     /**
-     * Called when DOM is loaded - processes queued requests
+     * Called when DOM is loaded - processes queued requests and enables batching
      */
     _dom_loaded(): void;
 }
@@ -253,4 +286,3 @@ export declare function init_as_module(): VTilt;
  * ]
  */
 export declare function init_from_snippet(): void;
-export {};

package/lib/constants.d.ts

@@ -7,5 +7,6 @@ export declare const DISTINCT_ID_KEY = "vt_distinct_id";
 export declare const DEVICE_ID_KEY = "vt_device_id";
 export declare const USER_PROPERTIES_KEY = "vt_user_properties";
 export declare const USER_STATE_KEY = "vt_user_state";
+export declare const INITIAL_PERSON_INFO = "$initial_person_info";
 export declare const STORAGE_METHODS: StorageMethods;
 export declare const TIMEZONES: Record<string, string>;

package/lib/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TIMEZONES = exports.STORAGE_METHODS = exports.USER_STATE_KEY = exports.USER_PROPERTIES_KEY = exports.DEVICE_ID_KEY = exports.DISTINCT_ID_KEY = exports.ANONYMOUS_ID_KEY = exports.PRIMARY_WINDOW_EXISTS_KEY = exports.WINDOW_ID_KEY = exports.STORAGE_KEY = void 0;
+exports.TIMEZONES = exports.STORAGE_METHODS = exports.INITIAL_PERSON_INFO = exports.USER_STATE_KEY = exports.USER_PROPERTIES_KEY = exports.DEVICE_ID_KEY = exports.DISTINCT_ID_KEY = exports.ANONYMOUS_ID_KEY = exports.PRIMARY_WINDOW_EXISTS_KEY = exports.WINDOW_ID_KEY = exports.STORAGE_KEY = void 0;
 exports.STORAGE_KEY = "vt_session_id";
 exports.WINDOW_ID_KEY = "vt_window_id";
 exports.PRIMARY_WINDOW_EXISTS_KEY = "vt_primary_window_exists";
@@ -9,6 +9,7 @@ exports.DISTINCT_ID_KEY = "vt_distinct_id";
 exports.DEVICE_ID_KEY = "vt_device_id";
 exports.USER_PROPERTIES_KEY = "vt_user_properties";
 exports.USER_STATE_KEY = "vt_user_state";
+exports.INITIAL_PERSON_INFO = "$initial_person_info";
 exports.STORAGE_METHODS = {
     cookie: "cookie",
     localStorage: "localStorage",

package/lib/rate-limiter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Rate Limiter - Token Bucket Algorithm (PostHog-style)
+ *
+ * Prevents runaway loops from flooding the server with events.
+ * Uses a token bucket algorithm with configurable rate and burst limits.
+ *
+ * Features:
+ * - Configurable events per second (default: 10)
+ * - Configurable burst limit (default: 100)
+ * - Token replenishment over time
+ * - Warning event when rate limited
+ */
+export declare const RATE_LIMIT_WARNING_EVENT = "$$client_ingestion_warning";
+export interface RateLimitBucket {
+    tokens: number;
+    last: number;
+}
+export interface RateLimiterConfig {
+    eventsPerSecond?: number;
+    eventsBurstLimit?: number;
+    persistence?: {
+        get: (key: string) => RateLimitBucket | null;
+        set: (key: string, value: RateLimitBucket) => void;
+    };
+    captureWarning?: (message: string) => void;
+}
+export declare class RateLimiter {
+    private eventsPerSecond;
+    private eventsBurstLimit;
+    private lastEventRateLimited;
+    private persistence?;
+    private captureWarning?;
+    constructor(config?: RateLimiterConfig);
+    /**
+     * Check if the client should be rate limited
+     *
+     * @param checkOnly - If true, don't consume a token (just check)
+     * @returns Object with isRateLimited flag and remaining tokens
+     */
+    checkRateLimit(checkOnly?: boolean): {
+        isRateLimited: boolean;
+        remainingTokens: number;
+    };
+    /**
+     * Check if an event should be allowed (consumes a token if allowed)
+     */
+    shouldAllowEvent(): boolean;
+    /**
+     * Get remaining tokens without consuming
+     */
+    getRemainingTokens(): number;
+}

package/lib/rate-limiter.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Rate Limiter - Token Bucket Algorithm (PostHog-style)
+ *
+ * Prevents runaway loops from flooding the server with events.
+ * Uses a token bucket algorithm with configurable rate and burst limits.
+ *
+ * Features:
+ * - Configurable events per second (default: 10)
+ * - Configurable burst limit (default: 100)
+ * - Token replenishment over time
+ * - Warning event when rate limited
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = exports.RATE_LIMIT_WARNING_EVENT = void 0;
+const RATE_LIMIT_STORAGE_KEY = "vt_rate_limit";
+exports.RATE_LIMIT_WARNING_EVENT = "$$client_ingestion_warning";
+class RateLimiter {
+    constructor(config = {}) {
+        var _a, _b;
+        this.lastEventRateLimited = false;
+        this.eventsPerSecond = (_a = config.eventsPerSecond) !== null && _a !== void 0 ? _a : 10;
+        this.eventsBurstLimit = Math.max((_b = config.eventsBurstLimit) !== null && _b !== void 0 ? _b : this.eventsPerSecond * 10, this.eventsPerSecond);
+        this.persistence = config.persistence;
+        this.captureWarning = config.captureWarning;
+        // Initialize lastEventRateLimited from current state
+        this.lastEventRateLimited = this.checkRateLimit(true).isRateLimited;
+    }
+    /**
+     * Check if the client should be rate limited
+     *
+     * @param checkOnly - If true, don't consume a token (just check)
+     * @returns Object with isRateLimited flag and remaining tokens
+     */
+    checkRateLimit(checkOnly = false) {
+        var _a, _b, _c, _d;
+        const now = Date.now();
+        // Get current bucket state from persistence or create new
+        const bucket = (_b = (_a = this.persistence) === null || _a === void 0 ? void 0 : _a.get(RATE_LIMIT_STORAGE_KEY)) !== null && _b !== void 0 ? _b : {
+            tokens: this.eventsBurstLimit,
+            last: now,
+        };
+        // Replenish tokens based on time elapsed
+        const secondsElapsed = (now - bucket.last) / 1000;
+        bucket.tokens += secondsElapsed * this.eventsPerSecond;
+        bucket.last = now;
+        // Cap tokens at burst limit
+        if (bucket.tokens > this.eventsBurstLimit) {
+            bucket.tokens = this.eventsBurstLimit;
+        }
+        const isRateLimited = bucket.tokens < 1;
+        // Consume a token if not just checking
+        if (!isRateLimited && !checkOnly) {
+            bucket.tokens = Math.max(0, bucket.tokens - 1);
+        }
+        // Capture warning event when first rate limited
+        if (isRateLimited && !this.lastEventRateLimited && !checkOnly) {
+            (_c = this.captureWarning) === null || _c === void 0 ? void 0 : _c.call(this, `vTilt client rate limited. Config: ${this.eventsPerSecond} events/second, ${this.eventsBurstLimit} burst limit.`);
+        }
+        this.lastEventRateLimited = isRateLimited;
+        (_d = this.persistence) === null || _d === void 0 ? void 0 : _d.set(RATE_LIMIT_STORAGE_KEY, bucket);
+        return {
+            isRateLimited,
+            remainingTokens: bucket.tokens,
+        };
+    }
+    /**
+     * Check if an event should be allowed (consumes a token if allowed)
+     */
+    shouldAllowEvent() {
+        return !this.checkRateLimit(false).isRateLimited;
+    }
+    /**
+     * Get remaining tokens without consuming
+     */
+    getRemainingTokens() {
+        return this.checkRateLimit(true).remainingTokens;
+    }
+}
+exports.RateLimiter = RateLimiter;