@formo/analytics 1.38.1 → 1.39.0

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

@@ -428,8 +428,17 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * gap. Lifecycle (connect/chain/disconnect) stays store-driven: only the
      * request wrapper installs here. Double counting is prevented in the
      * wrapper via `shouldSkipRequestCapture`.
+     *
+     * `attribution` resolves, live, the name and rdns of the connector this
+     * provider was wrapped for. Request-derived events are named from the
+     * registry, which for an unannounced provider falls back to flag
+     * sniffing; recording the connector's resolver here keeps them in
+     * agreement with the hook-driven events for that connector.
      */
-    _wrapWagmiProvider(provider: EIP1193Provider, chainId?: number): boolean;
+    _wrapWagmiProvider(provider: EIP1193Provider, chainId?: number, attribution?: () => {
+        name: string;
+        rdns?: string;
+    } | undefined): boolean;
     /** INTERNAL. Chain updates for the fallback-wrapped provider. */
     _rememberWagmiProviderChain(provider: EIP1193Provider, chainId: number | undefined): void;
     registerProvider(provider: EIP1193Provider, info?: {

package/dist/cjs/src/FormoAnalytics.js

@@ -245,9 +245,12 @@ var FormoAnalytics = /** @class */ (function () {
                 this.evmEvents.trackEIP1193Provider(provider);
             }
         }
-        // Initialize Solana manager if Solana options are provided
-        if (options.solana) {
-            this.solanaManager = new SolanaManager_1.SolanaManager(this, options.solana);
+        // Solana wallets are discovered through the Wallet Standard
+        // unconditionally, the way EVM wallets are through EIP-6963: an app
+        // that never configures Solana still gets its connects. `solana: false`
+        // is the opt-out; an object adds framework-kit's store or a cluster.
+        if (options.solana !== false) {
+            this.solanaManager = new SolanaManager_1.SolanaManager(this, typeof options.solana === "object" ? options.solana : undefined);
         }
         this._currentUrl = window.location.href;
         // Seed currentAddress/currentChainId from the persisted snapshot before
@@ -1018,6 +1021,9 @@ var FormoAnalytics = /** @class */ (function () {
         // Drop anything already buffered so a pending timer/pagehide flush
         // cannot ship events after consent withdrawal.
         this.eventManager.clear();
+        // Identity is purged below; registered sessions must be re-learned
+        // on opt-in, and nothing else would retry an already-adopted one.
+        this.evmEvents.markRegisteredAdoptionsPending();
         this.reset();
         logger_1.logger.info("Successfully opted out of tracking");
     };
@@ -1268,7 +1274,9 @@ var FormoAnalytics = /** @class */ (function () {
          */
         get: function () {
             if (!this.solanaManager) {
-                this.solanaManager = new SolanaManager_1.SolanaManager(this);
+                // Only reachable after `solana: false` (or after cleanup). The host
+                // opted out of discovery, so this manager serves the store path only.
+                this.solanaManager = new SolanaManager_1.SolanaManager(this, undefined, false);
             }
             return this.solanaManager;
         },
@@ -1363,8 +1371,14 @@ var FormoAnalytics = /** @class */ (function () {
      * gap. Lifecycle (connect/chain/disconnect) stays store-driven: only the
      * request wrapper installs here. Double counting is prevented in the
      * wrapper via `shouldSkipRequestCapture`.
+     *
+     * `attribution` resolves, live, the name and rdns of the connector this
+     * provider was wrapped for. Request-derived events are named from the
+     * registry, which for an unannounced provider falls back to flag
+     * sniffing; recording the connector's resolver here keeps them in
+     * agreement with the hook-driven events for that connector.
      */
-    FormoAnalytics.prototype._wrapWagmiProvider = function (provider, chainId) {
+    FormoAnalytics.prototype._wrapWagmiProvider = function (provider, chainId, attribution) {
         if (this.isCleanedUp || !(0, provider_1.isValidProvider)(provider))
             return false;
         try {
@@ -1374,6 +1388,7 @@ var FormoAnalytics = /** @class */ (function () {
             if (!this.evmRequests.registerRequestListeners(provider)) {
                 return false;
             }
+            this.evm.rememberAttribution(provider, attribution);
             if (chainId !== undefined) {
                 this.evm.rememberChain(provider, chainId);
             }

package/dist/cjs/src/FormoAnalyticsProvider.js

@@ -72,6 +72,18 @@ var defaultContext = {
     hasOptedOutTracking: function () { return false; },
 };
 exports.FormoAnalyticsContext = (0, react_1.createContext)(defaultContext);
+var optionObjectIds = new WeakMap();
+var nextOptionObjectId = 1;
+var optionObjectId = function (value) {
+    if (!value)
+        return undefined;
+    var id = optionObjectIds.get(value);
+    if (id === undefined) {
+        id = nextOptionObjectId++;
+        optionObjectIds.set(value, id);
+    }
+    return id;
+};
 /**
  * A stable key over the serializable parts of Options. The provider effect
  * re-initialises the SDK when this key changes; anything that alters SDK
@@ -95,6 +107,14 @@ var computeOptionsKey = function (options) {
         logger: options.logger,
         referral: options.referral,
         evm: options.evm,
+        // `solana` is a boolean or an options object. A store is a live event
+        // source, so replacing it must reinitialize the SDK even when both the
+        // old and new options contain a store.
+        solana: typeof options.solana === "object" ? undefined : options.solana,
+        solanaStoreId: typeof options.solana === "object"
+            ? optionObjectId(options.solana.store)
+            : undefined,
+        solanaCluster: typeof options.solana === "object" ? options.solana.cluster : undefined,
         // For complex objects, just track their presence, not their content
         hasProvider: !!options.provider,
         hasWagmi: !!options.wagmi,

package/dist/cjs/src/evm/EvmEventTracker.d.ts

@@ -52,10 +52,91 @@ export declare class EvmEventTracker {
      * Announcement-driven cleanup must not touch them: they are never in an
      * announcement list, so "missing from the announcement" is their normal
      * state, not evidence of removal. A Set rather than a WeakSet because
-     * suppressed adoptions retry from it; the registry holds these providers
-     * strongly anyway, and untrack removes them.
+     * the corrected-detect pass iterates it; the registry's detail list
+     * holds these providers strongly for the instance's life anyway.
      */
     private externallyRegistered;
+    /**
+     * Registered providers whose session this SDK has NOT yet learned.
+     *
+     * Only these are retried on page hits and opt-in. Re-running adoption for
+     * every registered provider looked idempotent but was not: adoption is
+     * the same path a live `accountsChanged` takes, and that path treats a
+     * provider with a different address from the active one as a wallet
+     * switch. With two registered providers, or one registered next to a
+     * discovered wallet, every page hit emitted a disconnect and a connect
+     * that no user action caused.
+     *
+     * A provider enters at registration (it may have no session yet, or be
+     * refused because tracking is suppressed), again whenever a handler
+     * refuses its signal while suppressed (noted on entry AND at the
+     * suppressed commit, since the handlers gate on the active provider and
+     * re-check suppression after an await), and again for all of them when
+     * an opt-out purges identity. It leaves the first time a handler commits
+     * its session unsuppressed, or when it is untracked. Retrying reads the
+     * provider's SYNCHRONOUS accounts only - no RPC - so a registered
+     * provider whose session never fires `accountsChanged` (a wallet that
+     * signals `connect` alone while `autocapture.connect` is off, which
+     * installs a chain-only observer) is still adopted on the next hit. "No
+     * RPC" holds for the pending provider itself; the handler's switch
+     * arbitration may still ask the ACTIVE provider for its accounts, as it
+     * does for any live signal.
+     *
+     * Replay goes through the accounts handler, which has live wallet-switch
+     * semantics: a different provider with a different address is a switch.
+     * So a pending provider is replayed only while no OTHER wallet is active
+     * and known - it waits, at no cost, until that wallet is gone - unless
+     * its own signal was refused (`latestRefused`): then the replay does
+     * exactly what the live signal would have done, switch included.
+     */
+    private pendingAdoptions;
+    /**
+     * The pending provider whose own live signal was refused while
+     * suppressed, LATEST only. The SDK follows one active wallet and the
+     * newest signal wins, so replaying only the last refused signal reaches
+     * the state the live signals would have reached, without the switches
+     * in between; an earlier refused provider stays pending, unprivileged.
+     */
+    private latestRefused?;
+    private dropRefusal;
+    /**
+     * An opt-out purges wallet identity. Every registered session is then
+     * unknown again (pending; no refusal is ADDED, so the opt-in replay of a
+     * merely connected wallet does not switch, while a refusal already
+     * standing from an excluded route keeps its meaning), and the
+     * opt-in retry must re-learn all of them: with the active wallet's
+     * address gone, the accounts handler cannot even tell a second wallet's
+     * accounts apart from the active one's, and would ignore them.
+     */
+    markRegisteredAdoptionsPending(): void;
+    /**
+     * Remember a registered provider's signal that suppression refuses.
+     *
+     * Replay privilege (`latestRefused`) goes only to a provider whose
+     * session the replay can actually read - synchronous accounts - so an
+     * accountless `connect` (a chain-only observation, or a session still
+     * pairing) cannot displace an earlier refusal that is adoptable.
+     */
+    private noteRefusalIfSuppressed;
+    /**
+     * Registered providers whose session ended and have not signalled a
+     * new one. Some providers keep stale synchronous `accounts` after a
+     * disconnect; replaying those would re-install a session that is over.
+     * Any later session signal (connect, accountsChanged) lifts this.
+     */
+    private awaitingNewSession;
+    /** A handler has learned this provider's session; nothing is pending. */
+    private settleAdoption;
+    /**
+     * A registered provider's session has ended. Its NEXT session is not
+     * yet learned, and may announce itself in a way no handler adopts (a
+     * `connect` alone while `autocapture.connect` is off installs a
+     * chain-only observer), so it is pending again for the page-hit retry.
+     */
+    private reopenAdoption;
+    /** One retry scan at a time; a call during a scan queues one more. */
+    private retryInFlight;
+    private retryRequested;
     /**
      * The connect this SDK has already reported for a provider.
      *
@@ -74,6 +155,11 @@ export declare class EvmEventTracker {
     constructor(wallet: WalletStateStore, registry: EvmProviderRegistry, deps: EvmEventTrackerDeps);
     /** Stop listening for wallet announcements. Called from SDK teardown. */
     cleanup(): void;
+    /** Set by `cleanup()`; every awaited continuation checks it. */
+    private disposed;
+    /** Bumped when a registered provider's session ends. See reopenAdoption. */
+    private sessionGenerations;
+    private sessionGeneration;
     /** Drop a provider's reported connect. Called when it stops being active. */
     forgetAnnouncedConnect(provider: EIP1193Provider): void;
     /**
@@ -109,14 +195,19 @@ export declare class EvmEventTracker {
      */
     adoptExternalProvider(detail: EIP6963ProviderDetail): boolean;
     /**
-     * Re-run session adoption for every registered external provider.
+     * Finish what registration could not.
+     *
+     * A registered provider's session may not have existed at registration,
+     * or its adoption was refused because tracking was suppressed (opt-out,
+     * excluded route) - and an existing session may never emit another
+     * accountsChanged, so nothing else would ever retry. Called when
+     * suppression can have ended (opt-in, page navigation).
      *
-     * Registration while tracking was suppressed (opt-out, excluded route)
-     * reached the adoption path and was refused - and a provider whose
-     * session already exists may never emit another accountsChanged, so
-     * nothing would ever retry. Called when suppression can have ended
-     * (opt-in, page navigation). Idempotent: an already-adopted wallet is
-     * deduplicated by the same state and markers as any repeated signal.
+     * Adoption is retried ONLY for providers not yet adopted
+     * (`pendingAdoptions`), only from their synchronous accounts, and only
+     * once suppression has actually ended. The corrected-detect pass below
+     * runs for every registered provider: it is deduplicated per session by
+     * rdns, so repeating it is free.
      */
     retryExternalAdoptions(): void;
     private registerAccountsChangedListener;