@v-tilt/browser 1.1.0 → 1.1.1

package/dist/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/dist/types.d.ts

@@ -1,69 +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;
-    disable_compression?: 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 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 type StorageMethod = "cookie" | "localStorage" | "sessionStorage";
-export interface StorageMethods {
-    cookie: "cookie";
-    localStorage: "localStorage";
-    sessionStorage: "sessionStorage";
+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/dist/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/dist/vtilt.d.ts

@@ -11,11 +11,11 @@ export declare class VTilt {
     private rateLimiter;
     historyAutocapture?: HistoryAutocapture;
     __loaded: boolean;
-    private _initialPageviewCaptured;
-    private _visibilityStateListener;
+    private _initial_pageview_captured;
+    private _visibility_state_listener;
     __request_queue: QueuedRequest[];
-    private _hasWarnedAboutConfig;
-    private _setOncePropertiesSent;
+    private _has_warned_about_config;
+    private _set_once_properties_sent;
     constructor(config?: Partial<VTiltConfig>);
     /**
      * Initializes a new instance of the VTilt tracking object.
@@ -53,11 +53,17 @@ export declare class VTilt {
      * This internal method should only be called by `init()`.
      */
     private _init;
+    /**
+     * Start the request queue if user hasn't opted out
+     * Following PostHog's pattern - called from both _init() and _dom_loaded()
+     * Safe to call multiple times as enable() is idempotent
+     */
+    private _start_queue_if_opted_in;
     /**
      * Set up handler to flush event queue on page unload
      * Uses both beforeunload and pagehide for maximum compatibility
      */
-    private _setupUnloadHandler;
+    private _setup_unload_handler;
     /**
      * Returns a string representation of the instance name
      * Used for debugging and logging
@@ -75,7 +81,7 @@ export declare class VTilt {
      * Returns true if projectId and token are present, false otherwise
      * Logs a warning only once per instance if not configured
      */
-    private _isConfigured;
+    private _is_configured;
     /**
      * Build the tracking URL with token in query parameters
      */
@@ -91,18 +97,18 @@ export declare class VTilt {
      * Called by RequestQueue when flushing
      * Uses RetryQueue for automatic retry on failure
      */
-    private _sendBatchedRequest;
+    private _send_batched_request;
     /**
      * Send HTTP request and return status code
      * Uses GZip compression for payloads > 1KB
      * Used by RetryQueue for retryable requests
      */
-    private _sendHttpRequest;
+    private _send_http_request;
     /**
      * Send request using sendBeacon for reliable delivery on page unload
      * Uses GZip compression for payloads > 1KB
      */
-    private _sendBeaconRequest;
+    private _send_beacon_request;
     /**
      * Send a queued request (called after DOM is loaded)
      */
@@ -125,7 +131,7 @@ export declare class VTilt {
      * Internal capture method that bypasses rate limiting
      * Used for system events like rate limit warnings
      */
-    private _captureInternal;
+    private _capture_internal;
     /**
      * Track a custom event (alias for capture)
      */
@@ -219,8 +225,9 @@ export declare class VTilt {
     createAlias(alias: string, original?: string): void;
     /**
      * Capture initial pageview with visibility check
+     * Note: The capture_pageview config check happens at the call site (in _init)
      */
-    private _captureInitialPageview;
+    private _capture_initial_pageview;
     /**
      * Get current configuration
      */
@@ -247,6 +254,7 @@ export declare class VTilt {
     _execute_array(array: any[]): void;
     /**
      * Called when DOM is loaded - processes queued requests and enables batching
+     * Following PostHog's pattern in _dom_loaded()
      */
     _dom_loaded(): void;
 }

package/lib/config.js

@@ -11,19 +11,17 @@ class ConfigManager {
     parseConfigFromScript(initialConfig) {
         if (!document.currentScript) {
             return {
-                projectId: initialConfig.projectId || "",
                 token: initialConfig.token || "",
                 ...initialConfig,
             };
         }
         const script = document.currentScript;
         const config = {
-            projectId: "", // Required field with default
             token: "", // Required field with default
             ...initialConfig,
         };
         // Parse basic attributes
-        config.host = script.getAttribute("data-host") || initialConfig.host;
+        config.api_host = script.getAttribute("data-api-host") || script.getAttribute("data-host") || initialConfig.api_host;
         config.proxy = script.getAttribute("data-proxy") || initialConfig.proxy;
         config.proxyUrl =
             script.getAttribute("data-proxy-url") || initialConfig.proxyUrl;
@@ -36,24 +34,19 @@ class ConfigManager {
             script.getAttribute("data-storage") || initialConfig.storage;
         config.stringifyPayload =
             script.getAttribute("data-stringify-payload") !== "false";
-        config.webVitals =
-            script.getAttribute("web-vitals") === "true" ||
-                script.getAttribute("data-web-vitals") === "true" ||
-                initialConfig.webVitals;
+        config.capture_performance =
+            script.getAttribute("data-capture-performance") === "true" ||
+                initialConfig.capture_performance;
         // Check for conflicting proxy configurations
         if (config.proxy && config.proxyUrl) {
             console.error("Error: Both data-proxy and data-proxy-url are specified. Please use only one of them.");
             throw new Error("Both data-proxy and data-proxy-url are specified. Please use only one of them.");
         }
-        // Parse global attributes
+        // Parse global attributes (data-vt-* attributes)
         config.globalAttributes = { ...initialConfig.globalAttributes };
         // NamedNodeMap is not iterable, so use Array.from to iterate over attributes
         for (const attr of Array.from(script.attributes)) {
-            if (attr.name.startsWith("tb_")) {
-                config.globalAttributes[attr.name.slice(3).replace(/-/g, "_")] =
-                    attr.value;
-            }
-            if (attr.name.startsWith("data-tb-")) {
+            if (attr.name.startsWith("data-vt-")) {
                 config.globalAttributes[attr.name.slice(8).replace(/-/g, "_")] =
                     attr.value;
             }

package/lib/constants.d.ts

@@ -1,12 +1,174 @@
-import { StorageMethods } from "./types";
-export declare const STORAGE_KEY = "vt_session_id";
-export declare const WINDOW_ID_KEY = "vt_window_id";
-export declare const PRIMARY_WINDOW_EXISTS_KEY = "vt_primary_window_exists";
-export declare const ANONYMOUS_ID_KEY = "vt_anonymous_id";
-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";
+/**
+ * Constants
+ *
+ * Following PostHog's pattern for constant definitions.
+ * These are used throughout the SDK for:
+ * - Storage keys
+ * - Property names
+ * - Event names
+ * - Configuration defaults
+ */
+/** @deprecated Use DISTINCT_ID instead */
+export declare const PEOPLE_DISTINCT_ID_KEY = "$people_distinct_id";
+/** Current distinct_id */
+export declare const DISTINCT_ID = "distinct_id";
+/** Alias ID for aliasing operations */
+export declare const ALIAS_ID_KEY = "__alias";
+/** Event timers storage key */
+export declare const EVENT_TIMERS_KEY = "__timers";
+/** Session ID storage key */
+export declare const SESSION_ID = "$sesid";
+/** Session storage key (for session manager) */
+export declare const STORAGE_KEY = "__vt_session";
+/** Window ID storage key */
+export declare const WINDOW_ID = "$windowid";
+/** Window ID key (for session storage) */
+export declare const WINDOW_ID_KEY = "__vt_window_id";
+/** Primary window exists key (for tab duplication detection) */
+export declare const PRIMARY_WINDOW_EXISTS_KEY = "__vt_primary_window";
+/** User state (anonymous/identified) */
+export declare const USER_STATE = "$user_state";
+/** User state storage key */
+export declare const USER_STATE_KEY = "__vt_user_state";
+/** Device ID storage key */
+export declare const DEVICE_ID = "$device_id";
+/** Device ID key (for storage) */
+export declare const DEVICE_ID_KEY = "__vt_device_id";
+/** Anonymous ID storage key */
+export declare const ANONYMOUS_ID = "$anonymous_id";
+/** Anonymous ID key (for storage) */
+export declare const ANONYMOUS_ID_KEY = "__vt_anonymous_id";
+/** Distinct ID key (for storage) */
+export declare const DISTINCT_ID_KEY = "__vt_distinct_id";
+/** User properties storage key */
+export declare const USER_PROPERTIES_KEY = "__vt_user_properties";
+/**
+ * Persistence methods object
+ * Following PostHog's approach for storage/persistence configuration
+ */
+export declare const PERSISTENCE_METHODS: {
+    cookie: "cookie";
+    localStorage: "localStorage";
+    localStoragePlusCookie: "localStorage+cookie";
+    sessionStorage: "sessionStorage";
+    memory: "memory";
+};
+/** @deprecated Use PERSISTENCE_METHODS instead */
+export declare const STORAGE_METHODS: {
+    cookie: "cookie";
+    localStorage: "localStorage";
+    localStoragePlusCookie: "localStorage+cookie";
+    sessionStorage: "sessionStorage";
+    memory: "memory";
+};
+/** Enable person processing flag */
+export declare const ENABLE_PERSON_PROCESSING = "$epp";
+/** Initial person info (referrer, URL, UTM params) */
 export declare const INITIAL_PERSON_INFO = "$initial_person_info";
-export declare const STORAGE_METHODS: StorageMethods;
+/** @deprecated Use INITIAL_PERSON_INFO */
+export declare const INITIAL_CAMPAIGN_PARAMS = "$initial_campaign_params";
+/** @deprecated Use INITIAL_PERSON_INFO */
+export declare const INITIAL_REFERRER_INFO = "$initial_referrer_info";
+/** Stored person properties for feature flags */
+export declare const STORED_PERSON_PROPERTIES_KEY = "$stored_person_properties";
+/** Stored group properties for feature flags */
+export declare const STORED_GROUP_PROPERTIES_KEY = "$stored_group_properties";
+export declare const AUTOCAPTURE_DISABLED_SERVER_SIDE = "$autocapture_disabled_server_side";
+export declare const WEB_VITALS_ENABLED_SERVER_SIDE = "$web_vitals_enabled_server_side";
+export declare const SESSION_RECORDING_ENABLED_SERVER_SIDE = "$session_recording_enabled_server_side";
+/** Pageview event */
+export declare const EVENT_PAGEVIEW = "$pageview";
+/** Pageleave event */
+export declare const EVENT_PAGELEAVE = "$pageleave";
+/** Identify event */
+export declare const EVENT_IDENTIFY = "$identify";
+/** Alias event */
+export declare const EVENT_ALIAS = "$create_alias";
+/** Set person properties event */
+export declare const EVENT_SET = "$set";
+/** Group identify event */
+export declare const EVENT_GROUP_IDENTIFY = "$groupidentify";
+/** Performance event */
+export declare const EVENT_PERFORMANCE = "$performance_event";
+/** Snapshot event (session recording) */
+export declare const EVENT_SNAPSHOT = "$snapshot";
+/** Rate limit warning event */
+export declare const EVENT_RATE_LIMIT_WARNING = "$$client_ingestion_warning";
+/** Process person profile flag */
+export declare const PROP_PROCESS_PERSON_PROFILE = "$process_person_profile";
+/** Is identified flag */
+export declare const PROP_IS_IDENTIFIED = "$is_identified";
+/** Anonymous distinct ID */
+export declare const PROP_ANON_DISTINCT_ID = "$anon_distinct_id";
+/** Session ID property */
+export declare const PROP_SESSION_ID = "$session_id";
+/** Window ID property */
+export declare const PROP_WINDOW_ID = "$window_id";
+/** Current URL */
+export declare const PROP_CURRENT_URL = "$current_url";
+/** Hostname */
+export declare const PROP_HOST = "$host";
+/** Pathname */
+export declare const PROP_PATHNAME = "$pathname";
+/** Referrer URL */
+export declare const PROP_REFERRER = "$referrer";
+/** Referring domain */
+export declare const PROP_REFERRING_DOMAIN = "$referring_domain";
+/** Browser */
+export declare const PROP_BROWSER = "$browser";
+/** Browser version */
+export declare const PROP_BROWSER_VERSION = "$browser_version";
+/** Operating system */
+export declare const PROP_OS = "$os";
+/** OS version */
+export declare const PROP_OS_VERSION = "$os_version";
+/** Device type */
+export declare const PROP_DEVICE_TYPE = "$device_type";
+/** Screen height */
+export declare const PROP_SCREEN_HEIGHT = "$screen_height";
+/** Screen width */
+export declare const PROP_SCREEN_WIDTH = "$screen_width";
+/** Viewport height */
+export declare const PROP_VIEWPORT_HEIGHT = "$viewport_height";
+/** Viewport width */
+export declare const PROP_VIEWPORT_WIDTH = "$viewport_width";
+/** Library name */
+export declare const PROP_LIB = "$lib";
+/** Library version */
+export declare const PROP_LIB_VERSION = "$lib_version";
+export declare const PROP_GEOIP_COUNTRY_CODE = "$geoip_country_code";
+export declare const PROP_GEOIP_COUNTRY_NAME = "$geoip_country_name";
+export declare const PROP_GEOIP_CITY_NAME = "$geoip_city_name";
+export declare const PROP_GEOIP_REGION_NAME = "$geoip_region_name";
+export declare const PROP_GEOIP_CONTINENT_CODE = "$geoip_continent_code";
+export declare const PROP_GEOIP_TIMEZONE = "$geoip_timezone";
+export declare const PROP_GEOIP_LATITUDE = "$geoip_latitude";
+export declare const PROP_GEOIP_LONGITUDE = "$geoip_longitude";
+/** Initial GeoIP properties (set once) */
+export declare const PROP_INITIAL_GEOIP_PREFIX = "$initial_geoip_";
+export declare const UTM_PARAMS: readonly ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "gclid", "gad_source", "gbraid", "wbraid", "fbclid", "msclkid", "twclid", "li_fat_id", "mc_cid", "igshid", "ttclid"];
+export type UTMParam = typeof UTM_PARAMS[number];
+export declare const PERSISTENCE_RESERVED_PROPERTIES: string[];
+/**
+ * Person profiles configuration mode
+ * - 'always': Always create person profiles (default)
+ * - 'identified_only': Only create profiles when user is identified
+ * - 'never': Never create person profiles (events only)
+ */
+export type PersonProfilesMode = 'always' | 'identified_only' | 'never';
+/** Default API host */
+export declare const DEFAULT_API_HOST = "https://api.vtilt.io";
+/** Default flush interval (ms) */
+export declare const DEFAULT_FLUSH_INTERVAL_MS = 5000;
+/** Default batch size */
+export declare const DEFAULT_BATCH_SIZE = 10;
+/** Session timeout (30 minutes in ms) */
+export declare const SESSION_TIMEOUT_MS: number;
+/** Session ID change threshold (ms) */
+export declare const SESSION_CHANGE_THRESHOLD_MS: number;
+/** Maximum event properties size (bytes) */
+export declare const MAX_PROPERTIES_SIZE = 65535;
+/** Maximum property value length */
+export declare const MAX_PROPERTY_VALUE_LENGTH = 8192;
+/** Timezone to country code mapping */
 export declare const TIMEZONES: Record<string, string>;