@v-tilt/browser 1.0.10 → 1.1.0

package/lib/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/lib/request-queue.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestQueue = exports.DEFAULT_FLUSH_INTERVAL_MS = void 0;
+exports.DEFAULT_FLUSH_INTERVAL_MS = 3000;
+/**
+ * Clamp a value to a range
+ */
+function clampToRange(value, min, max, defaultValue) {
+    if (typeof value !== "number" || isNaN(value)) {
+        return defaultValue;
+    }
+    return Math.min(Math.max(value, min), max);
+}
+class RequestQueue {
+    constructor(sendRequest, config) {
+        // We start in a paused state and only start flushing when enabled
+        this._isPaused = true;
+        this._queue = [];
+        this._flushTimeoutMs = clampToRange((config === null || config === void 0 ? void 0 : config.flush_interval_ms) || exports.DEFAULT_FLUSH_INTERVAL_MS, 250, // Min 250ms
+        5000, // Max 5 seconds
+        exports.DEFAULT_FLUSH_INTERVAL_MS);
+        this._sendRequest = sendRequest;
+    }
+    /**
+     * Get the current queue length
+     */
+    get length() {
+        return this._queue.length;
+    }
+    /**
+     * Enqueue an event for batched sending
+     */
+    enqueue(req) {
+        this._queue.push(req);
+        // Start flush timer if not already running
+        if (!this._flushTimeout) {
+            this._setFlushTimeout();
+        }
+    }
+    /**
+     * Flush all queued events immediately using sendBeacon
+     * Called on page unload to ensure events are delivered
+     */
+    unload() {
+        this._clearFlushTimeout();
+        if (this._queue.length === 0) {
+            return;
+        }
+        const requests = this._formatQueue();
+        // Send each batched request using sendBeacon for reliable delivery
+        for (const key in requests) {
+            const req = requests[key];
+            this._sendRequest({ ...req, transport: "sendBeacon" });
+        }
+    }
+    /**
+     * Enable the queue and start flushing
+     */
+    enable() {
+        this._isPaused = false;
+        this._setFlushTimeout();
+    }
+    /**
+     * Pause the queue (stops flushing but keeps events)
+     */
+    pause() {
+        this._isPaused = true;
+        this._clearFlushTimeout();
+    }
+    /**
+     * Force an immediate flush
+     */
+    flush() {
+        this._clearFlushTimeout();
+        this._flushNow();
+        this._setFlushTimeout();
+    }
+    /**
+     * Set up the flush timeout
+     */
+    _setFlushTimeout() {
+        if (this._isPaused) {
+            return;
+        }
+        this._flushTimeout = setTimeout(() => {
+            this._clearFlushTimeout();
+            this._flushNow();
+            // Restart the timeout for continuous flushing
+            if (this._queue.length > 0) {
+                this._setFlushTimeout();
+            }
+        }, this._flushTimeoutMs);
+    }
+    /**
+     * Clear the flush timeout
+     */
+    _clearFlushTimeout() {
+        if (this._flushTimeout) {
+            clearTimeout(this._flushTimeout);
+            this._flushTimeout = undefined;
+        }
+    }
+    /**
+     * Flush all queued events now
+     */
+    _flushNow() {
+        if (this._queue.length === 0) {
+            return;
+        }
+        const requests = this._formatQueue();
+        const now = Date.now();
+        for (const key in requests) {
+            const req = requests[key];
+            // Convert absolute timestamps to relative offsets
+            // This helps with clock skew between client and server
+            req.events.forEach((event) => {
+                const eventTime = new Date(event.timestamp).getTime();
+                event.$offset = Math.abs(eventTime - now);
+            });
+            this._sendRequest(req);
+        }
+    }
+    /**
+     * Format the queue into batched requests by URL/batchKey
+     */
+    _formatQueue() {
+        const requests = {};
+        this._queue.forEach((request) => {
+            const key = request.batchKey || request.url;
+            if (!requests[key]) {
+                requests[key] = {
+                    url: request.url,
+                    events: [],
+                    batchKey: request.batchKey,
+                };
+            }
+            requests[key].events.push(request.event);
+        });
+        // Clear the queue
+        this._queue = [];
+        return requests;
+    }
+}
+exports.RequestQueue = RequestQueue;

package/lib/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/lib/request.js

@@ -0,0 +1,265 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldCompress = exports.requestAsync = exports.request = exports.jsonStringify = exports.Compression = void 0;
+const fflate_1 = require("fflate");
+// Content types
+const CONTENT_TYPE_PLAIN = "text/plain";
+const CONTENT_TYPE_JSON = "application/json";
+// Compression threshold - skip compression for small payloads
+const MIN_COMPRESSION_SIZE = 1024; // 1KB
+/**
+ * Compression methods supported by the SDK
+ */
+var Compression;
+(function (Compression) {
+    Compression["GZipJS"] = "gzip-js";
+    Compression["None"] = "none";
+})(Compression || (exports.Compression = Compression = {}));
+/**
+ * JSON stringify with BigInt support
+ */
+const jsonStringify = (data) => {
+    return JSON.stringify(data, (_, value) => typeof value === "bigint" ? value.toString() : value);
+};
+exports.jsonStringify = jsonStringify;
+/**
+ * Encode request data with optional compression
+ */
+const encodePostData = (options) => {
+    const { data, compression } = options;
+    if (!data) {
+        return;
+    }
+    const jsonBody = (0, exports.jsonStringify)(data);
+    const estimatedSize = new Blob([jsonBody]).size;
+    // Use GZip compression if enabled and payload is large enough
+    if (compression === Compression.GZipJS &&
+        estimatedSize >= MIN_COMPRESSION_SIZE) {
+        try {
+            const gzipData = (0, fflate_1.gzipSync)((0, fflate_1.strToU8)(jsonBody), { mtime: 0 });
+            const blob = new Blob([gzipData], { type: CONTENT_TYPE_PLAIN });
+            // Only use compression if it actually reduces size
+            if (blob.size < estimatedSize * 0.95) {
+                return {
+                    contentType: CONTENT_TYPE_PLAIN,
+                    body: blob,
+                    estimatedSize: blob.size,
+                };
+            }
+        }
+        catch (_a) {
+            // Fallback to uncompressed on error
+        }
+    }
+    // Return uncompressed JSON
+    return {
+        contentType: CONTENT_TYPE_JSON,
+        body: jsonBody,
+        estimatedSize,
+    };
+};
+/**
+ * Send request using XMLHttpRequest
+ */
+const xhrRequest = (options) => {
+    const req = new XMLHttpRequest();
+    req.open(options.method || "POST", options.url, true);
+    const encoded = encodePostData(options);
+    if (!encoded) {
+        return;
+    }
+    const { contentType, body } = encoded;
+    // Set headers
+    if (options.headers) {
+        Object.entries(options.headers).forEach(([key, value]) => {
+            req.setRequestHeader(key, value);
+        });
+    }
+    req.setRequestHeader("Content-Type", contentType);
+    // Add compression indicator for gzip
+    if (contentType === CONTENT_TYPE_PLAIN &&
+        options.compression === Compression.GZipJS) {
+        req.setRequestHeader("Content-Encoding", "gzip");
+    }
+    if (options.timeout) {
+        req.timeout = options.timeout;
+    }
+    req.onreadystatechange = () => {
+        var _a;
+        if (req.readyState === 4) {
+            const response = {
+                statusCode: req.status,
+                text: req.responseText,
+            };
+            if (req.status === 200) {
+                try {
+                    response.json = JSON.parse(req.responseText);
+                }
+                catch (_b) {
+                    // Ignore parse errors
+                }
+            }
+            (_a = options.callback) === null || _a === void 0 ? void 0 : _a.call(options, response);
+        }
+    };
+    req.onerror = () => {
+        var _a;
+        (_a = options.callback) === null || _a === void 0 ? void 0 : _a.call(options, { statusCode: 0 });
+    };
+    req.send(body);
+};
+/**
+ * Send request using fetch API
+ */
+const fetchRequest = (options) => {
+    const encoded = encodePostData(options);
+    if (!encoded) {
+        return;
+    }
+    const { contentType, body, estimatedSize } = encoded;
+    const headers = {
+        "Content-Type": contentType,
+        ...(options.headers || {}),
+    };
+    // Add compression indicator for gzip
+    if (contentType === CONTENT_TYPE_PLAIN &&
+        options.compression === Compression.GZipJS) {
+        headers["Content-Encoding"] = "gzip";
+    }
+    const controller = new AbortController();
+    const timeoutId = options.timeout
+        ? setTimeout(() => controller.abort(), options.timeout)
+        : null;
+    fetch(options.url, {
+        method: options.method || "POST",
+        headers,
+        body,
+        // Use keepalive for smaller payloads to ensure delivery on page close
+        keepalive: estimatedSize < 64 * 1024 * 0.8,
+        signal: controller.signal,
+    })
+        .then(async (response) => {
+        var _a;
+        const text = await response.text();
+        const res = {
+            statusCode: response.status,
+            text,
+        };
+        if (response.status === 200) {
+            try {
+                res.json = JSON.parse(text);
+            }
+            catch (_b) {
+                // Ignore parse errors
+            }
+        }
+        (_a = options.callback) === null || _a === void 0 ? void 0 : _a.call(options, res);
+    })
+        .catch(() => {
+        var _a;
+        (_a = options.callback) === null || _a === void 0 ? void 0 : _a.call(options, { statusCode: 0 });
+    })
+        .finally(() => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    });
+};
+/**
+ * Send request using sendBeacon for reliable delivery on page unload
+ */
+const sendBeaconRequest = (options) => {
+    const encoded = encodePostData(options);
+    if (!encoded) {
+        return;
+    }
+    const { contentType, body } = encoded;
+    try {
+        // sendBeacon requires a Blob
+        const beaconBody = typeof body === "string" ? new Blob([body], { type: contentType }) : body;
+        // Add compression query param for server to detect
+        const url = options.compression === Compression.GZipJS &&
+            contentType === CONTENT_TYPE_PLAIN
+            ? `${options.url}${options.url.includes("?") ? "&" : "?"}compression=gzip-js`
+            : options.url;
+        navigator.sendBeacon(url, beaconBody);
+    }
+    catch (_a) {
+        // sendBeacon is best-effort, ignore errors
+    }
+};
+/**
+ * Available transport methods in order of preference
+ */
+const TRANSPORTS = [
+    {
+        name: "fetch",
+        available: typeof fetch !== "undefined",
+        method: fetchRequest,
+    },
+    {
+        name: "XHR",
+        available: typeof XMLHttpRequest !== "undefined",
+        method: xhrRequest,
+    },
+    {
+        name: "sendBeacon",
+        available: typeof navigator !== "undefined" && !!navigator.sendBeacon,
+        method: sendBeaconRequest,
+    },
+];
+/**
+ * Main request function - handles transport selection and dispatching
+ */
+const request = (options) => {
+    var _a;
+    const transport = options.transport || "fetch";
+    // Find the requested transport or fall back to first available
+    const transportConfig = TRANSPORTS.find((t) => t.name === transport && t.available) ||
+        TRANSPORTS.find((t) => t.available);
+    if (!transportConfig) {
+        console.error("vTilt: No available transport method");
+        (_a = options.callback) === null || _a === void 0 ? void 0 : _a.call(options, { statusCode: 0 });
+        return;
+    }
+    transportConfig.method(options);
+};
+exports.request = request;
+/**
+ * Promise-based request wrapper
+ */
+const requestAsync = (options) => {
+    return new Promise((resolve) => {
+        (0, exports.request)({
+            ...options,
+            callback: resolve,
+        });
+    });
+};
+exports.requestAsync = requestAsync;
+/**
+ * Check if compression is supported and beneficial
+ */
+const shouldCompress = (data) => {
+    if (typeof data === "undefined") {
+        return false;
+    }
+    try {
+        const size = new Blob([(0, exports.jsonStringify)(data)]).size;
+        return size >= MIN_COMPRESSION_SIZE;
+    }
+    catch (_a) {
+        return false;
+    }
+};
+exports.shouldCompress = shouldCompress;

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;
+}