@formo/analytics 1.35.0 → 1.35.2

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

@@ -8,9 +8,52 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     private _chainState;
     private _activeNamespace?;
     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;
@@ -260,6 +303,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
@@ -296,6 +349,37 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     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;
@@ -416,6 +500,56 @@ 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;