@v-tilt/browser 1.5.1 → 1.7.0

package/lib/types.d.ts

@@ -1,326 +0,0 @@
-/**
- * VTilt Types
- *
- * Type definitions for the VTilt tracking SDK.
- * Following PostHog's patterns where applicable.
- */
-import type { PersonProfilesMode } from "./constants";
-export interface VTiltConfig {
-    /** Project identifier (required) */
-    token: string;
-    /** API host for tracking (default: https://api.vtilt.io) */
-    api_host?: string;
-    /** UI host for dashboard links */
-    ui_host?: string | null;
-    /**
-     * Host for loading extension scripts (recorder.js, etc.)
-     * Defaults to unpkg CDN: https://unpkg.com/@v-tilt/browser@{version}/dist
-     * Can also use jsdelivr: https://cdn.jsdelivr.net/npm/@v-tilt/browser@{version}/dist
-     * Or self-hosted: https://your-domain.com/static
-     */
-    script_host?: string;
-    /** 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) - used in event properties */
-    domain?: string;
-    /** Storage method for session data */
-    storage?: PersistenceMethod;
-    /** Persistence method for user data */
-    persistence?: PersistenceMethod;
-    /** Persistence name prefix */
-    persistence_name?: string;
-    /**
-     * Enable cross-subdomain cookies.
-     * When true, cookies are shared across subdomains (e.g., app.example.com and www.example.com).
-     * Auto-detects false for platforms like herokuapp.com, vercel.app, netlify.app.
-     * @default true (except for excluded platforms)
-     */
-    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.
-     * Can be a boolean or an object with detailed configuration.
-     */
-    capture_performance?: boolean | CapturePerformanceConfig;
-    /** 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;
-    /** 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;
-    /** Session recording configuration */
-    session_recording?: SessionRecordingOptions;
-    /** Disable session recording (convenience flag) */
-    disable_session_recording?: boolean;
-    /** Chat widget configuration */
-    chat?: ChatWidgetConfig;
-    /** Disable chat (convenience flag) */
-    disable_chat?: boolean;
-    /** Global attributes added to all events */
-    globalAttributes?: Record<string, 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;
-    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 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;
-    /** User properties */
-    properties: Properties;
-    /** Identity state */
-    user_state: "anonymous" | "identified";
-}
-export interface UserProperties {
-    [key: string]: any;
-}
-export interface AliasEvent {
-    distinct_id: string;
-    original: string;
-}
-/** Supported Web Vitals metrics */
-export type SupportedWebVitalsMetric = "LCP" | "CLS" | "FCP" | "INP" | "TTFB";
-/** All supported Web Vitals metrics */
-export declare const ALL_WEB_VITALS_METRICS: SupportedWebVitalsMetric[];
-/** Default Web Vitals metrics (matches PostHog defaults) */
-export declare const DEFAULT_WEB_VITALS_METRICS: SupportedWebVitalsMetric[];
-/**
- * Web Vitals capture configuration
- */
-export interface CapturePerformanceConfig {
-    /** Enable or disable web vitals capture */
-    web_vitals?: boolean;
-    /** Which metrics to capture (default: LCP, CLS, FCP, INP) */
-    web_vitals_allowed_metrics?: SupportedWebVitalsMetric[];
-    /** Delay before flushing metrics in ms (default: 5000) */
-    web_vitals_delayed_flush_ms?: number;
-    /**
-     * Maximum allowed metric value in ms (default: 900000 = 15 minutes)
-     * Values above this are considered anomalies and ignored.
-     * Set to 0 to disable this check.
-     */
-    __web_vitals_max_value?: number;
-}
-export interface WebVitalMetric {
-    name: string;
-    value: number;
-    delta: number;
-    rating: "good" | "needs-improvement" | "poor";
-    id: string;
-    navigationType: string;
-    /** Timestamp when the metric was captured (added internally) */
-    timestamp?: number;
-    /** Attribution data from web-vitals library */
-    attribution?: Record<string, unknown>;
-}
-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;
-}
-/** Mask options for input elements in session recording */
-export interface SessionRecordingMaskInputOptions {
-    color?: boolean;
-    date?: boolean;
-    "datetime-local"?: boolean;
-    email?: boolean;
-    month?: boolean;
-    number?: boolean;
-    range?: boolean;
-    search?: boolean;
-    tel?: boolean;
-    text?: boolean;
-    time?: boolean;
-    url?: boolean;
-    week?: boolean;
-    textarea?: boolean;
-    select?: boolean;
-    password?: boolean;
-}
-/** Session recording configuration */
-export interface SessionRecordingOptions {
-    /** Enable session recording */
-    enabled?: boolean;
-    /** Sample rate (0-1, where 1 = 100%) */
-    sampleRate?: number;
-    /** Minimum session duration in ms before sending */
-    minimumDurationMs?: number;
-    /** Session idle threshold in ms (default: 5 minutes) */
-    sessionIdleThresholdMs?: number;
-    /** Full snapshot interval in ms (default: 5 minutes) */
-    fullSnapshotIntervalMs?: number;
-    /** Enable console log capture */
-    captureConsole?: boolean;
-    /** Enable network request capture */
-    captureNetwork?: boolean;
-    /** Canvas recording settings */
-    captureCanvas?: {
-        recordCanvas?: boolean;
-        canvasFps?: number;
-        canvasQuality?: number;
-    };
-    /** Block class for elements to hide (default: 'vt-no-capture') */
-    blockClass?: string;
-    /** Block selector for elements to hide */
-    blockSelector?: string;
-    /** Ignore class for input masking (default: 'vt-ignore-input') */
-    ignoreClass?: string;
-    /** Mask text class (default: 'vt-mask') */
-    maskTextClass?: string;
-    /** Mask text selector */
-    maskTextSelector?: string;
-    /** Mask all inputs (default: true) */
-    maskAllInputs?: boolean;
-    /** Mask input options */
-    maskInputOptions?: SessionRecordingMaskInputOptions;
-    /** Masking configuration */
-    masking?: {
-        maskAllInputs?: boolean;
-        maskTextSelector?: string;
-        blockSelector?: string;
-    };
-    /** Record headers in network requests */
-    recordHeaders?: boolean;
-    /** Record body in network requests */
-    recordBody?: boolean;
-    /** Compress events before sending (default: true) */
-    compressEvents?: boolean;
-    /** Internal: Mutation throttler refill rate */
-    __mutationThrottlerRefillRate?: number;
-    /** Internal: Mutation throttler bucket size */
-    __mutationThrottlerBucketSize?: number;
-}
-/** Chat widget configuration */
-export interface ChatWidgetConfig {
-    /** Enable/disable chat widget (default: auto from dashboard) */
-    enabled?: boolean;
-    /** Auto-fetch settings from dashboard (default: true) */
-    autoConfig?: boolean;
-    /** Widget position (default: 'bottom-right') */
-    position?: "bottom-right" | "bottom-left";
-    /** Widget header/greeting message */
-    greeting?: string;
-    /** Widget primary color */
-    color?: string;
-    /** Start in AI mode (default: true) */
-    aiMode?: boolean;
-    /** AI greeting message (first message from AI) */
-    aiGreeting?: string;
-    /** Preload widget script on idle vs on-demand */
-    preload?: boolean;
-    /** Offline message shown when business is unavailable */
-    offlineMessage?: string;
-    /** Collect email when offline */
-    collectEmailOffline?: boolean;
-}
-export interface RemoteConfig {
-    /** Default to identified_only mode */
-    defaultIdentifiedOnly?: boolean;
-    /** Feature flags */
-    featureFlags?: FeatureFlagsConfig;
-    /** Session recording config */
-    sessionRecording?: SessionRecordingOptions;
-}

package/lib/types.js

@@ -1,24 +0,0 @@
-"use strict";
-/**
- * VTilt Types
- *
- * Type definitions for the VTilt tracking SDK.
- * Following PostHog's patterns where applicable.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_WEB_VITALS_METRICS = exports.ALL_WEB_VITALS_METRICS = void 0;
-/** All supported Web Vitals metrics */
-exports.ALL_WEB_VITALS_METRICS = [
-    "LCP",
-    "CLS",
-    "FCP",
-    "INP",
-    "TTFB",
-];
-/** Default Web Vitals metrics (matches PostHog defaults) */
-exports.DEFAULT_WEB_VITALS_METRICS = [
-    "LCP",
-    "CLS",
-    "FCP",
-    "INP",
-];

package/lib/user-manager.d.ts

@@ -1,154 +0,0 @@
-/**
- * User Manager - Handles user identity and properties
- *
- * Uses shared StorageManager for consistent storage operations.
- *
- * Manages:
- * - anonymous_id: Generated ID for anonymous users
- * - distinct_id: User-provided ID after identification
- * - device_id: Persistent device identifier
- * - user_properties: Custom properties set via identify/setUserProperties
- * - user_state: "anonymous" or "identified"
- */
-import { UserIdentity, AliasEvent, PersistenceMethod } from "./types";
-export declare class UserManager {
-    private storage;
-    private userIdentity;
-    private _cachedPersonProperties;
-    constructor(storageMethod?: PersistenceMethod, cross_subdomain?: boolean);
-    /**
-     * Get current user identity
-     */
-    getUserIdentity(): UserIdentity;
-    /**
-     * Get current distinct ID (identified user ID)
-     */
-    getDistinctId(): string | null;
-    /**
-     * Get current anonymous ID
-     */
-    getAnonymousId(): string;
-    /**
-     * Get current user properties
-     */
-    getUserProperties(): Record<string, any>;
-    /**
-     * Get the effective ID for event tracking
-     */
-    getEffectiveId(): string;
-    /**
-     * Get current device ID
-     */
-    getDeviceId(): string;
-    /**
-     * Get current user state
-     */
-    getUserState(): "anonymous" | "identified";
-    /**
-     * Identify a user with distinct ID and properties
-     */
-    identify(newDistinctId?: string, userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
-    /**
-     * Set user properties without changing distinct ID
-     */
-    setUserProperties(userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): boolean;
-    /**
-     * Reset user identity (logout)
-     * Generates new anonymous ID, clears user data, optionally resets device ID
-     */
-    reset(reset_device_id?: boolean): void;
-    /**
-     * Update distinct ID (internal use - for VTilt)
-     */
-    setDistinctId(distinctId: string): void;
-    /**
-     * Update user state (internal use - for VTilt)
-     */
-    setUserState(state: "anonymous" | "identified"): void;
-    /**
-     * Update user properties (internal use - for VTilt)
-     */
-    updateUserProperties(userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
-    /**
-     * Set device ID if not already set (internal use - for VTilt)
-     */
-    ensureDeviceId(deviceId: string): void;
-    /**
-     * Create an alias to link two distinct IDs
-     */
-    createAlias(alias: string, original?: string): AliasEvent | null;
-    /**
-     * Check if distinct ID is string-like (hardcoded string) - public for validation
-     */
-    isDistinctIdStringLikePublic(distinctId: string): boolean;
-    /**
-     * Set initial person info
-     */
-    set_initial_person_info(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): void;
-    /**
-     * Get initial props
-     */
-    get_initial_props(): Record<string, any>;
-    /**
-     * Update referrer info
-     */
-    update_referrer_info(): void;
-    /**
-     * Load user identity from storage.
-     *
-     * For traditional SSR websites where each page navigation reloads JavaScript,
-     * identity MUST be persisted immediately when generated to ensure the same
-     * anonymous_id is used across all page loads.
-     *
-     * Flow:
-     * 1. Load from storage (reads cookies first for critical properties in SSR mode)
-     * 2. Generate new IDs if not found
-     * 3. Immediately persist to storage (saved to both localStorage and cookies)
-     *
-     * With `localStorage+cookie` persistence (default):
-     * - Critical properties are stored in cookies for SSR compatibility
-     * - Full data is stored in localStorage for fast SPA-style access
-     * - Cookies ensure identity persists across full page reloads
-     */
-    private loadUserIdentity;
-    /**
-     * Save user identity to storage
-     */
-    private saveUserIdentity;
-    /**
-     * Get user properties from storage
-     */
-    private getStoredUserProperties;
-    /**
-     * Set user properties in storage
-     */
-    private setStoredUserProperties;
-    /**
-     * Register a value once (only if not already set)
-     */
-    private register_once;
-    /**
-     * Generate a new anonymous ID
-     */
-    private generateAnonymousId;
-    /**
-     * Generate a new device ID
-     */
-    private generateDeviceId;
-    /**
-     * Get hash for person properties (for deduplication)
-     */
-    private getPersonPropertiesHash;
-    /**
-     * Validate distinct ID
-     */
-    private isValidDistinctId;
-    /**
-     * Check if distinct ID is string-like (hardcoded string)
-     */
-    private isDistinctIdStringLike;
-    /**
-     * Update storage method at runtime
-     */
-    updateStorageMethod(method: PersistenceMethod, cross_subdomain?: boolean): void;
-}