@formo/analytics 1.38.0 → 1.38.2

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

@@ -402,9 +402,9 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      *
      * With several live SDK instances (multi write-key pages) registering
      * the SAME provider, request-derived events (signatures, transactions)
-     * go to the most recently registered live instance - the same
-     * single-observer semantics discovery has always had for the request
-     * wrapper. Lifecycle events (connect, chain, disconnect) reach every
+     * go to the most recently CREATED live instance, regardless of the
+     * order registrations happen to land in - the same single-observer
+     * semantics discovery has always had for the request wrapper. Lifecycle events (connect, chain, disconnect) reach every
      * instance. Fanning request observations out to all instances is a
      * separate feature.
      *
@@ -428,8 +428,19 @@ 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): void;
+    _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?: {
         name?: string;
         rdns?: string;

package/dist/cjs/src/FormoAnalytics.js

@@ -1018,6 +1018,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");
     };
@@ -1337,9 +1340,9 @@ var FormoAnalytics = /** @class */ (function () {
      *
      * With several live SDK instances (multi write-key pages) registering
      * the SAME provider, request-derived events (signatures, transactions)
-     * go to the most recently registered live instance - the same
-     * single-observer semantics discovery has always had for the request
-     * wrapper. Lifecycle events (connect, chain, disconnect) reach every
+     * go to the most recently CREATED live instance, regardless of the
+     * order registrations happen to land in - the same single-observer
+     * semantics discovery has always had for the request wrapper. Lifecycle events (connect, chain, disconnect) reach every
      * instance. Fanning request observations out to all instances is a
      * separate feature.
      *
@@ -1363,15 +1366,43 @@ 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) {
+    FormoAnalytics.prototype._wrapWagmiProvider = function (provider, chainId, attribution) {
         if (this.isCleanedUp || !(0, provider_1.isValidProvider)(provider))
-            return;
+            return false;
         try {
-            this.evmRequests.registerRequestListeners(provider);
+            // The tracker reports refusals (frozen provider, unrebindable
+            // wrapper) by returning false rather than throwing; treat those as
+            // failures too so the caller can retry later.
+            if (!this.evmRequests.registerRequestListeners(provider)) {
+                return false;
+            }
+            this.evm.rememberAttribution(provider, attribution);
+            if (chainId !== undefined) {
+                this.evm.rememberChain(provider, chainId);
+            }
+            return true;
         }
         catch (e) {
             logger_1.logger.warn("Failed to wrap wagmi provider for hybrid capture", e);
+            return false;
+        }
+    };
+    /** INTERNAL. Chain updates for the fallback-wrapped provider. */
+    FormoAnalytics.prototype._rememberWagmiProviderChain = function (provider, chainId) {
+        if (this.isCleanedUp)
+            return;
+        try {
+            this.evm.rememberChain(provider, chainId);
+        }
+        catch (_a) {
+            /* bookkeeping only */
         }
     };
     FormoAnalytics.prototype.registerProvider = function (provider, info) {

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

@@ -7,6 +7,14 @@ export interface FormoAnalyticsProviderProps {
     children: ReactNode;
 }
 export declare const FormoAnalyticsContext: import("react").Context<IFormoAnalytics>;
+/**
+ * A stable key over the serializable parts of Options. The provider effect
+ * re-initialises the SDK when this key changes; anything that alters SDK
+ * behaviour must be represented here, or a runtime change to it is silently
+ * ignored. Complex objects are tracked by presence, plus the flags that
+ * change what the SDK does with them.
+ */
+export declare const computeOptionsKey: (options?: Options) => string;
 export declare const FormoAnalyticsProvider: FC<FormoAnalyticsProviderProps>;
 export declare const useFormo: () => IFormoAnalytics;
 //# sourceMappingURL=FormoAnalyticsProvider.d.ts.map

package/dist/cjs/src/FormoAnalyticsProvider.js

@@ -47,7 +47,7 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
     }
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useFormo = exports.FormoAnalyticsProvider = exports.FormoAnalyticsContext = void 0;
+exports.useFormo = exports.FormoAnalyticsProvider = exports.computeOptionsKey = exports.FormoAnalyticsContext = void 0;
 var jsx_runtime_1 = require("react/jsx-runtime");
 var react_1 = require("react");
 var FormoAnalytics_1 = require("./FormoAnalytics");
@@ -72,6 +72,45 @@ var defaultContext = {
     hasOptedOutTracking: function () { return false; },
 };
 exports.FormoAnalyticsContext = (0, react_1.createContext)(defaultContext);
+/**
+ * A stable key over the serializable parts of Options. The provider effect
+ * re-initialises the SDK when this key changes; anything that alters SDK
+ * behaviour must be represented here, or a runtime change to it is silently
+ * ignored. Complex objects are tracked by presence, plus the flags that
+ * change what the SDK does with them.
+ */
+var computeOptionsKey = function (options) {
+    var _a;
+    if (!options)
+        return 'undefined';
+    var serializableOptions = {
+        tracking: options.tracking,
+        autocapture: options.autocapture,
+        crossSubdomainCookies: options.crossSubdomainCookies,
+        apiHost: options.apiHost,
+        flushAt: options.flushAt,
+        flushInterval: options.flushInterval,
+        retryCount: options.retryCount,
+        maxQueueSize: options.maxQueueSize,
+        logger: options.logger,
+        referral: options.referral,
+        evm: options.evm,
+        // For complex objects, just track their presence, not their content
+        hasProvider: !!options.provider,
+        hasWagmi: !!options.wagmi,
+        wagmiEip1193Fallback: !!((_a = options.wagmi) === null || _a === void 0 ? void 0 : _a.eip1193Fallback),
+        hasReady: !!options.ready,
+    };
+    try {
+        return JSON.stringify(serializableOptions);
+    }
+    catch (error) {
+        // Fallback to timestamp if serialization fails
+        logger_1.logger.warn('Failed to serialize options, using timestamp', error);
+        return Date.now().toString();
+    }
+};
+exports.computeOptionsKey = computeOptionsKey;
 var FormoAnalyticsProvider = function (props) {
     var writeKey = props.writeKey, _a = props.disabled, disabled = _a === void 0 ? false : _a, children = props.children;
     // Keep the app running without analytics if no Write Key is provided or disabled
@@ -91,37 +130,7 @@ var InitializedAnalytics = function (_a) {
     var _b = (0, react_1.useState)(defaultContext), sdk = _b[0], setSdk = _b[1];
     var sdkRef = (0, react_1.useRef)(defaultContext);
     (0, storage_1.initStorageManager)(writeKey);
-    // Create a stable key from options that ignores complex objects and functions
-    // We only care about serializable config values that would affect SDK behavior
-    var optionsKey = (0, react_1.useMemo)(function () {
-        if (!options)
-            return 'undefined';
-        // Extract only the serializable parts of options
-        var serializableOptions = {
-            tracking: options.tracking,
-            autocapture: options.autocapture,
-            crossSubdomainCookies: options.crossSubdomainCookies,
-            apiHost: options.apiHost,
-            flushAt: options.flushAt,
-            flushInterval: options.flushInterval,
-            retryCount: options.retryCount,
-            maxQueueSize: options.maxQueueSize,
-            logger: options.logger,
-            referral: options.referral,
-            // For complex objects, just track their presence, not their content
-            hasProvider: !!options.provider,
-            hasWagmi: !!options.wagmi,
-            hasReady: !!options.ready,
-        };
-        try {
-            return JSON.stringify(serializableOptions);
-        }
-        catch (error) {
-            // Fallback to timestamp if serialization fails
-            logger_1.logger.warn('Failed to serialize options, using timestamp', error);
-            return Date.now().toString();
-        }
-    }, [options]);
+    var optionsKey = (0, react_1.useMemo)(function () { return (0, exports.computeOptionsKey)(options); }, [options]);
     (0, react_1.useEffect)(function () {
         var isCleanedUp = false;
         var initialize = function () { return __awaiter(void 0, void 0, void 0, function () {

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;