@v-tilt/browser 1.1.0 → 1.1.2

package/dist/module.d.ts

@@ -1,72 +1,196 @@
+/**
+ * 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)
+ */
+type PersonProfilesMode = "always" | "identified_only" | "never";
+
+/**
+ * VTilt Types
+ *
+ * Type definitions for the VTilt tracking SDK.
+ * Following PostHog's patterns where applicable.
+ */
+
 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;
-}
-interface SessionData {
-    value: string;
-    expiry: number;
-}
-interface WebVitalMetric {
-    name: string;
-    value: number;
-    delta: number;
-    rating: string;
-    id: string;
-    navigationType: string;
-}
-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;
 }
 interface EventPayload {
     [key: string]: any;
 }
+interface CaptureResult {
+    uuid: string;
+    event: string;
+    properties: Properties;
+    $set?: Properties;
+    $set_once?: Properties;
+    timestamp?: string;
+}
+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;
+}
 interface TrackingEvent {
     timestamp: string;
     event: string;
     project_id: string;
     domain: string;
-    payload: EventPayload;
-    distinct_id?: string;
+    distinct_id: string;
     anonymous_id?: string;
+    payload: EventPayload;
+}
+type Property = string | number | boolean | null | undefined | Date | any[] | Record<string, any>;
+interface Properties {
+    [key: string]: Property;
 }
-type StorageMethod = "cookie" | "localStorage" | "sessionStorage";
-interface StorageMethods {
-    cookie: "cookie";
-    localStorage: "localStorage";
-    sessionStorage: "sessionStorage";
+interface PropertyOperations {
+    $set?: Properties;
+    $set_once?: Properties;
+    $unset?: string[];
 }
+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)
+ */
+type PersistenceMethod = "localStorage+cookie" | "cookie" | "localStorage" | "sessionStorage" | "memory";
+/** User identity state */
 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 properties */
+    properties: Properties;
+    /** Identity state */
     user_state: "anonymous" | "identified";
 }
 interface UserProperties {
     [key: string]: any;
 }
-interface PropertyOperations {
-    $set?: Record<string, any>;
-    $set_once?: Record<string, any>;
-}
 interface AliasEvent {
     distinct_id: string;
     original: string;
 }
+interface WebVitalMetric {
+    name: string;
+    value: number;
+    delta: number;
+    rating: "good" | "needs-improvement" | "poor";
+    id: string;
+    navigationType: string;
+}
+interface GeolocationData {
+    country?: string;
+    locale?: string;
+}
+interface GroupsConfig {
+    [groupType: string]: string;
+}
+interface FeatureFlagsConfig {
+    [flagKey: string]: boolean | string;
+}
+type SessionIdChangedCallback = (newSessionId: string, previousSessionId: string | null, changeInfo: {
+    reason: "timeout" | "new_session" | "reset";
+}) => void;
+interface RequestOptions {
+    method?: "POST" | "GET";
+    headers?: Record<string, string>;
+    timeout?: number;
+    retry?: boolean;
+}
+interface RemoteConfig {
+    /** Default to identified_only mode */
+    defaultIdentifiedOnly?: boolean;
+    /** Feature flags */
+    featureFlags?: FeatureFlagsConfig;
+    /** Session recording config */
+    sessionRecording?: {
+        enabled?: boolean;
+        sampleRate?: number;
+    };
+}
 
 /**
  * This class is used to capture pageview events when the user navigates using the history API (pushState, replaceState)
@@ -115,11 +239,11 @@ 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.
@@ -157,11 +281,17 @@ 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
@@ -179,7 +309,7 @@ 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
      */
@@ -195,18 +325,18 @@ 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)
      */
@@ -229,7 +359,7 @@ 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)
      */
@@ -323,8 +453,9 @@ 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
      */
@@ -351,6 +482,7 @@ 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;
 }
@@ -358,4 +490,4 @@ declare class VTilt {
 declare const vt: VTilt;
 
 export { VTilt, vt as default, vt };
-export type { AliasEvent, EventPayload, GeolocationData, PropertyOperations, SessionData, StorageMethod, StorageMethods, TrackingEvent, UserIdentity, UserProperties, VTiltConfig, WebVitalMetric };
+export type { AliasEvent, CaptureOptions, CaptureResult, EventPayload, FeatureFlagsConfig, GeolocationData, GroupsConfig, PersistenceMethod, Properties, Property, PropertyOperations, RemoteConfig, RequestOptions, SessionData, SessionIdChangedCallback, TrackingEvent, UserIdentity, UserProperties, VTiltConfig, WebVitalMetric };