@formo/analytics 1.35.1 → 1.36.0

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

@@ -1,36 +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();
     private set _provider(value);
     private get _evmAddress();
     private get _evmChainId();
-    private _providerListenersMap;
+    private _announcedConnect;
     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
@@ -60,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>;
     /**
@@ -118,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
@@ -260,6 +304,16 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * Opt out of tracking.
      * @returns {void}
      */
+    /**
+     * Whether an event carrying this chain would currently be sent.
+     *
+     * Exposed for integrations that keep their own "already reported" state.
+     * `syncWalletState()` can accept a wallet that `trackEvent()` then drops -
+     * `tracking: false`, or a chain in `excludeChains` - and an integration that
+     * marked it as reported would stay silent about that wallet even after the
+     * configuration changed to allow it.
+     */
+    willTrackEvent(chainId?: ChainID): boolean;
     optOutTracking(): void;
     /**
      * Opt back into tracking after previously opting out. This will re-enable analytics tracking
@@ -272,34 +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;
-    private registerConnectListener;
-    private registerDisconnectListener;
-    private onConnected;
-    private registerRequestListeners;
     private onLocationChange;
     private trackPageHits;
     /**
@@ -313,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.
@@ -414,34 +372,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * ```
      */
     get solana(): SolanaManager;
-    private getAddress;
-    private getAccounts;
     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
@@ -453,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