@formo/analytics 1.35.2 → 1.37.0

package/dist/esm/src/FormoAnalytics.d.ts

@@ -1,79 +1,31 @@
 import { EIP6963ProviderDetail } from "mipd";
 import { Address, ChainID, Config, EIP1193Provider, IFormoAnalytics, IFormoEventContext, IFormoEventProperties, Options, SignatureStatus, TransactionStatus } from "./types";
+import { AutocaptureEventType } from "./tracking/TrackingPolicy";
 import { SolanaManager } from "./solana/SolanaManager";
 import type { PrivyUser } from "./privy";
+/**
+ * Constants for provider switching reasons
+ */
 export declare class FormoAnalytics implements IFormoAnalytics {
     readonly writeKey: string;
     options: Options;
-    private _chainState;
-    private _activeNamespace?;
+    /** Wallet identity, chain state and the active-wallet cookie. */
+    private wallet;
     private get _provider();
-    /**
-     * Drop a provider's reported-connect record when it stops being active.
-     *
-     * The active provider is displaced from several places, and not all of them
-     * go through the `_provider` setter: `setChainState()` writes
-     * `_chainState.evm.provider` directly and `clearChainState()` replaces the
-     * whole namespace. Guarding only the setter left A's record alive across a
-     * real A-to-B switch, so returning to A was suppressed.
-     */
-    private forgetConnectRecord;
     private set _provider(value);
     private get _evmAddress();
     private get _evmChainId();
-    /**
-     * Last known chain per tracked provider, fed by `chainChanged` / `connect`
-     * and by a one-off probe at tracking time. Read synchronously when labelling
-     * an autocaptured event, so the wallet's request transport is never used for
-     * analytics. Weak so an untracked provider can be collected.
-     */
-    /**
-     * The connect this SDK has actually REPORTED for a provider.
-     *
-     * Deduplicating on "is an address known" was wrong in both directions.
-     * `onConnected` and `onAccountsChanged` both observe one connection, so
-     * something has to stop them double-reporting - but an address can be
-     * present without a connect ever having been sent: restored from the
-     * active-wallet cookie, or reported with an unresolved chain and then
-     * refused by `tracking.excludeChains`. Suppressing on address presence lost
-     * the connect entirely in those cases.
-     *
-     * Records what was reported, so a later event can be recognised as a
-     * genuine improvement on it rather than a duplicate.
-     */
     private _announcedConnect;
-    private _providerChainIds;
-    /**
-     * Bumped on every chain observation, PER PROVIDER. An `eth_chainId` answer
-     * that resolves after a newer observation for the same provider must not
-     * overwrite it.
-     *
-     * Deliberately per provider, not per SDK instance: a global counter meant
-     * any activity on wallet B discarded a perfectly valid in-flight answer for
-     * wallet A, leaving A at chain 0 - and, since an unresolved chain fails
-     * closed, dropping all of A's events whenever `excludeChains` is set.
-     */
-    private _providerChainGenerations;
-    private _providerListenersMap;
     private session;
     private eventManager;
-    /**
-     * EIP-6963 provider details discovered through the browser
-     * This array contains all available providers with their metadata
-     */
-    private _providers;
-    /**
-     * Set of providers that have been tracked with event listeners
-     * This is separate from _providers because:
-     * - _providers contains all discovered providers (EIP-6963)
-     * - _trackedProviders contains only providers that have been set up with listeners
-     * - A provider can be discovered but not yet tracked (e.g., during initialization)
-     * - A provider can be tracked but later removed from discovery
-     */
-    private _trackedProviders;
-    private _injectedProviderDetail?;
-    private _processingAccountsChanged;
-    private _seenProviders;
+    /** Which EVM wallets exist, and what is known about each. */
+    private evm;
+    /** Which providers to watch, and what their events mean. */
+    private evmEvents;
+    /** Autocapture for signatures and transactions. */
+    private evmRequests;
+    /** Every "may we track this?" rule. See src/tracking/TrackingPolicy.ts. */
+    private trackingPolicy;
     /**
      * Wagmi event handler for tracking wallet events via Wagmi v2
      * Only initialized when options.wagmi is provided
@@ -103,15 +55,25 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     private _onLocationChangeListener?;
     private _pageHooksDisposed;
     config: Config;
-    currentChainId?: ChainID;
-    currentAddress?: Address;
-    currentUserId?: string;
     /**
-     * Helper method to check if a provider is different from the currently active one
-     * @param provider The provider to check
-     * @returns true if there's a provider mismatch, false otherwise
+     * The wallet later events are attributed to, derived from whichever
+     * namespace last claimed the slot. Read by the wagmi and Privy
+     * integrations; the store is the only writer.
      */
-    private isProviderMismatch;
+    get currentAddress(): Address | undefined;
+    get currentChainId(): ChainID | undefined;
+    /**
+     * These stay writable.
+     *
+     * Both were public mutable fields, so a consumer assigning one is using a
+     * documented public API. Getter-only replacements would break that
+     * silently: TypeScript rejects the assignment, and plain JavaScript throws
+     * on an accessor with no setter. The writes forward into the store, which
+     * keeps a single owner without turning a refactor into a breaking change.
+     */
+    set currentAddress(value: Address | undefined);
+    set currentChainId(value: ChainID | undefined);
+    currentUserId?: string;
     private constructor();
     static init(writeKey: string, options?: Options): Promise<FormoAnalytics>;
     /**
@@ -161,6 +123,45 @@ export declare class FormoAnalytics implements IFormoAnalytics {
         chainId?: ChainID;
         address?: Address;
     }, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
+    /** @see WalletStateStore.set */
+    private setChainState;
+    /** @see WalletStateStore.clear */
+    private clearChainState;
+    /**
+     * Record validated wallet/chain state WITHOUT emitting an event.
+     *
+     * Integrations must call this on every connect / chain change / disconnect,
+     * even when the matching autocapture event is disabled, or the exclusion
+     * gate (which keys off the central chain, not the event payload) can be
+     * bypassed. Stays on the class because integrations bind to it.
+     * @see WalletStateStore.syncWalletState
+     */
+    syncWalletState(params: {
+        chainId?: ChainID;
+        address?: Address;
+    }): void;
+    /** @see WalletStateStore.clearProvider */
+    private clearActiveProvider;
+    /** @see WalletStateStore.backfill */
+    private backfillActiveWallet;
+    /** @see WalletStateStore.clearStaleEvmWalletOnSwitchWhileSuppressed */
+    private clearStaleEvmWalletOnSwitchWhileSuppressed;
+    /** @see EvmProviderRegistry.addListener */
+    private addProviderListener;
+    /** @see EvmProviderRegistry.removeListeners */
+    private removeProviderListeners;
+    /** @see EvmProviderRegistry.infoFor */
+    private getProviderInfo;
+    /** @see EvmProviderRegistry.isWrapped */
+    private isProviderAlreadyWrapped;
+    /** @see EvmProviderRegistry.resolveChainId */
+    private resolveChainIdForProvider;
+    /** @see EvmProviderRegistry.rememberChain */
+    private rememberProviderChain;
+    /** @see EvmProviderRegistry.addressOf */
+    private getAddress;
+    /** @see EvmProviderRegistry.accountsOf */
+    private getAccounts;
     /**
      * Emits a chain network change event.
      * @param {ChainID} params.chainId
@@ -325,65 +326,6 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @returns {boolean} True if the user has opted out
      */
     hasOptedOutTracking(): boolean;
-    /**
-     * Track an EIP-1193 provider by wrapping its request method and adding event listeners
-     * Note: This is only used in non-Wagmi mode. When Wagmi is enabled, all tracking
-     * happens through Wagmi's connector system instead of EIP-1193/EIP-6963.
-     * @param provider The EIP-1193 provider to track
-     */
-    private trackEIP1193Provider;
-    private trackProviders;
-    private addProviderListener;
-    private registerAccountsChangedListener;
-    private onAccountsChanged;
-    /**
-     * Handles changes to the accounts of a given EIP-1193 provider.
-     *
-     * @param provider - The EIP-1193 provider whose accounts have changed.
-     * @param accounts - The new array of account addresses. An empty array indicates a disconnect.
-     * @returns A promise that resolves when the account change has been processed.
-     *
-     * If the accounts array is empty and the provider is the active provider, this method triggers
-     * a disconnect flow. Otherwise, it updates the state to reflect the new accounts as needed.
-     */
-    private _handleAccountsChanged;
-    private registerChainChangedListener;
-    private onChainChanged;
-    /**
-     * Record a provider's chain from its `connect` event, and nothing else.
-     *
-     * Used when connect autocapture is off. `connect` carries `chainId` in its
-     * payload, so this needs no RPC - unlike the full handler, which resolves
-     * the account.
-     */
-    private registerConnectChainObserver;
-    /**
-     * Whether a connect for this wallet still needs reporting.
-     *
-     * True when nothing has been reported for this provider, or when the account
-     * changed. A wallet already reported is not reported again.
-     *
-     * Deliberately does NOT re-report to correct a chain. When `accountsChanged`
-     * wins the race on a provider that exposes no synchronous `chainId`, the
-     * connect carries 0 - honestly, since the chain is unknown at that instant -
-     * and the `connect` payload that follows knows the real one. Emitting again
-     * to relabel would mean two connects for one connection, which is the bug
-     * this whole path exists to prevent. That payload still corrects
-     * `currentChainId`, so everything after it is attributed properly.
-     */
-    private shouldReportConnect;
-    /**
-     * Record a connect as reported - but only if it will actually be sent.
-     *
-     * `connect()` passes through `shouldTrack()`, which refuses an unresolvable
-     * chain when `tracking.excludeChains` is configured. Marking a refused event
-     * as reported would suppress the authoritative one that follows.
-     */
-    private markConnectReported;
-    private registerConnectListener;
-    private registerDisconnectListener;
-    private onConnected;
-    private registerRequestListeners;
     private onLocationChange;
     private trackPageHits;
     /**
@@ -397,94 +339,26 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     /**
      * Visitor-level tracking suppression.
      *
-     * Returns true when the SDK must not persist any identity/session/chain
-     * state or send any events for this visitor - i.e. an explicit opt-out or a
-     * jurisdiction/timezone exclusion. Public entry points that write state
-     * before reaching the `shouldTrack()` event gate (identify/connect/detect)
-     * check this first so suppressed visitors leave no cookies or session state.
-     * @returns {boolean} True if all tracking and persistence must be suppressed
+     * True when the SDK must not persist identity/session/chain state or send
+     * events for this visitor. Public entry points that write state before
+     * reaching the `shouldTrack()` gate (identify / connect / detect) check this
+     * first, so a suppressed visitor leaves no cookies or session state.
+     *
+     * The rule lives in `TrackingPolicy`; this stays on the class because it is
+     * part of the surface integrations bind to.
      * @internal Also read by `identifyPrivyUser` (via a structural cast) so the
      * Privy sync skips chain reconciliation and emission for suppressed visitors.
      */
     isTrackingSuppressed(): boolean;
-    /**
-     * Whether the current chain id is in `tracking.excludeChains`.
-     *
-     * Split out from `shouldTrack()` so `identify()` can check it *before*
-     * mutating identity state. `trackEvent()` drops an excluded event silently
-     * and returns void, but `identify()` marks the wallet as identified first, so
-     * without this guard an identify on an excluded chain is dedup-marked and
-     * then discarded, and the wallet never re-emits for the rest of the session
-     * even after switching to an allowed chain. On the Privy path that loses the
-     * user's whole cluster at once rather than a single wallet.
-     *
-     * Mirrors the chain rule in `shouldTrack()`: only applies when `tracking` is
-     * an options object with `excludeChains` set, and only once a chain id is
-     * known.
-     */
-    private isCurrentChainExcluded;
-    /**
-     * Whether the current environment is excluded from tracking - the visitor's
-     * timezone, the current hostname, or the current pathname matches a
-     * configured exclusion.
-     *
-     * Timezone is visitor/session-level (stable for the session); host/path are
-     * current-page-level and transient - if a SPA navigates to an allowed path,
-     * tracking resumes for future actions. Used as the "do not write identity or
-     * send events" gate at every entry point that would persist state before the
-     * `shouldTrack()` event gate.
-     * @returns {boolean} True if the current environment is excluded
-     */
-    private isCurrentEnvironmentExcluded;
-    /**
-     * Whether the current hostname matches a configured `tracking.excludeHosts`
-     * entry (exact match). Current-page-level - see isCurrentEnvironmentExcluded.
-     * @returns {boolean} True if the current hostname is excluded
-     */
-    private isHostExcluded;
-    /**
-     * Whether the current pathname matches a configured `tracking.excludePaths`
-     * entry (exact match). Current-page-level - see isCurrentEnvironmentExcluded.
-     * @returns {boolean} True if the current pathname is excluded
-     */
-    private isPathExcluded;
-    /**
-     * Whether the current call is in a visitor-level suppression state - opt-out
-     * or excluded timezone - for which any persisted identity cookie should be
-     * actively purged (not merely skipped). Host/path exclusions are
-     * deliberately excluded here: they are transient current-page states, so a
-     * cookie legitimately written on an allowed page must survive a visit to an
-     * excluded route.
-     * @returns {boolean} True if persisted identity must be purged
-     */
-    private isPersistedIdentityPurgeRequired;
-    /**
-     * Whether the visitor's browser-resolved timezone matches a configured
-     * `tracking.excludeTimezones` entry (case-insensitive). Client-side and
-     * best-effort - see TrackingOptions.excludeTimezones.
-     * @returns {boolean} True if the current timezone is excluded
-     */
-    private isTimezoneExcluded;
-    /**
-     * Determines if tracking should be enabled based on configuration and consent
-     * @returns {boolean} True if tracking should be enabled
-     */
+    /** @see TrackingPolicy.shouldTrack */
     private shouldTrack;
     /**
      * Check if a specific wallet event type is enabled for autocapture
      * @param eventType The wallet event type to check
      * @returns {boolean} True if the event type should be autocaptured
      */
-    isAutocaptureEnabled(eventType: "connect" | "disconnect" | "signature" | "transaction" | "chain"): boolean;
-    /**
-     * Get provider information for a given provider
-     * @param provider The provider to get info for
-     * @returns Provider information
-     */
-    private getProviderInfo;
-    private getProviders;
+    isAutocaptureEnabled(eventType: AutocaptureEventType): boolean;
     get providers(): readonly EIP6963ProviderDetail[];
-    private detectWallets;
     get provider(): EIP1193Provider | undefined;
     /**
      * Access the Solana integration manager.
@@ -498,84 +372,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * ```
      */
     get solana(): SolanaManager;
-    private getAddress;
-    private getAccounts;
-    /**
-     * Resolve the chain an autocaptured request actually ran on.
-     *
-     * `_evmChainId` is maintained by `chainChanged` from whichever provider is
-     * currently active. When a request arrives from a *different* tracked
-     * provider - which happens whenever a visitor has two wallets installed -
-     * that cached value describes the wrong wallet, and tagging the event with
-     * it silently mis-attributes the chain.
-     *
-     * Answered entirely from a per-provider snapshot. This is deliberately
-     * SYNCHRONOUS and never issues an RPC.
-     *
-     * An earlier version called `eth_chainId` on the signing provider and
-     * time-boxed it with `Promise.race`. That is not safe: the race abandons the
-     * SDK's promise but cannot cancel the provider's request. On a transport
-     * that serializes - WalletConnect's relay socket, the very case this path
-     * exists to serve - an abandoned lookup stays at the head of the wallet's
-     * queue, and every later RPC the dapp makes queues behind it until reload.
-     * Mislabelling a chain is a reporting defect; wedging the user's wallet is
-     * not acceptable to avoid one.
-     *
-     * When nothing is known, this reports 0 ("unknown") rather than guessing
-     * with the active provider's chain, which is known-wrong for another wallet.
-     */
-    private resolveChainIdForProvider;
-    /**
-     * Record a provider's chain. Fed by `chainChanged` and `connect`, and by the
-     * one-off probe at tracking time - never from inside a user request.
-     */
-    private rememberProviderChain;
-    /** Advance and return this provider's chain-observation generation. */
-    private bumpProviderChainGeneration;
-    /**
-     * Seed a provider's chain from whatever it already exposes synchronously.
-     *
-     * Most EIP-1193 implementations carry a `chainId` property (MetaMask,
-     * WalletConnect, Coinbase). Reading it costs nothing and cannot block.
-     *
-     * There is deliberately no RPC fallback. An earlier version probed with
-     * `eth_chainId` when a provider was first tracked, on the theory that
-     * tracking time is off the user's critical path. It is not: a serialized
-     * transport has ONE queue, so a stalled probe sits in front of every later
-     * signature and transaction the dapp makes. It could also land out of order
-     * - a slow probe response overwriting a newer `chainChanged` - and relabel
-     * events onto a chain the wallet had already left.
-     *
-     * A provider that exposes nothing stays unknown until it emits
-     * `chainChanged` or `connect`, and unknown is reported honestly as 0.
-     */
-    private seedProviderChainFromState;
     private getCurrentChainId;
-    private buildSignatureEventPayload;
-    private buildTransactionEventPayload;
-    /**
-     * Persist an EVM address discovered through autocapture (signature / transaction)
-     * as the current EVM address when none is currently set. This lets subsequent
-     * track()/page() calls carry the address even when the underlying wallet never
-     * fires an EIP-1193 `accountsChanged` event (embedded wallets, smart accounts,
-     * social-login wrappers). If `accountsChanged` later fires it overwrites this
-     * value in the normal way; existing connections are never clobbered.
-     */
-    private backfillActiveWallet;
-    /**
-     * Apply an EVM autocapture connect/switch while tracking is suppressed
-     * (opt-out / timezone / excluded host or path): never LEARN the wallet, but
-     * if it is a switch away from an already-learned EVM wallet, drop the stale
-     * one (which also clears the active-wallet cookie) so it can't attach to a
-     * later allowed-page event.
-     */
-    private clearStaleEvmWalletOnSwitchWhileSuppressed;
-    /**
-     * Polls for transaction receipt and emits tx.status = CONFIRMED or REVERTED.
-     */
-    private pollTransactionReceipt;
-    private removeProviderListeners;
-    private untrackProvider;
     getTrackedProvidersCount(): number;
     /**
      * Get current provider state for debugging
@@ -587,86 +384,5 @@ export declare class FormoAnalytics implements IFormoAnalytics {
         seenProviders: number;
         activeProvider: boolean;
     };
-    /**
-     * Clean up providers that are no longer available
-     * This helps maintain consistent state and prevents memory leaks
-     */
-    private cleanupUnavailableProviders;
-    /**
-     * Helper method to check if a provider is already wrapped
-     * @param provider The provider to check
-     * @param currentRequest The current request function
-     * @returns true if the provider is already wrapped
-     */
-    private isProviderAlreadyWrapped;
-    /**
-     * Handle provider mismatch by switching to the new provider and invalidating old tokens
-     * @param provider The new provider to switch to
-     */
-    private handleProviderMismatch;
-    /**
-     * Determine which namespace a chainId belongs to.
-     */
-    private getNamespace;
-    /**
-     * Update per-chain state and sync the derived currentAddress/currentChainId.
-     * Accepts either a namespace string ('evm'/'solana') or a chainId number
-     * to resolve the namespace automatically. When a chainId number is passed,
-     * it is also stored as the namespace's chainId (unless explicitly overridden
-     * in the update object).
-     */
-    private setChainState;
-    /**
-     * Clear per-chain state for a given namespace (or chainId) and sync derived state.
-     */
-    private clearChainState;
-    /**
-     * Sync validated wallet/chain state into the SDK's central state
-     * WITHOUT emitting an event.
-     *
-     * Integrations (e.g. the wagmi handler) must call this on every
-     * connect / chain-change / disconnect - even when the corresponding
-     * autocapture event is disabled. Otherwise `currentChainId` stays
-     * stale/undefined and `shouldTrack()`'s `tracking.excludeChains`
-     * check (which keys off `currentChainId`, not the event payload) can
-     * be bypassed, letting wallet activity on an excluded chain still be
-     * collected.
-     *
-     * - valid `address` present → record per-chain + derived state
-     * - `address` absent → clear chain state (disconnect)
-     */
-    syncWalletState(params: {
-        chainId?: ChainID;
-        address?: Address;
-    }): void;
-    /**
-     * Synchronize currentAddress/currentChainId from the active namespace.
-     * Last-connected-chain-wins: _activeNamespace takes precedence.
-     */
-    private syncDerivedState;
-    /**
-     * Persist (or clear) the current wallet snapshot in a cookie so that the
-     * SDK can repopulate `currentAddress`/`currentChainId` at init on the next
-     * page load - closing the gap between page-show and wagmi/EIP-1193
-     * reconnection during which track()/page() events would otherwise ship
-     * with an empty address.
-     */
-    private persistActiveWallet;
-    /**
-     * Seed `currentAddress`/`currentChainId` from the persisted snapshot, if
-     * any. Called once during construction before the first page hit fires.
-     */
-    private loadActiveWallet;
-    /**
-     * Helper method to clear the active provider state
-     * Centralizes provider clearing logic for consistency
-     */
-    private clearActiveProvider;
-    /**
-     * Helper method to safely add a provider detail to _providers array, ensuring no duplicates
-     * @param detail The provider detail to add
-     * @returns true if the provider was added, false if it was already present
-     */
-    private safeAddProviderDetail;
 }
 //# sourceMappingURL=FormoAnalytics.d.ts.map