@v-tilt/browser 1.0.1

package/lib/session.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = void 0;
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+class SessionManager {
+    constructor(storageMethod = "cookie", domain) {
+        this.storageMethod = storageMethod;
+        this.domain = domain;
+    }
+    /**
+     * Get session ID from cookie
+     */
+    getSessionIdFromCookie() {
+        const cookie = {};
+        document.cookie.split(";").forEach(function (el) {
+            const [key, value] = el.split("=");
+            cookie[key.trim()] = value;
+        });
+        return cookie[constants_1.STORAGE_KEY] || null;
+    }
+    /**
+     * Get session ID from storage
+     */
+    getSessionId() {
+        if (this.storageMethod === constants_1.STORAGE_METHODS.localStorage ||
+            this.storageMethod === constants_1.STORAGE_METHODS.sessionStorage) {
+            const storage = this.storageMethod === constants_1.STORAGE_METHODS.localStorage
+                ? localStorage
+                : sessionStorage;
+            const serializedItem = storage.getItem(constants_1.STORAGE_KEY);
+            if (!serializedItem) {
+                return null;
+            }
+            let item = null;
+            try {
+                item = JSON.parse(serializedItem);
+            }
+            catch (_a) {
+                return null;
+            }
+            if (typeof item !== "object" || item === null) {
+                return null;
+            }
+            const now = new Date();
+            if (now.getTime() > item.expiry) {
+                storage.removeItem(constants_1.STORAGE_KEY);
+                return null;
+            }
+            return item.value;
+        }
+        return this.getSessionIdFromCookie();
+    }
+    /**
+     * Set session ID in cookie
+     */
+    setSessionIdFromCookie(sessionId) {
+        let cookieValue = `${constants_1.STORAGE_KEY}=${sessionId}; Max-Age=1800; path=/; secure`;
+        if (this.domain) {
+            cookieValue += `; domain=${this.domain}`;
+        }
+        document.cookie = cookieValue;
+    }
+    /**
+     * Set session ID in storage
+     */
+    setSessionId() {
+        /**
+         * Try to keep same session id if it exists, generate a new one otherwise.
+         *   - First request in a session will generate a new session id
+         *   - The next request will keep the same session id and extend the TTL for 30 more minutes
+         */
+        const sessionId = this.getSessionId() || (0, utils_1.uuidv4)();
+        if (this.storageMethod === constants_1.STORAGE_METHODS.localStorage ||
+            this.storageMethod === constants_1.STORAGE_METHODS.sessionStorage) {
+            const now = new Date();
+            const item = {
+                value: sessionId,
+                expiry: now.getTime() + 1800 * 1000,
+            };
+            const value = JSON.stringify(item);
+            const storage = this.storageMethod === constants_1.STORAGE_METHODS.localStorage
+                ? localStorage
+                : sessionStorage;
+            storage.setItem(constants_1.STORAGE_KEY, value);
+        }
+        else {
+            this.setSessionIdFromCookie(sessionId);
+        }
+        return sessionId;
+    }
+    /**
+     * Reset session ID (PostHog behavior: generates new session on reset)
+     */
+    resetSessionId() {
+        // Clear existing session
+        if (this.storageMethod === constants_1.STORAGE_METHODS.localStorage ||
+            this.storageMethod === constants_1.STORAGE_METHODS.sessionStorage) {
+            const storage = this.storageMethod === constants_1.STORAGE_METHODS.localStorage
+                ? localStorage
+                : sessionStorage;
+            storage.removeItem(constants_1.STORAGE_KEY);
+        }
+        else {
+            // Clear cookie
+            document.cookie = `${constants_1.STORAGE_KEY}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;`;
+            if (this.domain) {
+                document.cookie = `${constants_1.STORAGE_KEY}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/; domain=${this.domain};`;
+            }
+        }
+        // Generate new session ID
+        this.setSessionId();
+    }
+}
+exports.SessionManager = SessionManager;

package/lib/tracking.d.ts

@@ -0,0 +1,112 @@
+import { VTiltConfig, EventPayload } from "./types";
+interface QueuedRequest {
+    url: string;
+    event: any;
+}
+export declare class TrackingManager {
+    private config;
+    private sessionManager;
+    private userManager;
+    __request_queue: QueuedRequest[];
+    private _hasWarnedAboutConfig;
+    constructor(config: VTiltConfig);
+    /**
+     * Get current domain from window location
+     * Returns full URL format for consistency with dashboard
+     */
+    private getCurrentDomain;
+    /**
+     * Check if tracking is properly configured
+     * Returns true if projectId and token are present, false otherwise
+     * Logs a warning only once per instance if not configured
+     */
+    private _isConfigured;
+    /**
+     * Send event to endpoint
+     */
+    sendEvent(name: string, payload: EventPayload): Promise<void>;
+    /**
+     * Build the tracking URL with token in query parameters (PostHog style)
+     */
+    private buildUrl;
+    /**
+     * Send HTTP request
+     * This is the central entry point for all tracking requests
+     */
+    private sendRequest;
+    /**
+     * Send a queued request (called after DOM is loaded)
+     */
+    _send_retriable_request(item: QueuedRequest): void;
+    /**
+     * Track page hit
+     */
+    trackPageHit(): void;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Identify a user with PostHog-style property operations
+     * Copied from PostHog's identify method signature
+     */
+    identify(distinctId?: string, userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
+    /**
+     * Set user properties (PostHog-style)
+     */
+    setUserProperties(userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
+    /**
+     * Reset user identity (logout)
+     * PostHog behavior: Clears all user data, generates new anonymous ID, resets session
+     *
+     * @param reset_device_id - If true, also resets device_id. Default: false
+     */
+    resetUser(reset_device_id?: boolean): void;
+    /**
+     * Get current user identity
+     */
+    getUserIdentity(): import("./types").UserIdentity;
+    /**
+     * Get current device ID
+     */
+    getDeviceId(): string;
+    /**
+     * Get current user state
+     */
+    getUserState(): "anonymous" | "identified";
+    /**
+     * Create an alias to link two distinct IDs
+     * PostHog behavior: Links anonymous session to account on signup
+     *
+     * @param alias - A unique identifier that you want to use for this user in the future
+     * @param original - The current identifier being used for this user (optional, defaults to current distinct_id)
+     *
+     * @example
+     * // Link anonymous user to account on signup
+     * vtilt.createAlias('user_12345')
+     *
+     * @example
+     * // Explicit alias with original ID
+     * vtilt.createAlias('user_12345', 'anonymous_abc123')
+     */
+    createAlias(alias: string, original?: string): void;
+    /**
+     * Setup listener for identify, set, and alias events
+     */
+    private setupIdentifyListener;
+    /**
+     * Send identify event for session merging
+     */
+    private sendIdentifyEvent;
+    /**
+     * Send $set event for property updates (PostHog behavior)
+     * This notifies Tinybird when user properties are updated
+     */
+    private sendSetEvent;
+    /**
+     * Send alias event for identity linking
+     * PostHog format: { alias: alias, distinct_id: original }
+     */
+    private sendAliasEvent;
+}
+export {};

package/lib/tracking.js

@@ -0,0 +1,326 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrackingManager = void 0;
+const session_1 = require("./session");
+const user_manager_1 = require("./user-manager");
+const utils_1 = require("./utils");
+const geolocation_1 = require("./geolocation");
+class TrackingManager {
+    constructor(config) {
+        this.__request_queue = [];
+        this._hasWarnedAboutConfig = false; // Track if we've already warned about missing config
+        this.config = config;
+        // Auto-detect domain from window.location if not provided
+        if (!this.config.domain && typeof window !== "undefined") {
+            this.config.domain = this.getCurrentDomain();
+        }
+        this.sessionManager = new session_1.SessionManager(config.storage || "cookie", this.config.domain);
+        this.userManager = new user_manager_1.UserManager(config.persistence || "localStorage", this.config.domain);
+        // Listen for identify events
+        this.setupIdentifyListener();
+    }
+    /**
+     * Get current domain from window location
+     * Returns full URL format for consistency with dashboard
+     */
+    getCurrentDomain() {
+        if (typeof window === "undefined") {
+            return "";
+        }
+        const protocol = window.location.protocol;
+        const hostname = window.location.hostname;
+        const port = window.location.port;
+        const portSuffix = port ? `:${port}` : "";
+        return `${protocol}//${hostname}${portSuffix}`;
+    }
+    /**
+     * Check if tracking is properly configured
+     * Returns true if projectId and token are present, false otherwise
+     * Logs a warning only once per instance if not configured
+     */
+    _isConfigured() {
+        if (this.config.projectId && this.config.token) {
+            return true;
+        }
+        // Only warn once to avoid console spam
+        if (!this._hasWarnedAboutConfig) {
+            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;
+        }
+        return false;
+    }
+    /**
+     * Send event to endpoint
+     */
+    async sendEvent(name, payload) {
+        this.sessionManager.setSessionId();
+        if (!(0, utils_1.isValidUserAgent)(window.navigator.userAgent)) {
+            return;
+        }
+        const url = this.buildUrl();
+        let processedPayload;
+        if (this.config.stringifyPayload !== false) {
+            processedPayload = (0, utils_1.maskSuspiciousAttributes)(payload);
+            processedPayload = Object.assign({}, JSON.parse(processedPayload), this.config.globalAttributes);
+            processedPayload = JSON.stringify(processedPayload);
+            if (!(0, utils_1.isValidPayload)(processedPayload)) {
+                return;
+            }
+        }
+        else {
+            processedPayload = Object.assign({}, payload, this.config.globalAttributes);
+            const maskedStr = (0, utils_1.maskSuspiciousAttributes)(processedPayload);
+            if (!(0, utils_1.isValidPayload)(maskedStr)) {
+                return;
+            }
+            processedPayload = JSON.parse(maskedStr);
+        }
+        const session_id = this.sessionManager.getSessionId() || (0, utils_1.uuidv4)();
+        const distinct_id = this.userManager.getDistinctId();
+        const anonymous_id = this.userManager.getAnonymousId();
+        const trackingEvent = {
+            timestamp: new Date().toISOString(),
+            event: name,
+            session_id,
+            tenant_id: this.config.projectId || "",
+            domain: this.config.domain || this.getCurrentDomain(), // Use config domain or current domain
+            payload: processedPayload,
+            distinct_id: distinct_id || anonymous_id,
+        };
+        this.sendRequest(url, trackingEvent, true);
+    }
+    /**
+     * Build the tracking URL with token in query parameters (PostHog style)
+     */
+    buildUrl() {
+        const { proxyUrl, proxy, host, token } = this.config;
+        // Use proxy endpoint to handle Tinybird authentication
+        if (proxyUrl) {
+            // Use the full proxy URL as provided
+            return proxyUrl;
+        }
+        else if (proxy) {
+            // Construct the proxy URL from the proxy domain with token
+            return `${proxy}/api/tracking?token=${token}`;
+        }
+        else if (host) {
+            const cleanHost = host.replace(/\/+$/gm, "");
+            return `${cleanHost}/api/tracking?token=${token}`;
+        }
+        else {
+            // Use relative path to our tracking proxy endpoint
+            return `/api/tracking?token=${token}`;
+        }
+    }
+    /**
+     * Send HTTP request
+     * This is the central entry point for all tracking requests
+     */
+    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()) {
+            return;
+        }
+        // Check if we should queue requests (for older browsers before DOM is loaded)
+        if (shouldEnqueue && typeof window !== "undefined") {
+            // ENQUEUE_REQUESTS is defined in vtilt.ts as a module-level variable
+            const ENQUEUE_REQUESTS = window.__VTILT_ENQUEUE_REQUESTS;
+            if (ENQUEUE_REQUESTS) {
+                this.__request_queue.push({ url, event });
+                return;
+            }
+        }
+        const request = new XMLHttpRequest();
+        request.open("POST", url, true);
+        request.setRequestHeader("Content-Type", "application/json");
+        request.send(JSON.stringify(event));
+    }
+    /**
+     * Send a queued request (called after DOM is loaded)
+     */
+    _send_retriable_request(item) {
+        this.sendRequest(item.url, item.event, false);
+    }
+    /**
+     * Track page hit
+     */
+    trackPageHit() {
+        // If test environment
+        if ((0, utils_1.isTestEnvironment)()) {
+            return;
+        }
+        const { country, locale } = (0, geolocation_1.getCountryAndLocale)();
+        // Wait a bit for SPA routers
+        setTimeout(() => {
+            this.sendEvent("page_hit", {
+                "user-agent": window.navigator.userAgent,
+                locale,
+                location: country,
+                referrer: document.referrer,
+                pathname: window.location.pathname,
+                href: window.location.href,
+            });
+        }, 300);
+    }
+    /**
+     * Get current session ID
+     */
+    getSessionId() {
+        return this.sessionManager.getSessionId();
+    }
+    /**
+     * Identify a user with PostHog-style property operations
+     * Copied from PostHog's identify method signature
+     */
+    identify(distinctId, userPropertiesToSet, userPropertiesToSetOnce) {
+        this.userManager.identify(distinctId, userPropertiesToSet, userPropertiesToSetOnce);
+    }
+    /**
+     * Set user properties (PostHog-style)
+     */
+    setUserProperties(userPropertiesToSet, userPropertiesToSetOnce) {
+        this.userManager.setUserProperties(userPropertiesToSet, userPropertiesToSetOnce);
+    }
+    /**
+     * Reset user identity (logout)
+     * PostHog behavior: Clears all user data, generates new anonymous ID, resets session
+     *
+     * @param reset_device_id - If true, also resets device_id. Default: false
+     */
+    resetUser(reset_device_id) {
+        // PostHog behavior: Reset session ID
+        this.sessionManager.resetSessionId();
+        this.userManager.reset(reset_device_id);
+    }
+    /**
+     * Get current user identity
+     */
+    getUserIdentity() {
+        return this.userManager.getUserIdentity();
+    }
+    /**
+     * Get current device ID
+     */
+    getDeviceId() {
+        return this.userManager.getDeviceId();
+    }
+    /**
+     * Get current user state
+     */
+    getUserState() {
+        return this.userManager.getUserState();
+    }
+    /**
+     * Create an alias to link two distinct IDs
+     * PostHog behavior: Links anonymous session to account on signup
+     *
+     * @param alias - A unique identifier that you want to use for this user in the future
+     * @param original - The current identifier being used for this user (optional, defaults to current distinct_id)
+     *
+     * @example
+     * // Link anonymous user to account on signup
+     * vtilt.createAlias('user_12345')
+     *
+     * @example
+     * // Explicit alias with original ID
+     * vtilt.createAlias('user_12345', 'anonymous_abc123')
+     */
+    createAlias(alias, original) {
+        this.userManager.createAlias(alias, original);
+    }
+    /**
+     * Setup listener for identify, set, and alias events
+     */
+    setupIdentifyListener() {
+        // Listen for identify events
+        window.addEventListener("vtilt:identify", (event) => {
+            const customEvent = event;
+            const { distinct_id, anonymous_id, device_id, properties } = customEvent.detail;
+            this.sendIdentifyEvent(distinct_id, anonymous_id, device_id, properties);
+        });
+        // Listen for set events (property updates)
+        window.addEventListener("vtilt:set", (event) => {
+            const customEvent = event;
+            const { $set, $set_once } = customEvent.detail;
+            this.sendSetEvent($set || {}, $set_once || {});
+        });
+        // Listen for alias events
+        window.addEventListener("vtilt:alias", (event) => {
+            const customEvent = event;
+            const aliasEvent = customEvent.detail;
+            this.sendAliasEvent(aliasEvent);
+        });
+    }
+    /**
+     * Send identify event for session merging
+     */
+    sendIdentifyEvent(distinctId, anonymousId, deviceId, properties) {
+        const url = this.buildUrl();
+        const session_id = this.sessionManager.getSessionId() || (0, utils_1.uuidv4)();
+        // Payload contains only properties, not event or distinct_id (those are in trackingEvent)
+        const identifyPayload = {
+            $anon_distinct_id: anonymousId,
+            $device_id: deviceId,
+            ...properties,
+        };
+        const trackingEvent = {
+            timestamp: new Date().toISOString(),
+            event: "$identify",
+            session_id,
+            tenant_id: this.config.projectId || "",
+            domain: this.config.domain || this.getCurrentDomain(),
+            payload: identifyPayload,
+            distinct_id: distinctId,
+        };
+        this.sendRequest(url, trackingEvent, true);
+    }
+    /**
+     * Send $set event for property updates (PostHog behavior)
+     * This notifies Tinybird when user properties are updated
+     */
+    sendSetEvent(userPropertiesToSet, userPropertiesToSetOnce) {
+        const url = this.buildUrl();
+        const session_id = this.sessionManager.getSessionId() || (0, utils_1.uuidv4)();
+        const distinct_id = this.userManager.getDistinctId();
+        const anonymous_id = this.userManager.getAnonymousId();
+        const setEventPayload = {
+            $set: userPropertiesToSet || {},
+            $set_once: userPropertiesToSetOnce || {},
+        };
+        const trackingEvent = {
+            timestamp: new Date().toISOString(),
+            event: "$set",
+            session_id,
+            tenant_id: this.config.projectId || "",
+            domain: this.config.domain || this.getCurrentDomain(),
+            payload: setEventPayload,
+            distinct_id: distinct_id || anonymous_id,
+        };
+        this.sendRequest(url, trackingEvent, true);
+    }
+    /**
+     * Send alias event for identity linking
+     * PostHog format: { alias: alias, distinct_id: original }
+     */
+    sendAliasEvent(aliasEvent) {
+        const url = this.buildUrl();
+        const session_id = this.sessionManager.getSessionId() || (0, utils_1.uuidv4)();
+        const aliasPayload = {
+            $original_id: aliasEvent.original,
+            $alias_id: aliasEvent.distinct_id,
+        };
+        const trackingEvent = {
+            timestamp: new Date().toISOString(),
+            event: "$alias",
+            session_id,
+            tenant_id: this.config.projectId || "",
+            domain: this.config.domain || this.getCurrentDomain(),
+            payload: aliasPayload,
+            distinct_id: aliasEvent.distinct_id,
+        };
+        this.sendRequest(url, trackingEvent, true);
+    }
+}
+exports.TrackingManager = TrackingManager;

package/lib/types.d.ts

@@ -0,0 +1,67 @@
+export interface VTiltConfig {
+    projectId: string;
+    token: string;
+    host?: string;
+    scriptHost?: string;
+    proxy?: string;
+    proxyUrl?: string;
+    domain?: string;
+    storage?: "cookie" | "localStorage" | "sessionStorage";
+    stringifyPayload?: boolean;
+    webVitals?: boolean;
+    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;
+}
+export interface EventPayload {
+    [key: string]: any;
+}
+export interface TrackingEvent {
+    timestamp: string;
+    event: string;
+    session_id: string;
+    tenant_id: string;
+    domain: string;
+    payload: EventPayload;
+    distinct_id?: string;
+}
+export type StorageMethod = "cookie" | "localStorage" | "sessionStorage";
+export interface StorageMethods {
+    cookie: "cookie";
+    localStorage: "localStorage";
+    sessionStorage: "sessionStorage";
+}
+export interface UserIdentity {
+    distinct_id: string | null;
+    anonymous_id: string;
+    device_id: string;
+    properties: Record<string, any>;
+    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;
+}

package/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });