@unifold/analytics 0.1.72

package/dist/index.d.mts

@@ -0,0 +1,329 @@
+/**
+ * Well-known event names.
+ *
+ * Exported as a const object (not an enum) so it tree-shakes cleanly —
+ * consumers get autocomplete without pulling in a runtime object they
+ * don't use. The `AnalyticsEventName` type still accepts arbitrary
+ * strings so new events don't require an SDK update.
+ */
+declare const AnalyticsEvents: {
+    /** User viewed a screen / step in the flow. */
+    readonly SCREEN_VIEWED: "screen_viewed";
+    /** User selected a payment method. */
+    readonly PAYMENT_METHOD_SELECTED: "payment_method_selected";
+    /**
+     * User picked an asset — the token *and* the chain it lives on. One event
+     * for both, carrying the full identity, because neither half identifies an
+     * asset alone; either dropdown changing re-fires it.
+     */
+    readonly TOKEN_SELECTED: "token_selected";
+    /** User picked a browser wallet to connect. */
+    readonly WALLET_SELECTED: "wallet_selected";
+    /** User picked an onramp/exchange provider (card quote, bank, exchange). */
+    readonly PROVIDER_SELECTED: "provider_selected";
+    /**
+     * User picked what to pay with inside a provider's flow — a card, or a
+     * wallet like Apple Pay. Distinct from `payment_method_selected`, which is
+     * the funding route they chose from the deposit menu.
+     */
+    readonly PAYMENT_METHOD_TYPE_SELECTED: "payment_method_type_selected";
+    /**
+     * User reached a step that asks them to prove something about themselves —
+     * identity details, a document, an emailed or texted code, an exchange MFA
+     * prompt. `verification_type` says which.
+     */
+    readonly VERIFICATION_STARTED: "verification_started";
+    /** User handed over what the step asked for. A provider may still be reviewing. */
+    readonly VERIFICATION_SUBMITTED: "verification_submitted";
+    /** The provider accepted it. */
+    readonly VERIFICATION_COMPLETED: "verification_completed";
+    /** The provider rejected it, or the user backed out. See `failure_reason`. */
+    readonly VERIFICATION_FAILED: "verification_failed";
+    /**
+     * User began linking an account they hold somewhere else — an exchange, a
+     * Stripe Link profile. Distinct from connecting a browser wallet, which the
+     * user already controls locally.
+     */
+    readonly ACCOUNT_CONNECTION_STARTED: "account_connection_started";
+    /** The external account is linked and usable. */
+    readonly ACCOUNT_CONNECTED: "account_connected";
+    /** Linking the external account failed or was abandoned. */
+    readonly ACCOUNT_CONNECTION_FAILED: "account_connection_failed";
+    /** User began connecting a browser wallet. */
+    readonly WALLET_CONNECTION_STARTED: "wallet_connection_started";
+    /** The wallet is connected and usable. */
+    readonly WALLET_CONNECTED: "wallet_connected";
+    /** The connection failed, or the user declined it in their wallet. */
+    readonly WALLET_CONNECTION_FAILED: "wallet_connection_failed";
+    /** User navigated back a step. */
+    readonly BACK_CLICKED: "back_clicked";
+    /** User started a flow (deposit, checkout, withdraw). */
+    readonly FLOW_STARTED: "flow_started";
+    /** User completed a flow successfully. */
+    readonly FLOW_COMPLETED: "flow_completed";
+    /** A flow failed with an error. */
+    readonly FLOW_FAILED: "flow_failed";
+    /** Generic UI interaction (button press, link tap). */
+    readonly BUTTON_CLICKED: "button_clicked";
+    /** Widget/modal opened. */
+    readonly WIDGET_OPENED: "widget_opened";
+    /** Widget/modal closed. */
+    readonly WIDGET_CLOSED: "widget_closed";
+};
+/** Any known event name, or an arbitrary string for forward-compat. */
+type AnalyticsEventName = (typeof AnalyticsEvents)[keyof typeof AnalyticsEvents] | (string & Record<never, never>);
+/** Flat event-specific properties. Keep flat for easy PostHog filtering. */
+interface AnalyticsProperties {
+    /** Payment method (transfer_crypto, card, apple_pay, exchange_connect, etc.) */
+    method?: string;
+    /** Flow type (deposit, checkout, withdraw). */
+    flow_type?: string;
+    /** Screen / step name (method_selector, amount_entry, review, processing, success). */
+    screen?: string;
+    /** Numeric step in the funnel (1-indexed). */
+    step?: number;
+    /** Chain id (e.g. "mainnet", "8453"). */
+    chain?: string;
+    /**
+     * Slugged network name, paired with `chain` (e.g. "base", "hypercore",
+     * "base_sepolia"). Grouping key for charts; `chain` stays the exact id.
+     */
+    network?: string;
+    /** Chain family (ethereum, solana, …). */
+    chain_type?: string;
+    /** Token contract address. */
+    token_address?: string;
+    /** Browser wallet identifier/name (metamask, phantom, …). */
+    wallet?: string;
+    /** Transaction amount in USD. */
+    amount_usd?: string;
+    /** Human-readable token amount (standard unit, e.g. "0.5"). */
+    amount?: string;
+    /** Token amount in base units (smallest denomination). */
+    amount_base_unit?: string;
+    /** UI element identifier for button_clicked events. */
+    element?: string;
+    /** Error code for flow_failed events. */
+    error_code?: string;
+    /** Onramp/exchange provider identifier. */
+    provider?: string;
+    /**
+     * What the user is paying with: `card`, `apple_pay`, `google_pay`. The brand
+     * and the last four digits stay out — which wallet, or none, is the part
+     * that moves conversion.
+     */
+    payment_method_type?: string;
+    /** Token symbol as displayed (e.g. "USDC", "USDC.e", "USDC (Perp)"). */
+    token?: string;
+    /**
+     * Slugged token symbol, paired with `token` (e.g. "usdc", "usdc_e",
+     * "usdc_perp"). Grouping key for charts; `token` stays the display symbol.
+     */
+    currency?: string;
+    /**
+     * What a `verification_*` event is about: `identity`, `document`, `email`,
+     * `phone`, `mfa`, `limit_upgrade`.
+     */
+    verification_type?: string;
+    /**
+     * Provider's own name for the level being verified, when it has tiers —
+     * Stripe's `l0` / `l1` / `l2`. Telemetry only.
+     */
+    verification_tier?: string;
+    /**
+     * Provider's raw status verbatim (`pending`, `rejected`, `resubmit`, …). The
+     * event name says what happened in our terms; this says what the provider
+     * called it, which is what support tickets quote.
+     *
+     * Telemetry only, like every other `verification_*` property: the host is
+     * told a check didn't pass and nothing more.
+     */
+    verification_status?: string;
+    /** Screen navigated away from (back_clicked). */
+    from_screen?: string;
+    /**
+     * Machine-readable failure reason.
+     *
+     * Telemetry only for verification and account connections, where the reason
+     * names what didn't check out about the user. Wallet connections do forward
+     * theirs — declining a prompt is the user's own visible action.
+     */
+    failure_reason?: string;
+    /** Catch-all for forward-compat. */
+    [key: string]: unknown;
+}
+/** Auto-populated SDK/device metadata. Not business data. */
+interface AnalyticsContext {
+    library: {
+        name: string;
+        version: string;
+    };
+    platform?: string;
+}
+/** Full event payload sent to the telemetry backend. */
+interface AnalyticsEvent {
+    event: AnalyticsEventName;
+    timestamp: string;
+    /**
+     * Analytics journey id (`asess_<ksuid>`): one per modal open → close.
+     * Present only while a journey is active (after {@link EventTracker.startSession},
+     * before {@link EventTracker.endSession}). Serialized as `session_id`.
+     */
+    sessionId?: string;
+    /**
+     * Internal Unifold user.id (`user_<ksuid>`), typically obtained from the
+     * deposit-addresses response. Serialized to the wire as `user_id`.
+     */
+    userId?: string;
+    properties: AnalyticsProperties;
+    context: AnalyticsContext;
+}
+interface AnalyticsConfig {
+    /** Full telemetry ingest URL. Must be provided by the host (e.g. connect-react reads it from @unifold/core). */
+    endpoint?: string;
+    /** Publishable key (pk_...) used for auth and project identification. */
+    publishableKey: string;
+    /** SDK version string (e.g. "0.1.70"). Auto-populated from package version if omitted. */
+    sdkVersion?: string;
+    /** Platform identifier (e.g. "web", "ios", "react-native"). */
+    platform?: string;
+    /**
+     * Internal Unifold user.id. Optional at construction — usually set later via
+     * {@link EventTracker.setUserId} once deposit-addresses returns.
+     */
+    userId?: string;
+    /** Disable all telemetry. Events are still emitted locally but never sent. */
+    disabled?: boolean;
+    /** Enable debug logging to console. */
+    debug?: boolean;
+    /**
+     * Dedup window in milliseconds. If the same event name + properties
+     * fires again within this window, the duplicate is dropped.
+     * Prevents noise from React re-renders. Defaults to 500ms.
+     * Set to 0 to disable dedup.
+     */
+    dedupMs?: number;
+}
+
+/**
+ * Lightweight analytics tracker for the Unifold SDK.
+ *
+ * Follows the Segment Track spec: event name + flat `properties` bag +
+ * auto-populated `context` for SDK metadata.
+ *
+ * Includes built-in dedup to prevent noise from React re-renders —
+ * identical events within the dedup window are silently dropped.
+ *
+ * ```ts
+ * const tracker = createEventTracker({ projectId: 'proj_123', platform: 'web' });
+ *
+ * // Funnel tracking
+ * tracker.track('screen_viewed', { screen: 'method_selector', flow_type: 'deposit', step: 1 });
+ * tracker.track('payment_method_selected', { method: 'transfer_crypto', flow_type: 'deposit' });
+ * tracker.track('screen_viewed', { screen: 'amount_entry', flow_type: 'deposit', step: 2 });
+ * tracker.track('flow_completed', { method: 'transfer_crypto', flow_type: 'deposit', amount_usd: '100' });
+ * ```
+ */
+declare class EventTracker {
+    private emitter;
+    private config;
+    private context;
+    private recentEvents;
+    private unsubForwarder;
+    private userId;
+    /** Set only while a journey is active (modal open → close). */
+    private sessionId;
+    constructor(config: AnalyticsConfig);
+    private attachForwarder;
+    private detachForwarder;
+    /**
+     * Track an event. Properties are flat key-value pairs that become
+     * directly filterable dimensions in PostHog.
+     *
+     * Duplicate calls with the same event name + properties within the
+     * dedup window are silently dropped.
+     */
+    track(eventName: AnalyticsEventName, properties?: AnalyticsProperties): void;
+    /**
+     * Associate subsequent events with an internal Unifold user.id
+     * (`user_<ksuid>`). Pass `null` to clear. Usually called once the
+     * deposit-addresses response returns the id.
+     */
+    setUserId(userId: string | null): void;
+    /**
+     * Start a new analytics journey (modal open). Mints an `asess_<ksuid>` and
+     * returns it. Every {@link EventTracker.track} call until
+     * {@link EventTracker.endSession} carries it.
+     *
+     * Does not touch `userId`: the internal `user_<ksuid>` is attached separately
+     * via {@link EventTracker.setUserId} once the deposit-addresses response
+     * returns, and persists until the host replaces it.
+     */
+    startSession(): string;
+    /**
+     * End the current journey (modal close). Clears the session id so any stray
+     * events after close are session-less. Call this *after* the terminal
+     * `widget_closed` track call.
+     */
+    endSession(): void;
+    /** Current analytics journey id, or `undefined` when no journey is active. */
+    getSessionId(): string | undefined;
+    /**
+     * Subscribe to a specific event or `'*'` for all events.
+     * Returns an unsubscribe function.
+     */
+    on(eventName: AnalyticsEventName | '*', handler: (event: AnalyticsEvent) => void): () => void;
+    /** Remove all listeners and stop forwarding. */
+    destroy(): void;
+    /** Enable or disable network forwarding at runtime. Custom listeners are preserved. */
+    setDisabled(disabled: boolean): void;
+}
+/** Create a new EventTracker instance. */
+declare function createEventTracker(config: AnalyticsConfig): EventTracker;
+
+type EventHandler<T> = (event: T) => void;
+/**
+ * Minimal typed event emitter with wildcard support.
+ *
+ * - `on()` returns an unsubscribe function.
+ * - `'*'` subscribes to every event type.
+ * - Handler exceptions are caught so a faulty listener never breaks the host app.
+ */
+declare class Emitter<EventMap extends Record<string, unknown>> {
+    private handlers;
+    on<K extends keyof EventMap>(type: K, handler: EventHandler<EventMap[K]>): () => void;
+    on(type: '*', handler: EventHandler<EventMap[keyof EventMap]>): () => void;
+    emit<K extends keyof EventMap>(type: K, event: EventMap[K]): void;
+    removeAllListeners(): void;
+}
+
+/**
+ * Fire-and-forget POST of an analytics event.
+ *
+ * - Sends the publishable key via `x-publishable-key` header for auth.
+ * - Uses `keepalive: true` so the request completes even during page unload.
+ * - Never throws — failures are silently swallowed (optionally logged in debug mode).
+ */
+declare function forwardEvent(event: AnalyticsEvent, publishableKey: string, endpoint?: string, debug?: boolean): void;
+
+/**
+ * Dependency-free KSUID generator.
+ *
+ * Kept in sync with `@unifold/core`'s implementation (packages/core/src/lib/utils.ts)
+ * but duplicated intentionally: `@unifold/analytics` is a zero-dependency leaf
+ * package and must not depend on `@unifold/core`.
+ */
+/**
+ * Generate a KSUID-like ID without external dependencies.
+ * Format: `base62(4-byte-timestamp + 16-random-bytes)` (27 chars).
+ */
+declare function generateKSUID(): string;
+/**
+ * Generate a KSUID-like prefixed ID without external dependencies.
+ * Format: `{prefix}_{base62(...)}`.
+ */
+declare function generatePrefixedKSUID(prefix: string): string;
+
+declare const PACKAGE_VERSION = "0.1.72";
+
+export { type AnalyticsConfig, type AnalyticsContext, type AnalyticsEvent, type AnalyticsEventName, AnalyticsEvents, type AnalyticsProperties, Emitter, EventTracker, PACKAGE_VERSION, createEventTracker, forwardEvent, generateKSUID, generatePrefixedKSUID };

package/dist/index.d.ts

@@ -0,0 +1,329 @@
+/**
+ * Well-known event names.
+ *
+ * Exported as a const object (not an enum) so it tree-shakes cleanly —
+ * consumers get autocomplete without pulling in a runtime object they
+ * don't use. The `AnalyticsEventName` type still accepts arbitrary
+ * strings so new events don't require an SDK update.
+ */
+declare const AnalyticsEvents: {
+    /** User viewed a screen / step in the flow. */
+    readonly SCREEN_VIEWED: "screen_viewed";
+    /** User selected a payment method. */
+    readonly PAYMENT_METHOD_SELECTED: "payment_method_selected";
+    /**
+     * User picked an asset — the token *and* the chain it lives on. One event
+     * for both, carrying the full identity, because neither half identifies an
+     * asset alone; either dropdown changing re-fires it.
+     */
+    readonly TOKEN_SELECTED: "token_selected";
+    /** User picked a browser wallet to connect. */
+    readonly WALLET_SELECTED: "wallet_selected";
+    /** User picked an onramp/exchange provider (card quote, bank, exchange). */
+    readonly PROVIDER_SELECTED: "provider_selected";
+    /**
+     * User picked what to pay with inside a provider's flow — a card, or a
+     * wallet like Apple Pay. Distinct from `payment_method_selected`, which is
+     * the funding route they chose from the deposit menu.
+     */
+    readonly PAYMENT_METHOD_TYPE_SELECTED: "payment_method_type_selected";
+    /**
+     * User reached a step that asks them to prove something about themselves —
+     * identity details, a document, an emailed or texted code, an exchange MFA
+     * prompt. `verification_type` says which.
+     */
+    readonly VERIFICATION_STARTED: "verification_started";
+    /** User handed over what the step asked for. A provider may still be reviewing. */
+    readonly VERIFICATION_SUBMITTED: "verification_submitted";
+    /** The provider accepted it. */
+    readonly VERIFICATION_COMPLETED: "verification_completed";
+    /** The provider rejected it, or the user backed out. See `failure_reason`. */
+    readonly VERIFICATION_FAILED: "verification_failed";
+    /**
+     * User began linking an account they hold somewhere else — an exchange, a
+     * Stripe Link profile. Distinct from connecting a browser wallet, which the
+     * user already controls locally.
+     */
+    readonly ACCOUNT_CONNECTION_STARTED: "account_connection_started";
+    /** The external account is linked and usable. */
+    readonly ACCOUNT_CONNECTED: "account_connected";
+    /** Linking the external account failed or was abandoned. */
+    readonly ACCOUNT_CONNECTION_FAILED: "account_connection_failed";
+    /** User began connecting a browser wallet. */
+    readonly WALLET_CONNECTION_STARTED: "wallet_connection_started";
+    /** The wallet is connected and usable. */
+    readonly WALLET_CONNECTED: "wallet_connected";
+    /** The connection failed, or the user declined it in their wallet. */
+    readonly WALLET_CONNECTION_FAILED: "wallet_connection_failed";
+    /** User navigated back a step. */
+    readonly BACK_CLICKED: "back_clicked";
+    /** User started a flow (deposit, checkout, withdraw). */
+    readonly FLOW_STARTED: "flow_started";
+    /** User completed a flow successfully. */
+    readonly FLOW_COMPLETED: "flow_completed";
+    /** A flow failed with an error. */
+    readonly FLOW_FAILED: "flow_failed";
+    /** Generic UI interaction (button press, link tap). */
+    readonly BUTTON_CLICKED: "button_clicked";
+    /** Widget/modal opened. */
+    readonly WIDGET_OPENED: "widget_opened";
+    /** Widget/modal closed. */
+    readonly WIDGET_CLOSED: "widget_closed";
+};
+/** Any known event name, or an arbitrary string for forward-compat. */
+type AnalyticsEventName = (typeof AnalyticsEvents)[keyof typeof AnalyticsEvents] | (string & Record<never, never>);
+/** Flat event-specific properties. Keep flat for easy PostHog filtering. */
+interface AnalyticsProperties {
+    /** Payment method (transfer_crypto, card, apple_pay, exchange_connect, etc.) */
+    method?: string;
+    /** Flow type (deposit, checkout, withdraw). */
+    flow_type?: string;
+    /** Screen / step name (method_selector, amount_entry, review, processing, success). */
+    screen?: string;
+    /** Numeric step in the funnel (1-indexed). */
+    step?: number;
+    /** Chain id (e.g. "mainnet", "8453"). */
+    chain?: string;
+    /**
+     * Slugged network name, paired with `chain` (e.g. "base", "hypercore",
+     * "base_sepolia"). Grouping key for charts; `chain` stays the exact id.
+     */
+    network?: string;
+    /** Chain family (ethereum, solana, …). */
+    chain_type?: string;
+    /** Token contract address. */
+    token_address?: string;
+    /** Browser wallet identifier/name (metamask, phantom, …). */
+    wallet?: string;
+    /** Transaction amount in USD. */
+    amount_usd?: string;
+    /** Human-readable token amount (standard unit, e.g. "0.5"). */
+    amount?: string;
+    /** Token amount in base units (smallest denomination). */
+    amount_base_unit?: string;
+    /** UI element identifier for button_clicked events. */
+    element?: string;
+    /** Error code for flow_failed events. */
+    error_code?: string;
+    /** Onramp/exchange provider identifier. */
+    provider?: string;
+    /**
+     * What the user is paying with: `card`, `apple_pay`, `google_pay`. The brand
+     * and the last four digits stay out — which wallet, or none, is the part
+     * that moves conversion.
+     */
+    payment_method_type?: string;
+    /** Token symbol as displayed (e.g. "USDC", "USDC.e", "USDC (Perp)"). */
+    token?: string;
+    /**
+     * Slugged token symbol, paired with `token` (e.g. "usdc", "usdc_e",
+     * "usdc_perp"). Grouping key for charts; `token` stays the display symbol.
+     */
+    currency?: string;
+    /**
+     * What a `verification_*` event is about: `identity`, `document`, `email`,
+     * `phone`, `mfa`, `limit_upgrade`.
+     */
+    verification_type?: string;
+    /**
+     * Provider's own name for the level being verified, when it has tiers —
+     * Stripe's `l0` / `l1` / `l2`. Telemetry only.
+     */
+    verification_tier?: string;
+    /**
+     * Provider's raw status verbatim (`pending`, `rejected`, `resubmit`, …). The
+     * event name says what happened in our terms; this says what the provider
+     * called it, which is what support tickets quote.
+     *
+     * Telemetry only, like every other `verification_*` property: the host is
+     * told a check didn't pass and nothing more.
+     */
+    verification_status?: string;
+    /** Screen navigated away from (back_clicked). */
+    from_screen?: string;
+    /**
+     * Machine-readable failure reason.
+     *
+     * Telemetry only for verification and account connections, where the reason
+     * names what didn't check out about the user. Wallet connections do forward
+     * theirs — declining a prompt is the user's own visible action.
+     */
+    failure_reason?: string;
+    /** Catch-all for forward-compat. */
+    [key: string]: unknown;
+}
+/** Auto-populated SDK/device metadata. Not business data. */
+interface AnalyticsContext {
+    library: {
+        name: string;
+        version: string;
+    };
+    platform?: string;
+}
+/** Full event payload sent to the telemetry backend. */
+interface AnalyticsEvent {
+    event: AnalyticsEventName;
+    timestamp: string;
+    /**
+     * Analytics journey id (`asess_<ksuid>`): one per modal open → close.
+     * Present only while a journey is active (after {@link EventTracker.startSession},
+     * before {@link EventTracker.endSession}). Serialized as `session_id`.
+     */
+    sessionId?: string;
+    /**
+     * Internal Unifold user.id (`user_<ksuid>`), typically obtained from the
+     * deposit-addresses response. Serialized to the wire as `user_id`.
+     */
+    userId?: string;
+    properties: AnalyticsProperties;
+    context: AnalyticsContext;
+}
+interface AnalyticsConfig {
+    /** Full telemetry ingest URL. Must be provided by the host (e.g. connect-react reads it from @unifold/core). */
+    endpoint?: string;
+    /** Publishable key (pk_...) used for auth and project identification. */
+    publishableKey: string;
+    /** SDK version string (e.g. "0.1.70"). Auto-populated from package version if omitted. */
+    sdkVersion?: string;
+    /** Platform identifier (e.g. "web", "ios", "react-native"). */
+    platform?: string;
+    /**
+     * Internal Unifold user.id. Optional at construction — usually set later via
+     * {@link EventTracker.setUserId} once deposit-addresses returns.
+     */
+    userId?: string;
+    /** Disable all telemetry. Events are still emitted locally but never sent. */
+    disabled?: boolean;
+    /** Enable debug logging to console. */
+    debug?: boolean;
+    /**
+     * Dedup window in milliseconds. If the same event name + properties
+     * fires again within this window, the duplicate is dropped.
+     * Prevents noise from React re-renders. Defaults to 500ms.
+     * Set to 0 to disable dedup.
+     */
+    dedupMs?: number;
+}
+
+/**
+ * Lightweight analytics tracker for the Unifold SDK.
+ *
+ * Follows the Segment Track spec: event name + flat `properties` bag +
+ * auto-populated `context` for SDK metadata.
+ *
+ * Includes built-in dedup to prevent noise from React re-renders —
+ * identical events within the dedup window are silently dropped.
+ *
+ * ```ts
+ * const tracker = createEventTracker({ projectId: 'proj_123', platform: 'web' });
+ *
+ * // Funnel tracking
+ * tracker.track('screen_viewed', { screen: 'method_selector', flow_type: 'deposit', step: 1 });
+ * tracker.track('payment_method_selected', { method: 'transfer_crypto', flow_type: 'deposit' });
+ * tracker.track('screen_viewed', { screen: 'amount_entry', flow_type: 'deposit', step: 2 });
+ * tracker.track('flow_completed', { method: 'transfer_crypto', flow_type: 'deposit', amount_usd: '100' });
+ * ```
+ */
+declare class EventTracker {
+    private emitter;
+    private config;
+    private context;
+    private recentEvents;
+    private unsubForwarder;
+    private userId;
+    /** Set only while a journey is active (modal open → close). */
+    private sessionId;
+    constructor(config: AnalyticsConfig);
+    private attachForwarder;
+    private detachForwarder;
+    /**
+     * Track an event. Properties are flat key-value pairs that become
+     * directly filterable dimensions in PostHog.
+     *
+     * Duplicate calls with the same event name + properties within the
+     * dedup window are silently dropped.
+     */
+    track(eventName: AnalyticsEventName, properties?: AnalyticsProperties): void;
+    /**
+     * Associate subsequent events with an internal Unifold user.id
+     * (`user_<ksuid>`). Pass `null` to clear. Usually called once the
+     * deposit-addresses response returns the id.
+     */
+    setUserId(userId: string | null): void;
+    /**
+     * Start a new analytics journey (modal open). Mints an `asess_<ksuid>` and
+     * returns it. Every {@link EventTracker.track} call until
+     * {@link EventTracker.endSession} carries it.
+     *
+     * Does not touch `userId`: the internal `user_<ksuid>` is attached separately
+     * via {@link EventTracker.setUserId} once the deposit-addresses response
+     * returns, and persists until the host replaces it.
+     */
+    startSession(): string;
+    /**
+     * End the current journey (modal close). Clears the session id so any stray
+     * events after close are session-less. Call this *after* the terminal
+     * `widget_closed` track call.
+     */
+    endSession(): void;
+    /** Current analytics journey id, or `undefined` when no journey is active. */
+    getSessionId(): string | undefined;
+    /**
+     * Subscribe to a specific event or `'*'` for all events.
+     * Returns an unsubscribe function.
+     */
+    on(eventName: AnalyticsEventName | '*', handler: (event: AnalyticsEvent) => void): () => void;
+    /** Remove all listeners and stop forwarding. */
+    destroy(): void;
+    /** Enable or disable network forwarding at runtime. Custom listeners are preserved. */
+    setDisabled(disabled: boolean): void;
+}
+/** Create a new EventTracker instance. */
+declare function createEventTracker(config: AnalyticsConfig): EventTracker;
+
+type EventHandler<T> = (event: T) => void;
+/**
+ * Minimal typed event emitter with wildcard support.
+ *
+ * - `on()` returns an unsubscribe function.
+ * - `'*'` subscribes to every event type.
+ * - Handler exceptions are caught so a faulty listener never breaks the host app.
+ */
+declare class Emitter<EventMap extends Record<string, unknown>> {
+    private handlers;
+    on<K extends keyof EventMap>(type: K, handler: EventHandler<EventMap[K]>): () => void;
+    on(type: '*', handler: EventHandler<EventMap[keyof EventMap]>): () => void;
+    emit<K extends keyof EventMap>(type: K, event: EventMap[K]): void;
+    removeAllListeners(): void;
+}
+
+/**
+ * Fire-and-forget POST of an analytics event.
+ *
+ * - Sends the publishable key via `x-publishable-key` header for auth.
+ * - Uses `keepalive: true` so the request completes even during page unload.
+ * - Never throws — failures are silently swallowed (optionally logged in debug mode).
+ */
+declare function forwardEvent(event: AnalyticsEvent, publishableKey: string, endpoint?: string, debug?: boolean): void;
+
+/**
+ * Dependency-free KSUID generator.
+ *
+ * Kept in sync with `@unifold/core`'s implementation (packages/core/src/lib/utils.ts)
+ * but duplicated intentionally: `@unifold/analytics` is a zero-dependency leaf
+ * package and must not depend on `@unifold/core`.
+ */
+/**
+ * Generate a KSUID-like ID without external dependencies.
+ * Format: `base62(4-byte-timestamp + 16-random-bytes)` (27 chars).
+ */
+declare function generateKSUID(): string;
+/**
+ * Generate a KSUID-like prefixed ID without external dependencies.
+ * Format: `{prefix}_{base62(...)}`.
+ */
+declare function generatePrefixedKSUID(prefix: string): string;
+
+declare const PACKAGE_VERSION = "0.1.72";
+
+export { type AnalyticsConfig, type AnalyticsContext, type AnalyticsEvent, type AnalyticsEventName, AnalyticsEvents, type AnalyticsProperties, Emitter, EventTracker, PACKAGE_VERSION, createEventTracker, forwardEvent, generateKSUID, generatePrefixedKSUID };

package/dist/index.js

@@ -0,0 +1,326 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/emitter.ts
+var Emitter = class {
+  constructor() {
+    __publicField(this, "handlers", /* @__PURE__ */ new Map());
+  }
+  on(type, handler) {
+    let set = this.handlers.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlers.set(type, set);
+    }
+    set.add(handler);
+    return () => {
+      set.delete(handler);
+    };
+  }
+  emit(type, event) {
+    const dispatch = (handler) => {
+      try {
+        handler(event);
+      } catch (err) {
+        console.error("[unifold/event-tracker] handler threw", err);
+      }
+    };
+    this.handlers.get(type)?.forEach(dispatch);
+    this.handlers.get("*")?.forEach(dispatch);
+  }
+  removeAllListeners() {
+    this.handlers.clear();
+  }
+};
+
+// src/forwarder.ts
+var DEFAULT_ENDPOINT = "/v1/public/events";
+function forwardEvent(event, publishableKey, endpoint = DEFAULT_ENDPOINT, debug = false) {
+  try {
+    if (typeof fetch === "undefined") {
+      if (debug) console.debug("[unifold/analytics] fetch unavailable, skipping forward");
+      return;
+    }
+    const { sessionId, userId, ...rest } = event;
+    const body = {
+      ...rest,
+      // Only attach session_id while a journey is active (modal open → close).
+      ...sessionId ? { session_id: sessionId } : {},
+      ...userId ? { user_id: userId } : {}
+    };
+    fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-publishable-key": publishableKey
+      },
+      body: JSON.stringify(body),
+      keepalive: true
+    }).catch((err) => {
+      if (debug) console.debug("[unifold/analytics] forward failed", err);
+    });
+  } catch (err) {
+    if (debug) console.debug("[unifold/analytics] forward error", err);
+  }
+}
+
+// src/ksuid.ts
+function generateKSUID() {
+  const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+  const KSUID_EPOCH = 14e8;
+  const timestampSeconds = Math.floor(Date.now() / 1e3) - KSUID_EPOCH;
+  const payload = new Uint8Array(20);
+  payload[0] = timestampSeconds >>> 24 & 255;
+  payload[1] = timestampSeconds >>> 16 & 255;
+  payload[2] = timestampSeconds >>> 8 & 255;
+  payload[3] = timestampSeconds & 255;
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(payload.subarray(4));
+  } else {
+    for (let i = 4; i < 20; i++) {
+      payload[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  let value = 0n;
+  for (const byte of payload) {
+    value = value << 8n | BigInt(byte);
+  }
+  let encoded = "";
+  while (value > 0n) {
+    encoded = BASE62[Number(value % 62n)] + encoded;
+    value = value / 62n;
+  }
+  return encoded.padStart(27, "0");
+}
+function generatePrefixedKSUID(prefix) {
+  return `${prefix}_${generateKSUID()}`;
+}
+
+// src/version.ts
+var PACKAGE_VERSION = "0.1.72";
+
+// src/tracker.ts
+var LIBRARY_NAME = "@unifold/analytics";
+var DEFAULT_DEDUP_MS = 500;
+var SESSION_PREFIX = "asess";
+function dedupKey(sessionId, eventName, properties) {
+  const sorted = Object.keys(properties).sort().map((k) => `${k}=${String(properties[k])}`).join("&");
+  return `${sessionId ?? ""}|${eventName}|${sorted}`;
+}
+var EventTracker = class {
+  constructor(config) {
+    __publicField(this, "emitter", new Emitter());
+    __publicField(this, "config");
+    __publicField(this, "context");
+    __publicField(this, "recentEvents", /* @__PURE__ */ new Map());
+    __publicField(this, "unsubForwarder", null);
+    __publicField(this, "userId");
+    /** Set only while a journey is active (modal open → close). */
+    __publicField(this, "sessionId");
+    this.config = {
+      endpoint: config.endpoint ?? "/v1/public/events",
+      publishableKey: config.publishableKey,
+      sdkVersion: config.sdkVersion ?? PACKAGE_VERSION,
+      platform: config.platform ?? "web",
+      userId: config.userId ?? "",
+      disabled: config.disabled ?? false,
+      debug: config.debug ?? false,
+      dedupMs: config.dedupMs ?? DEFAULT_DEDUP_MS
+    };
+    this.userId = config.userId || void 0;
+    this.context = {
+      library: {
+        name: LIBRARY_NAME,
+        version: this.config.sdkVersion
+      },
+      platform: this.config.platform
+    };
+    if (!this.config.disabled) {
+      this.attachForwarder();
+    }
+  }
+  attachForwarder() {
+    this.unsubForwarder = this.emitter.on("*", (event) => {
+      forwardEvent(event, this.config.publishableKey, this.config.endpoint, this.config.debug);
+    });
+  }
+  detachForwarder() {
+    this.unsubForwarder?.();
+    this.unsubForwarder = null;
+  }
+  /**
+   * Track an event. Properties are flat key-value pairs that become
+   * directly filterable dimensions in PostHog.
+   *
+   * Duplicate calls with the same event name + properties within the
+   * dedup window are silently dropped.
+   */
+  track(eventName, properties) {
+    const props = properties ?? {};
+    if (this.config.dedupMs > 0) {
+      const key = dedupKey(this.sessionId, eventName, props);
+      const now = Date.now();
+      const lastSeen = this.recentEvents.get(key);
+      if (lastSeen !== void 0 && now - lastSeen < this.config.dedupMs) {
+        if (this.config.debug) {
+          console.debug("[unifold/analytics] dedup suppressed", eventName);
+        }
+        return;
+      }
+      this.recentEvents.set(key, now);
+      if (this.recentEvents.size > 200) {
+        const cutoff = now - this.config.dedupMs;
+        for (const [k, ts] of this.recentEvents) {
+          if (ts < cutoff) this.recentEvents.delete(k);
+        }
+      }
+    }
+    const event = {
+      event: eventName,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      sessionId: this.sessionId,
+      userId: this.userId,
+      properties: props,
+      context: this.context
+    };
+    if (this.config.debug) {
+      console.debug("[unifold/analytics] track", eventName, event);
+    }
+    this.emitter.emit(eventName, event);
+  }
+  /**
+   * Associate subsequent events with an internal Unifold user.id
+   * (`user_<ksuid>`). Pass `null` to clear. Usually called once the
+   * deposit-addresses response returns the id.
+   */
+  setUserId(userId) {
+    this.userId = userId || void 0;
+  }
+  /**
+   * Start a new analytics journey (modal open). Mints an `asess_<ksuid>` and
+   * returns it. Every {@link EventTracker.track} call until
+   * {@link EventTracker.endSession} carries it.
+   *
+   * Does not touch `userId`: the internal `user_<ksuid>` is attached separately
+   * via {@link EventTracker.setUserId} once the deposit-addresses response
+   * returns, and persists until the host replaces it.
+   */
+  startSession() {
+    this.sessionId = generatePrefixedKSUID(SESSION_PREFIX);
+    return this.sessionId;
+  }
+  /**
+   * End the current journey (modal close). Clears the session id so any stray
+   * events after close are session-less. Call this *after* the terminal
+   * `widget_closed` track call.
+   */
+  endSession() {
+    this.sessionId = void 0;
+  }
+  /** Current analytics journey id, or `undefined` when no journey is active. */
+  getSessionId() {
+    return this.sessionId;
+  }
+  /**
+   * Subscribe to a specific event or `'*'` for all events.
+   * Returns an unsubscribe function.
+   */
+  on(eventName, handler) {
+    return this.emitter.on(eventName, handler);
+  }
+  /** Remove all listeners and stop forwarding. */
+  destroy() {
+    this.emitter.removeAllListeners();
+    this.recentEvents.clear();
+  }
+  /** Enable or disable network forwarding at runtime. Custom listeners are preserved. */
+  setDisabled(disabled) {
+    if (disabled && !this.config.disabled) {
+      this.detachForwarder();
+    } else if (!disabled && this.config.disabled) {
+      this.attachForwarder();
+    }
+    this.config.disabled = disabled;
+  }
+};
+function createEventTracker(config) {
+  return new EventTracker(config);
+}
+
+// src/types.ts
+var AnalyticsEvents = {
+  /** User viewed a screen / step in the flow. */
+  SCREEN_VIEWED: "screen_viewed",
+  /** User selected a payment method. */
+  PAYMENT_METHOD_SELECTED: "payment_method_selected",
+  /**
+   * User picked an asset — the token *and* the chain it lives on. One event
+   * for both, carrying the full identity, because neither half identifies an
+   * asset alone; either dropdown changing re-fires it.
+   */
+  TOKEN_SELECTED: "token_selected",
+  /** User picked a browser wallet to connect. */
+  WALLET_SELECTED: "wallet_selected",
+  /** User picked an onramp/exchange provider (card quote, bank, exchange). */
+  PROVIDER_SELECTED: "provider_selected",
+  /**
+   * User picked what to pay with inside a provider's flow — a card, or a
+   * wallet like Apple Pay. Distinct from `payment_method_selected`, which is
+   * the funding route they chose from the deposit menu.
+   */
+  PAYMENT_METHOD_TYPE_SELECTED: "payment_method_type_selected",
+  /**
+   * User reached a step that asks them to prove something about themselves —
+   * identity details, a document, an emailed or texted code, an exchange MFA
+   * prompt. `verification_type` says which.
+   */
+  VERIFICATION_STARTED: "verification_started",
+  /** User handed over what the step asked for. A provider may still be reviewing. */
+  VERIFICATION_SUBMITTED: "verification_submitted",
+  /** The provider accepted it. */
+  VERIFICATION_COMPLETED: "verification_completed",
+  /** The provider rejected it, or the user backed out. See `failure_reason`. */
+  VERIFICATION_FAILED: "verification_failed",
+  /**
+   * User began linking an account they hold somewhere else — an exchange, a
+   * Stripe Link profile. Distinct from connecting a browser wallet, which the
+   * user already controls locally.
+   */
+  ACCOUNT_CONNECTION_STARTED: "account_connection_started",
+  /** The external account is linked and usable. */
+  ACCOUNT_CONNECTED: "account_connected",
+  /** Linking the external account failed or was abandoned. */
+  ACCOUNT_CONNECTION_FAILED: "account_connection_failed",
+  /** User began connecting a browser wallet. */
+  WALLET_CONNECTION_STARTED: "wallet_connection_started",
+  /** The wallet is connected and usable. */
+  WALLET_CONNECTED: "wallet_connected",
+  /** The connection failed, or the user declined it in their wallet. */
+  WALLET_CONNECTION_FAILED: "wallet_connection_failed",
+  /** User navigated back a step. */
+  BACK_CLICKED: "back_clicked",
+  /** User started a flow (deposit, checkout, withdraw). */
+  FLOW_STARTED: "flow_started",
+  /** User completed a flow successfully. */
+  FLOW_COMPLETED: "flow_completed",
+  /** A flow failed with an error. */
+  FLOW_FAILED: "flow_failed",
+  /** Generic UI interaction (button press, link tap). */
+  BUTTON_CLICKED: "button_clicked",
+  /** Widget/modal opened. */
+  WIDGET_OPENED: "widget_opened",
+  /** Widget/modal closed. */
+  WIDGET_CLOSED: "widget_closed"
+};
+
+exports.AnalyticsEvents = AnalyticsEvents;
+exports.Emitter = Emitter;
+exports.EventTracker = EventTracker;
+exports.PACKAGE_VERSION = PACKAGE_VERSION;
+exports.createEventTracker = createEventTracker;
+exports.forwardEvent = forwardEvent;
+exports.generateKSUID = generateKSUID;
+exports.generatePrefixedKSUID = generatePrefixedKSUID;

package/dist/index.mjs

@@ -0,0 +1,317 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/emitter.ts
+var Emitter = class {
+  constructor() {
+    __publicField(this, "handlers", /* @__PURE__ */ new Map());
+  }
+  on(type, handler) {
+    let set = this.handlers.get(type);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlers.set(type, set);
+    }
+    set.add(handler);
+    return () => {
+      set.delete(handler);
+    };
+  }
+  emit(type, event) {
+    const dispatch = (handler) => {
+      try {
+        handler(event);
+      } catch (err) {
+        console.error("[unifold/event-tracker] handler threw", err);
+      }
+    };
+    this.handlers.get(type)?.forEach(dispatch);
+    this.handlers.get("*")?.forEach(dispatch);
+  }
+  removeAllListeners() {
+    this.handlers.clear();
+  }
+};
+
+// src/forwarder.ts
+var DEFAULT_ENDPOINT = "/v1/public/events";
+function forwardEvent(event, publishableKey, endpoint = DEFAULT_ENDPOINT, debug = false) {
+  try {
+    if (typeof fetch === "undefined") {
+      if (debug) console.debug("[unifold/analytics] fetch unavailable, skipping forward");
+      return;
+    }
+    const { sessionId, userId, ...rest } = event;
+    const body = {
+      ...rest,
+      // Only attach session_id while a journey is active (modal open → close).
+      ...sessionId ? { session_id: sessionId } : {},
+      ...userId ? { user_id: userId } : {}
+    };
+    fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-publishable-key": publishableKey
+      },
+      body: JSON.stringify(body),
+      keepalive: true
+    }).catch((err) => {
+      if (debug) console.debug("[unifold/analytics] forward failed", err);
+    });
+  } catch (err) {
+    if (debug) console.debug("[unifold/analytics] forward error", err);
+  }
+}
+
+// src/ksuid.ts
+function generateKSUID() {
+  const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+  const KSUID_EPOCH = 14e8;
+  const timestampSeconds = Math.floor(Date.now() / 1e3) - KSUID_EPOCH;
+  const payload = new Uint8Array(20);
+  payload[0] = timestampSeconds >>> 24 & 255;
+  payload[1] = timestampSeconds >>> 16 & 255;
+  payload[2] = timestampSeconds >>> 8 & 255;
+  payload[3] = timestampSeconds & 255;
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(payload.subarray(4));
+  } else {
+    for (let i = 4; i < 20; i++) {
+      payload[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  let value = 0n;
+  for (const byte of payload) {
+    value = value << 8n | BigInt(byte);
+  }
+  let encoded = "";
+  while (value > 0n) {
+    encoded = BASE62[Number(value % 62n)] + encoded;
+    value = value / 62n;
+  }
+  return encoded.padStart(27, "0");
+}
+function generatePrefixedKSUID(prefix) {
+  return `${prefix}_${generateKSUID()}`;
+}
+
+// src/version.ts
+var PACKAGE_VERSION = "0.1.72";
+
+// src/tracker.ts
+var LIBRARY_NAME = "@unifold/analytics";
+var DEFAULT_DEDUP_MS = 500;
+var SESSION_PREFIX = "asess";
+function dedupKey(sessionId, eventName, properties) {
+  const sorted = Object.keys(properties).sort().map((k) => `${k}=${String(properties[k])}`).join("&");
+  return `${sessionId ?? ""}|${eventName}|${sorted}`;
+}
+var EventTracker = class {
+  constructor(config) {
+    __publicField(this, "emitter", new Emitter());
+    __publicField(this, "config");
+    __publicField(this, "context");
+    __publicField(this, "recentEvents", /* @__PURE__ */ new Map());
+    __publicField(this, "unsubForwarder", null);
+    __publicField(this, "userId");
+    /** Set only while a journey is active (modal open → close). */
+    __publicField(this, "sessionId");
+    this.config = {
+      endpoint: config.endpoint ?? "/v1/public/events",
+      publishableKey: config.publishableKey,
+      sdkVersion: config.sdkVersion ?? PACKAGE_VERSION,
+      platform: config.platform ?? "web",
+      userId: config.userId ?? "",
+      disabled: config.disabled ?? false,
+      debug: config.debug ?? false,
+      dedupMs: config.dedupMs ?? DEFAULT_DEDUP_MS
+    };
+    this.userId = config.userId || void 0;
+    this.context = {
+      library: {
+        name: LIBRARY_NAME,
+        version: this.config.sdkVersion
+      },
+      platform: this.config.platform
+    };
+    if (!this.config.disabled) {
+      this.attachForwarder();
+    }
+  }
+  attachForwarder() {
+    this.unsubForwarder = this.emitter.on("*", (event) => {
+      forwardEvent(event, this.config.publishableKey, this.config.endpoint, this.config.debug);
+    });
+  }
+  detachForwarder() {
+    this.unsubForwarder?.();
+    this.unsubForwarder = null;
+  }
+  /**
+   * Track an event. Properties are flat key-value pairs that become
+   * directly filterable dimensions in PostHog.
+   *
+   * Duplicate calls with the same event name + properties within the
+   * dedup window are silently dropped.
+   */
+  track(eventName, properties) {
+    const props = properties ?? {};
+    if (this.config.dedupMs > 0) {
+      const key = dedupKey(this.sessionId, eventName, props);
+      const now = Date.now();
+      const lastSeen = this.recentEvents.get(key);
+      if (lastSeen !== void 0 && now - lastSeen < this.config.dedupMs) {
+        if (this.config.debug) {
+          console.debug("[unifold/analytics] dedup suppressed", eventName);
+        }
+        return;
+      }
+      this.recentEvents.set(key, now);
+      if (this.recentEvents.size > 200) {
+        const cutoff = now - this.config.dedupMs;
+        for (const [k, ts] of this.recentEvents) {
+          if (ts < cutoff) this.recentEvents.delete(k);
+        }
+      }
+    }
+    const event = {
+      event: eventName,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      sessionId: this.sessionId,
+      userId: this.userId,
+      properties: props,
+      context: this.context
+    };
+    if (this.config.debug) {
+      console.debug("[unifold/analytics] track", eventName, event);
+    }
+    this.emitter.emit(eventName, event);
+  }
+  /**
+   * Associate subsequent events with an internal Unifold user.id
+   * (`user_<ksuid>`). Pass `null` to clear. Usually called once the
+   * deposit-addresses response returns the id.
+   */
+  setUserId(userId) {
+    this.userId = userId || void 0;
+  }
+  /**
+   * Start a new analytics journey (modal open). Mints an `asess_<ksuid>` and
+   * returns it. Every {@link EventTracker.track} call until
+   * {@link EventTracker.endSession} carries it.
+   *
+   * Does not touch `userId`: the internal `user_<ksuid>` is attached separately
+   * via {@link EventTracker.setUserId} once the deposit-addresses response
+   * returns, and persists until the host replaces it.
+   */
+  startSession() {
+    this.sessionId = generatePrefixedKSUID(SESSION_PREFIX);
+    return this.sessionId;
+  }
+  /**
+   * End the current journey (modal close). Clears the session id so any stray
+   * events after close are session-less. Call this *after* the terminal
+   * `widget_closed` track call.
+   */
+  endSession() {
+    this.sessionId = void 0;
+  }
+  /** Current analytics journey id, or `undefined` when no journey is active. */
+  getSessionId() {
+    return this.sessionId;
+  }
+  /**
+   * Subscribe to a specific event or `'*'` for all events.
+   * Returns an unsubscribe function.
+   */
+  on(eventName, handler) {
+    return this.emitter.on(eventName, handler);
+  }
+  /** Remove all listeners and stop forwarding. */
+  destroy() {
+    this.emitter.removeAllListeners();
+    this.recentEvents.clear();
+  }
+  /** Enable or disable network forwarding at runtime. Custom listeners are preserved. */
+  setDisabled(disabled) {
+    if (disabled && !this.config.disabled) {
+      this.detachForwarder();
+    } else if (!disabled && this.config.disabled) {
+      this.attachForwarder();
+    }
+    this.config.disabled = disabled;
+  }
+};
+function createEventTracker(config) {
+  return new EventTracker(config);
+}
+
+// src/types.ts
+var AnalyticsEvents = {
+  /** User viewed a screen / step in the flow. */
+  SCREEN_VIEWED: "screen_viewed",
+  /** User selected a payment method. */
+  PAYMENT_METHOD_SELECTED: "payment_method_selected",
+  /**
+   * User picked an asset — the token *and* the chain it lives on. One event
+   * for both, carrying the full identity, because neither half identifies an
+   * asset alone; either dropdown changing re-fires it.
+   */
+  TOKEN_SELECTED: "token_selected",
+  /** User picked a browser wallet to connect. */
+  WALLET_SELECTED: "wallet_selected",
+  /** User picked an onramp/exchange provider (card quote, bank, exchange). */
+  PROVIDER_SELECTED: "provider_selected",
+  /**
+   * User picked what to pay with inside a provider's flow — a card, or a
+   * wallet like Apple Pay. Distinct from `payment_method_selected`, which is
+   * the funding route they chose from the deposit menu.
+   */
+  PAYMENT_METHOD_TYPE_SELECTED: "payment_method_type_selected",
+  /**
+   * User reached a step that asks them to prove something about themselves —
+   * identity details, a document, an emailed or texted code, an exchange MFA
+   * prompt. `verification_type` says which.
+   */
+  VERIFICATION_STARTED: "verification_started",
+  /** User handed over what the step asked for. A provider may still be reviewing. */
+  VERIFICATION_SUBMITTED: "verification_submitted",
+  /** The provider accepted it. */
+  VERIFICATION_COMPLETED: "verification_completed",
+  /** The provider rejected it, or the user backed out. See `failure_reason`. */
+  VERIFICATION_FAILED: "verification_failed",
+  /**
+   * User began linking an account they hold somewhere else — an exchange, a
+   * Stripe Link profile. Distinct from connecting a browser wallet, which the
+   * user already controls locally.
+   */
+  ACCOUNT_CONNECTION_STARTED: "account_connection_started",
+  /** The external account is linked and usable. */
+  ACCOUNT_CONNECTED: "account_connected",
+  /** Linking the external account failed or was abandoned. */
+  ACCOUNT_CONNECTION_FAILED: "account_connection_failed",
+  /** User began connecting a browser wallet. */
+  WALLET_CONNECTION_STARTED: "wallet_connection_started",
+  /** The wallet is connected and usable. */
+  WALLET_CONNECTED: "wallet_connected",
+  /** The connection failed, or the user declined it in their wallet. */
+  WALLET_CONNECTION_FAILED: "wallet_connection_failed",
+  /** User navigated back a step. */
+  BACK_CLICKED: "back_clicked",
+  /** User started a flow (deposit, checkout, withdraw). */
+  FLOW_STARTED: "flow_started",
+  /** User completed a flow successfully. */
+  FLOW_COMPLETED: "flow_completed",
+  /** A flow failed with an error. */
+  FLOW_FAILED: "flow_failed",
+  /** Generic UI interaction (button press, link tap). */
+  BUTTON_CLICKED: "button_clicked",
+  /** Widget/modal opened. */
+  WIDGET_OPENED: "widget_opened",
+  /** Widget/modal closed. */
+  WIDGET_CLOSED: "widget_closed"
+};
+
+export { AnalyticsEvents, Emitter, EventTracker, PACKAGE_VERSION, createEventTracker, forwardEvent, generateKSUID, generatePrefixedKSUID };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@unifold/analytics",
+  "version": "0.1.72",
+  "description": "Lightweight internal analytics for the Unifold SDK — zero external dependencies",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "prettier": "^3.2.5",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.9"
+  },
+  "keywords": [
+    "unifold",
+    "analytics",
+    "telemetry",
+    "sdk"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}