@v-tilt/browser 1.10.10 → 1.12.0

package/dist/user-manager.d.ts

@@ -10,12 +10,26 @@
  * - user_properties: Custom properties set via identify/setUserProperties
  * - user_state: "anonymous" or "identified"
  */
-import { UserIdentity, AliasEvent, PersistenceMethod } from "./types";
+import { UserIdentity, IdentityUpdate, PersistenceMethod } from "./types";
 export declare class UserManager {
     private storage;
     private userIdentity;
-    private _cachedPersonProperties;
+    private _isFirstVisit;
     constructor(storageMethod?: PersistenceMethod, cross_subdomain?: boolean);
+    /**
+     * Hydrate identity from persistent storage.
+     *
+     * Called by VTilt._boot() once the browser environment is guaranteed ready
+     * (DOMContentLoaded). This is the only code path that reads from
+     * localStorage / cookies. If storage is empty (first visit), the generated
+     * IDs are persisted so they survive the next page load.
+     */
+    hydrateFromStorage(): void;
+    /**
+     * Generate an ephemeral in-memory identity with no storage access.
+     * Used by the constructor so the SDK is safe to instantiate in SSR.
+     */
+    private generateEphemeralIdentity;
     /**
      * Get current user identity
      */
@@ -45,42 +59,20 @@ export declare class UserManager {
      */
     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
+     * Returns true if this is the user's first visit (no prior anonymous_id
+     * in storage when the SDK booted). Resets after first call.
+     * Matches GA4's _fv=1 semantics.
      */
-    setUserProperties(userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): boolean;
+    consumeFirstVisit(): boolean;
     /**
-     * Reset user identity (logout)
-     * Generates new anonymous ID, clears user data, optionally resets device ID
+     * Apply batched identity changes with a single save.
+     * Replaces individual setters to avoid multiple storage writes per operation.
      */
-    reset(reset_device_id?: boolean): void;
+    applyUpdate(update: IdentityUpdate): void;
     /**
-     * Update distinct ID (internal use - for VTilt)
+     * Reset identity to anonymous state. Generates new IDs and clears user data.
      */
-    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;
+    reset(resetDeviceId?: boolean): void;
     /**
      * Set initial person info
      */
@@ -127,28 +119,10 @@ export declare class UserManager {
      * 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
+     * Update storage method at runtime.
      */
     updateStorageMethod(method: PersistenceMethod, cross_subdomain?: boolean): void;
 }

package/dist/utils/base64.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Base64 encoding for binary data.
+ *
+ * Used by the request layer (`request.ts`) and session recording
+ * (`extensions/replay/session-recording.ts`) to send gzip-compressed bodies
+ * over `navigator.sendBeacon` as **text** rather than as a binary `Blob`.
+ *
+ * Why this exists:
+ *
+ *   `sendBeacon(url, blob)` with a binary `Blob` (e.g. a gzipped Uint8Array)
+ *   is racy. Browsers queue the beacon synchronously, then serialize the
+ *   body to the network *after* the JS context has been torn down on
+ *   `pagehide` / tab discard. If the underlying `ArrayBuffer` is detached
+ *   or GC'd before that flush, the wire body ends up empty or truncated —
+ *   while the URL we already committed still carries `?compression=gzip-js`.
+ *   The server then tries `gunzipSync` against an empty buffer and throws
+ *   `Z_BUF_ERROR: unexpected end of file`.
+ *
+ *   Sending the gzip bytes as a base64 *string* sidesteps the problem
+ *   entirely: `Blob([string])` owns its own UTF-8 encoded copy, and
+ *   `sendBeacon` is reliable for text bodies. The server already accepts
+ *   `?compression=base64` for this exact path.
+ */
+/**
+ * Encode a `Uint8Array` to a base64 string using `btoa`.
+ *
+ * Chunks the bytes through `String.fromCharCode` so we don't blow the
+ * argument-count limit on `apply()` for large buffers.
+ */
+export declare function uint8ArrayToBase64(bytes: Uint8Array): string;

package/dist/utils/bot-detection.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Bot / crawler detection for the browser SDK.
+ *
+ * User-agent patterns are aligned with PostHog's `@posthog/core` bot list
+ * (https://github.com/PostHog/posthog-js — `utils/bot-detection.ts`) so
+ * behaviour matches what PostHog integrators expect.
+ *
+ * Keep in sync with `app/src/lib/tracking/bot-detection.ts`.
+ */
+/** Substrings matched case-insensitively against `User-Agent` (and SDK `navigator.userAgent`). */
+export declare const DEFAULT_BLOCKED_UA_STRS: readonly string[];
+/**
+ * Returns true when the user agent matches a known bot/crawler pattern.
+ */
+export declare function isBlockedUA(ua: string | undefined | null, customBlockedUserAgents?: string[]): boolean;
+/** Subset of `Navigator.userAgentData` used for bot checks. */
+export interface NavigatorUAData {
+    brands?: {
+        brand: string;
+        version: string;
+    }[];
+    platform?: string;
+}
+/**
+ * Browser-side bot check (PostHog `isLikelyBot` parity): UA string, CH brand
+ * hints, and `navigator.webdriver`.
+ */
+export declare function isLikelyBot(nav: Navigator | undefined, customBlockedUserAgents?: string[]): boolean;

package/dist/utils/endpoint-url.d.ts

@@ -0,0 +1,36 @@
+import type { VTiltConfig } from "../types";
+/** Header that carries the project token on every authenticated SDK call.
+ *  Matches the server-side `withPublicProjectAccess` wrapper, which reads
+ *  the same name (`request.headers.get('x-api-key')`) before falling back
+ *  to the `?token=` query parameter. */
+export declare const PROJECT_TOKEN_HEADER = "x-api-key";
+export interface BuildEndpointUrlOptions {
+    /**
+     * Append `?token=<token>` to the URL. Off by default so the URL stays
+     * clean — privacy/ad blockers commonly match on `?token=` in known
+     * analytics origins, and the cleaner the URL is the less likely a
+     * legitimate request gets cancelled with `ERR_BLOCKED_BY_CLIENT`.
+     *
+     * Pass `true` only for transports that cannot carry a custom header
+     * (i.e. `navigator.sendBeacon`), where the query parameter is still
+     * the only practical way to authenticate the request.
+     */
+    includeTokenQuery?: boolean;
+}
+/**
+ * Resolves a path + project token to a full request URL.
+ * Used by the main client and by lazy chunks (e.g. session recording) that
+ * only have access to `getConfig()` and must not depend on `VTilt` prototype methods.
+ *
+ * By default the returned URL does NOT carry the project token. Callers
+ * are expected to attach it via the `x-api-key` header (see
+ * `getProjectTokenHeader`). For `sendBeacon` paths where headers aren't
+ * supported, pass `{ includeTokenQuery: true }`.
+ */
+export declare function buildEndpointUrlFromConfig(config: Pick<VTiltConfig, "api_host" | "token">, path: string, options?: BuildEndpointUrlOptions): string;
+/**
+ * Returns the auth header dict to merge into a `fetch` / `XMLHttpRequest`
+ * call. Returns an empty object when no token is configured so callers
+ * can spread it unconditionally.
+ */
+export declare function getProjectTokenHeader(config: Pick<VTiltConfig, "token">): Record<string, string>;

package/dist/utils/event-emitter.d.ts

@@ -96,6 +96,7 @@ export declare const VTiltEvents: {
     readonly SESSION_ROTATED: "session:rotated";
     readonly FEATURE_STARTED: "feature:started";
     readonly FEATURE_STOPPED: "feature:stopped";
+    readonly CONSENT_UPDATED: "consent:updated";
     readonly EVENT_CAPTURED: "event:captured";
     readonly EVENT_SENT: "event:sent";
     readonly EVENT_FAILED: "event:failed";

package/dist/utils/globals.d.ts

@@ -13,7 +13,6 @@ export interface LazyLoadedSessionRecordingInterface {
     sessionId: string;
     status: string;
     isStarted: boolean;
-    onRemoteConfig?: (response: any) => void;
     log: (message: string, level: "log" | "warn" | "error") => void;
     updateConfig: (config: any) => void;
 }
@@ -136,6 +135,8 @@ export interface ChatConfig {
     offlineMessage?: string;
     /** Collect email when offline */
     collectEmailOffline?: boolean;
+    /** Bubble appearance and behavior */
+    bubble?: BubbleConfig;
     /** Called when widget is opened */
     onWidgetOpen?: () => void;
     /** Called when widget is closed */
@@ -171,6 +172,47 @@ export interface ChatTheme {
     userBubbleColor?: string;
     agentBubbleColor?: string;
 }
+/**
+ * First argument to `vt.sendChatMessage()` / {@link LazyLoadedChatInterface.sendMessage}.
+ *
+ * Plain strings stay plain text for backward compatibility. Use `{ markdown: '...' }`,
+ * `{ html: '...' }`, or `options.format` for rich content.
+ */
+export type SendChatMessageContent = string | {
+    text: string;
+} | {
+    markdown: string;
+} | {
+    html: string;
+};
+/**
+ * Options for `vt.sendChatMessage()` / {@link LazyLoadedChatInterface.sendMessage}.
+ */
+export interface SendChatMessageOptions {
+    /**
+     * Target conversation: `'new'` creates a channel, a UUID selects an existing one,
+     * omit to use the active conversation (must already be in conversation view).
+     */
+    channel?: "new" | string;
+    /**
+     * Open the widget panel before sending. Default: true. Pass `open: false` to send without opening.
+     */
+    open?: boolean;
+    /**
+     * Applies when the first argument is a plain string. Default: `text`.
+     * `markdown` and `html` use the same sanitized rendering as AI/agent messages.
+     */
+    format?: "text" | "markdown" | "html";
+}
+/**
+ * Chat bubble appearance and behavior configuration
+ */
+export interface BubbleConfig {
+    /** Allow user to drag the bubble to reposition (default: false) */
+    draggable?: boolean;
+    /** Show the bubble on load (default: true). Set to false to control via vt.chat.show() */
+    visible?: boolean;
+}
 /**
  * Interface for lazy-loaded chat widget (set by chat.ts entrypoint)
  */
@@ -195,12 +237,39 @@ export interface LazyLoadedChatInterface {
     createChannel(): Promise<void>;
     /** Go back to channel list from conversation view */
     goToChannelList(): void;
-    sendMessage(content: string): Promise<void>;
+    sendMessage(content: SendChatMessageContent, options?: SendChatMessageOptions): Promise<void>;
     markAsRead(): void;
     onMessage(callback: (message: ChatMessage) => void): () => void;
     onTyping(callback: (isTyping: boolean, senderType: string) => void): () => void;
     onConnectionChange(callback: (connected: boolean) => void): () => void;
     updateConfig?(config: ChatConfig): void;
+    registerWidget?(definition: {
+        type: string;
+        toolDescription: string;
+        parameters: Record<string, {
+            type: string;
+            description: string;
+        }>;
+        render: (params: Record<string, unknown>, context: {
+            channelId: string;
+            distinctId: string;
+            primaryColor: string;
+            apiBase: string;
+            token: string;
+            messageId: string;
+        }) => string;
+        onAction: (action: string, data: Record<string, unknown>, context: {
+            channelId: string;
+            distinctId: string;
+            primaryColor: string;
+            apiBase: string;
+            token: string;
+            messageId: string;
+        }) => Promise<{
+            replaceHTML?: string;
+            sendMessage?: string;
+        }>;
+    }): void;
     destroy(): void;
 }
 /**

package/dist/utils/index.d.ts

@@ -1,6 +1,9 @@
 export * from "./type-guards";
 export * from "./safewrap";
+export * from "./endpoint-url";
 export * from "./event-emitter";
+export * from "./transport-health";
+export { getLogger, resolveLogLevel, setLevelFromConfig, type LogLevel, type Logger, } from "./logger";
 /**
  * Generate a short, URL-safe random ID (nanoid-compatible).
  * Uses crypto.getRandomValues for entropy — same approach as nanoid.
@@ -12,7 +15,23 @@ export declare function generateId(size?: number): string;
  */
 export declare function isValidUserAgent(userAgent: string): boolean;
 /**
- * Validate payload string
+ * Maximum serialized event payload size, in bytes (1 MB).
+ *
+ * The transport layer gzips bodies before sending and the ingestion API
+ * applies its own server-side limits, so this cap exists only to defeat
+ * runaway client-side bugs (infinite property growth, accidental DOM dumps).
+ *
+ * Previously 10 KB, which silently dropped legitimate `$autocapture` events
+ * on real apps where 15–25 ancestor elements with framework class soup put
+ * the JSON above 10 KB before any user-defined properties were added.
+ *
+ * Aligned with PostHog's analogous client cap (1 MB).
+ */
+export declare const MAX_PAYLOAD_BYTES = 1048576;
+/**
+ * Validate payload string. Used to defend against pathological / runaway
+ * payloads only; routine "this event got too big" cases (deep DOM chains)
+ * must NOT be silently dropped here. See {@link MAX_PAYLOAD_BYTES}.
  */
 export declare function isValidPayload(payloadStr: string): boolean;
 /**
@@ -45,7 +64,3 @@ export declare function stripEmptyProperties<T extends Record<string, any>>(obj:
  * Strip leading dollar sign from string
  */
 export declare function stripLeadingDollar(str: string): string;
-/**
- * Check if value is null
- */
-export declare function isNull(value: any): boolean;

package/dist/utils/logger.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Configurable logger for SDK development tracing.
+ *
+ * Level taxonomy (single source of truth — every SDK file follows it):
+ *  - error: SDK or integrator-supplied input is broken (failed network with no
+ *    retry left, invalid identify input, storage write rejected, feature
+ *    crashed inside safewrap).
+ *  - warn:  degraded but recovering (deprecated API, falling back from
+ *    localStorage to memory, retrying a failed request, ignoring an
+ *    unsupported config option, browser feature missing).
+ *  - info:  one-time lifecycle events the integrator wants in the console
+ *    while wiring the SDK up (SDK initialised, autocapture started/stopped,
+ *    replay started/stopped, chat connected, person identified).
+ *  - debug: per-event trace useful when filing a bug (every captured event
+ *    name, every autocapture skip with reason, every queue flush, request
+ *    URLs, decide-endpoint payload).
+ *
+ * Default floor is 'warn' — so SDK errors and warnings always reach the
+ * integrator without opt-in (matches Amplitude/PostHog/Sentry). Use 'none'
+ * to silence everything (e.g. shared kiosk consoles).
+ *
+ * Resolution precedence for the active level:
+ *  1. log_level / debug passed to vt.init() — locks the level.
+ *  2. Remote config from /decide (diagnostics.defaultLogLevel) — applied only
+ *     if init did not lock the level.
+ *  3. Module default 'warn'.
+ */
+import type { VTiltConfig } from "../types";
+export type LogLevel = "none" | "error" | "warn" | "info" | "debug";
+export interface Logger {
+    /**
+     * Set the active level. When `lockedByInit` is true the level is pinned
+     * and subsequent calls to `setLevelFromRemote` are ignored. Use this
+     * variant only from the init-config resolver in vtilt.ts.
+     */
+    setLevel(level: LogLevel, lockedByInit?: boolean): void;
+    /**
+     * Apply a level coming from remote config. No-op when the integrator
+     * pinned a level at init time, so a hard-coded snippet always wins.
+     */
+    setLevelFromRemote(level: LogLevel | null | undefined): void;
+    getLevel(): LogLevel;
+    isLockedByInit(): boolean;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/**
+ * Get the global SDK logger. Level is set by VTilt from config (log_level or
+ * debug: true) and may later be overridden by remote config via
+ * setLevelFromRemote — unless init pinned the level.
+ */
+export declare function getLogger(): Logger;
+/**
+ * Resolve a log level from VTiltConfig. Centralises the
+ * `log_level ?? (debug ? 'debug' : 'warn')` rule so call sites cannot drift.
+ */
+export declare function resolveLogLevel(config: Pick<VTiltConfig, "log_level" | "debug">): LogLevel;
+/**
+ * Apply a config-derived level to the global logger. Pass `lockedByInit`
+ * (default true) when the call originates from vt.init() so remote config
+ * cannot later override the integrator's choice.
+ */
+export declare function setLevelFromConfig(config: Pick<VTiltConfig, "log_level" | "debug">, lockedByInit?: boolean): LogLevel;
+export declare function __resetLoggerForTests(): void;

package/dist/utils/request-utils.d.ts

@@ -7,6 +7,11 @@
  * IE11 doesn't support `new URL`, so we use anchor element
  */
 export declare function convertToURL(url: string): HTMLAnchorElement | null;
+/**
+ * Parse all query parameters from a URL into a key/value map.
+ * When a key appears more than once, the last value wins.
+ */
+export declare function getAllQueryParams(url: string): Record<string, string>;
 /**
  * Get query parameter from URL
  */

package/dist/utils/safewrap.d.ts

@@ -3,9 +3,14 @@
  *
  * Error isolation utilities to prevent feature errors from crashing the SDK.
  * Following PostHog's safewrap pattern.
+ *
+ * All errors are routed through the central level-gated logger
+ * (`getLogger()`) so they respect the integrator's `log_level` choice.
+ * `error`-level messages always surface in the default `warn` floor.
  */
 /**
- * Logger interface for error reporting
+ * Logger interface for error reporting. Kept narrow so callers can inject a
+ * custom logger in tests without depending on the full `Logger` shape.
  */
 interface Logger {
     error: (...args: unknown[]) => void;

package/dist/utils/transport-health.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Transport health tracking
+ *
+ * Chromium and Firefox surface `ERR_BLOCKED_BY_CLIENT` (or the equivalent
+ * "NetworkError when attempting to fetch") to the JS layer as a generic
+ * `TypeError: Failed to fetch` — there is no programmatic way to tell a
+ * cancelled-by-extension request apart from an offline or DNS failure.
+ *
+ * What we can do is notice the pattern. Once a handful of consecutive
+ * top-level transport failures happen in a row we treat the transport as
+ * "likely blocked" for the rest of the page session and:
+ *
+ *   1. Stop scheduling new requests (no more retries, no new session
+ *      recording POSTs). The browser will keep logging
+ *      `ERR_BLOCKED_BY_CLIENT` for any request the SDK *does* fire, so
+ *      we minimise that noise by firing fewer of them.
+ *   2. Log a single explanatory warning that points integrators at the
+ *      reverse-proxy escape hatch so they aren't left guessing.
+ *
+ * A subsequent successful response resets the counter — transient
+ * connectivity glitches don't latch the SDK into "blocked" mode.
+ *
+ * The state is *page-session scoped*. We deliberately do not persist it
+ * to storage: ad-blocker filter lists change, the user might disable a
+ * blocker for our domain, and we don't want a single bad page load to
+ * cripple every future visit.
+ */
+/**
+ * Record a top-level transport failure (network error / blocked / aborted).
+ *
+ * `scope` is the SDK module reporting the failure (e.g. `"replay"`,
+ * `"capture"`); it's used purely for the warning log message.
+ */
+export declare function markTransportFailure(scope: string): void;
+/**
+ * Record a successful response. Resets the failure counter; a future run
+ * of failures must accumulate from zero before flipping the flag again.
+ *
+ * Does NOT clear the `blocked` flag: once the SDK has decided to back
+ * off in a session it stays backed off for the lifetime of that page.
+ * Without this rule a single intermittent success between failures would
+ * silently re-enable the retry storm we are trying to suppress.
+ */
+export declare function markTransportSuccess(): void;
+/**
+ * Once the SDK believes the transport is blocked, this returns `true`
+ * for the rest of the page session. Callers should skip scheduling work
+ * that would otherwise spam `ERR_BLOCKED_BY_CLIENT` into the console.
+ */
+export declare function isTransportLikelyBlocked(): boolean;
+/**
+ * Test-only reset. Not exported from the package barrel — only
+ * `__tests__` should use it.
+ */
+export declare function __resetTransportHealthForTests(): void;

package/dist/utils/type-guards.d.ts

@@ -39,7 +39,7 @@ export declare function isObject(x: unknown): x is Record<string, unknown>;
 /**
  * Check if value is a function
  */
-export declare function isFunction(x: unknown): x is Function;
+export declare function isFunction(x: unknown): x is (...args: unknown[]) => unknown;
 /**
  * Check if value is a Date object
  */