@formo/analytics 1.29.0 → 1.30.0

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

@@ -54,6 +54,10 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     private crossSubdomainCookies;
     /** In-memory URL used to deduplicate SPA pageview events. */
     private _currentUrl;
+    /** Page-hit hooks installed in trackPageHits() so cleanup() can undo them. */
+    private _onPopStateListener?;
+    private _onLocationChangeListener?;
+    private _pageHooksDisposed;
     config: Config;
     currentChainId?: ChainID;
     currentAddress?: Address;
@@ -132,18 +136,16 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @param {ChainID} params.chainId
      * @param {Address} params.address
      * @param {string} params.message
-     * @param {string} params.signatureHash - only provided if status is confirmed
      * @param {IFormoEventProperties} properties
      * @param {IFormoEventContext} context
      * @param {(...args: unknown[]) => void} callback
      * @returns {Promise<void>}
      */
-    signature({ status, chainId, address, message, signatureHash, }: {
+    signature({ status, chainId, address, message, }: {
         status: SignatureStatus;
         chainId?: ChainID;
         address: Address;
         message: string;
-        signatureHash?: string;
     }, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
     /**
      * Emits a transaction event.
@@ -272,6 +274,12 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     private registerRequestListeners;
     private onLocationChange;
     private trackPageHits;
+    /**
+     * Wrap history.pushState / replaceState exactly once per `history` object,
+     * regardless of how many SDK instances are constructed. Uses a Symbol
+     * marker so we recognize our own wrapper across module reloads in HMR.
+     */
+    private static installHistoryHooksOnce;
     private trackPageHit;
     private trackEvent;
     /**
@@ -312,6 +320,15 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     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;
     /**
      * Polls for transaction receipt and emits tx.status = CONFIRMED or REVERTED.
      */
@@ -362,11 +379,43 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * 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

package/dist/cjs/src/FormoAnalytics.js

@@ -85,6 +85,7 @@ var PROVIDER_SWITCH_REASONS = {
 var FormoAnalytics = /** @class */ (function () {
     function FormoAnalytics(writeKey, options) {
         if (options === void 0) { options = {}; }
+        var _this = this;
         var _a, _b, _c;
         this.writeKey = writeKey;
         this.options = options;
@@ -124,6 +125,7 @@ var FormoAnalytics = /** @class */ (function () {
         this.isEvmDisabled = false;
         /** In-memory URL used to deduplicate SPA pageview events. */
         this._currentUrl = "";
+        this._pageHooksDisposed = false;
         this.currentUserId = "";
         this.config = {
             writeKey: writeKey,
@@ -159,6 +161,10 @@ var FormoAnalytics = /** @class */ (function () {
             maxQueueSize: options.maxQueueSize,
             flushInterval: options.flushInterval,
             errorHandler: options.errorHandler,
+            // Hard consent gate at the queue boundary: nothing buffered is
+            // ever sent once the user has opted out, even via a timer or
+            // pagehide flush scheduled before opt-out.
+            canSend: function () { return !_this.hasOptedOutTracking(); },
         }), options);
         // Check consent status on initialization
         if (this.hasOptedOutTracking()) {
@@ -191,6 +197,10 @@ var FormoAnalytics = /** @class */ (function () {
             this.solanaManager = new SolanaManager_1.SolanaManager(this, options.solana);
         }
         this._currentUrl = window.location.href;
+        // Seed currentAddress/currentChainId from the persisted snapshot before
+        // the first page hit queues so reload-time track()/page() carry the
+        // wallet even before wagmi/EIP-1193 reconnection completes.
+        this.loadActiveWallet();
         this.trackPageHit();
         this.trackPageHits();
     }
@@ -292,10 +302,25 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.reset = function () {
         this.currentUserId = undefined;
+        // Clear in-memory wallet identity too. Without this, a logout/reset
+        // (also triggered by optOutTracking) still leaks the previous wallet
+        // address on subsequent track()/page() events for the rest of the
+        // page lifetime, because they fall back to currentAddress. Keep the
+        // EVM provider reference so tracking can resume on the next connect.
+        this.currentAddress = undefined;
+        this.currentChainId = undefined;
+        var evmProvider = this._chainState.evm.provider;
+        this._chainState = { evm: { provider: evmProvider }, solana: {} };
+        this._activeNamespace = undefined;
         (0, storage_1.cookie)().remove(constants_1.LOCAL_ANONYMOUS_ID_KEY);
         (0, storage_1.cookie)().remove(constants_1.SESSION_USER_ID_KEY);
         (0, storage_1.cookie)().remove(session_1.SESSION_WALLET_DETECTED_KEY);
         (0, storage_1.cookie)().remove(session_1.SESSION_WALLET_IDENTIFIED_KEY);
+        (0, storage_1.cookie)().remove(constants_1.ACTIVE_WALLET_KEY);
+        // Stored traffic-source attribution (referrer/UTM) is tracking data;
+        // clear it too so reset()/optOutTracking() don't leave it to be
+        // re-attached to the next session's events.
+        (0, storage_1.session)().remove(constants_1.SESSION_TRAFFIC_SOURCE_KEY);
     };
     /**
      * Clean up resources and event listeners
@@ -304,6 +329,8 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.cleanup = function () {
         logger_1.logger.debug("FormoAnalytics: Cleaning up resources");
+        // Drop buffered events so a torn-down instance can't flush later.
+        this.eventManager.clear();
         // Clean up Wagmi handler if present
         if (this.wagmiHandler) {
             this.wagmiHandler.cleanup();
@@ -321,6 +348,21 @@ var FormoAnalytics = /** @class */ (function () {
                 this.untrackProvider(provider);
             }
         }
+        // Tear down page-hit hooks: remove window listeners and silence the
+        // history.pushState/replaceState wrappers so an orphaned instance (e.g.
+        // from a re-mount in React Strict Mode / HMR) stops emitting page events
+        // with stale state.
+        this._pageHooksDisposed = true;
+        if (typeof window !== "undefined") {
+            if (this._onPopStateListener) {
+                window.removeEventListener("popstate", this._onPopStateListener);
+                this._onPopStateListener = undefined;
+            }
+            if (this._onLocationChangeListener) {
+                window.removeEventListener("locationchange", this._onLocationChangeListener);
+                this._onLocationChangeListener = undefined;
+            }
+        }
         logger_1.logger.debug("FormoAnalytics: Cleanup complete");
     };
     /**
@@ -452,7 +494,6 @@ var FormoAnalytics = /** @class */ (function () {
      * @param {ChainID} params.chainId
      * @param {Address} params.address
      * @param {string} params.message
-     * @param {string} params.signatureHash - only provided if status is confirmed
      * @param {IFormoEventProperties} properties
      * @param {IFormoEventContext} context
      * @param {(...args: unknown[]) => void} callback
@@ -460,10 +501,15 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.signature = function (_a, properties_1, context_1, callback_1) {
         return __awaiter(this, arguments, void 0, function (_b, properties, context, callback) {
-            var status = _b.status, chainId = _b.chainId, address = _b.address, message = _b.message, signatureHash = _b.signatureHash;
+            var status = _b.status, chainId = _b.chainId, address = _b.address, message = _b.message;
             return __generator(this, function (_c) {
                 switch (_c.label) {
-                    case 0: return [4 /*yield*/, this.trackEvent(constants_1.EventType.SIGNATURE, __assign({ status: status, chainId: chainId, address: address, message: message }, (signatureHash && { signatureHash: signatureHash })), properties, context, callback)];
+                    case 0: return [4 /*yield*/, this.trackEvent(constants_1.EventType.SIGNATURE, {
+                            status: status,
+                            chainId: chainId,
+                            address: address,
+                            message: message,
+                        }, properties, context, callback)];
                     case 1:
                         _c.sent();
                         return [2 /*return*/];
@@ -534,6 +580,13 @@ var FormoAnalytics = /** @class */ (function () {
                 switch (_d.label) {
                     case 0:
                         _d.trys.push([0, 12, , 13]);
+                        // identify() writes the user-id cookie and marks wallet
+                        // identification before trackEvent's consent check — gate the
+                        // whole method so an opted-out user gets no identity persistence.
+                        if (this.hasOptedOutTracking()) {
+                            logger_1.logger.info("identify() skipped: user has opted out of tracking");
+                            return [2 /*return*/];
+                        }
                         if (!!params) return [3 /*break*/, 10];
                         // If no params provided, auto-identify
                         logger_1.logger.info("Auto-identifying with providers:", this._providers.map(function (p) { return p.info.name; }));
@@ -600,6 +653,7 @@ var FormoAnalytics = /** @class */ (function () {
                         validAddress = (0, address_1.validateAddress)(address);
                         if (validAddress) {
                             this.currentAddress = validAddress;
+                            this.persistActiveWallet();
                         }
                         else {
                             (_c = logger_1.logger.warn) === null || _c === void 0 ? void 0 : _c.call(logger_1.logger, "Invalid address provided to identify:", address);
@@ -608,7 +662,7 @@ var FormoAnalytics = /** @class */ (function () {
                         if (userId) {
                             this.currentUserId = userId;
                             domain = (0, cookiePolicy_1.getIdentityCookieDomain)(this.crossSubdomainCookies);
-                            (0, storage_1.cookie)().set(constants_1.SESSION_USER_ID_KEY, userId, __assign({ path: "/" }, (domain ? { domain: domain } : {})));
+                            (0, storage_1.cookie)().set(constants_1.SESSION_USER_ID_KEY, userId, __assign(__assign({ path: "/" }, (0, cookiePolicy_1.getIdentityCookieSecurity)()), (domain ? { domain: domain } : {})));
                         }
                         isAlreadyIdentified = this.session.isWalletIdentified(validAddress, rdns || "");
                         logger_1.logger.debug("Identify: Checking deduplication", {
@@ -657,6 +711,12 @@ var FormoAnalytics = /** @class */ (function () {
             return __generator(this, function (_c) {
                 switch (_c.label) {
                     case 0:
+                        // detect() marks wallet detection (a cookie write) before
+                        // trackEvent's consent check — gate it on opt-out.
+                        if (this.hasOptedOutTracking()) {
+                            logger_1.logger.info("detect() skipped: user has opted out of tracking");
+                            return [2 /*return*/];
+                        }
                         if (this.session.isWalletDetected(rdns))
                             return [2 /*return*/, logger_1.logger.warn("Detect: Wallet ".concat(providerName, " already detected in this session"))];
                         this.session.markWalletDetected(rdns);
@@ -703,6 +763,9 @@ var FormoAnalytics = /** @class */ (function () {
         // Set opt-out flag in persistent storage using direct cookie access
         // This must be done before switching storage to ensure persistence
         (0, consent_1.setConsentFlag)(this.writeKey, constants_1.CONSENT_OPT_OUT_KEY, "true");
+        // Drop anything already buffered so a pending timer/pagehide flush
+        // cannot ship events after consent withdrawal.
+        this.eventManager.clear();
         this.reset();
         logger_1.logger.info("Successfully opted out of tracking");
     };
@@ -1453,35 +1516,52 @@ var FormoAnalytics = /** @class */ (function () {
         });
     };
     FormoAnalytics.prototype.trackPageHits = function () {
-        return __awaiter(this, void 0, void 0, function () {
-            var oldPushState, oldReplaceState;
-            var _this = this;
-            return __generator(this, function (_a) {
-                oldPushState = history.pushState;
-                history.pushState = function pushState() {
-                    var args = [];
-                    for (var _i = 0; _i < arguments.length; _i++) {
-                        args[_i] = arguments[_i];
-                    }
-                    var ret = oldPushState.apply(this, args);
-                    window.dispatchEvent(new window.Event("locationchange"));
-                    return ret;
-                };
-                oldReplaceState = history.replaceState;
-                history.replaceState = function replaceState() {
-                    var args = [];
-                    for (var _i = 0; _i < arguments.length; _i++) {
-                        args[_i] = arguments[_i];
-                    }
-                    var ret = oldReplaceState.apply(this, args);
-                    window.dispatchEvent(new window.Event("locationchange"));
-                    return ret;
-                };
-                window.addEventListener("popstate", function () { return _this.onLocationChange(); });
-                window.addEventListener("locationchange", function () { return _this.onLocationChange(); });
-                return [2 /*return*/];
-            });
-        });
+        var _this = this;
+        // Install a single, instance-agnostic wrapper around history.pushState /
+        // replaceState so concurrent SDK instances (React Strict Mode, HMR) don't
+        // each stack their own wrapper — which would dispatch N synthetic events
+        // per navigation and produce O(N^2) onLocationChange calls. The wrapper
+        // dispatches once; per-instance bookkeeping is done by per-instance
+        // listeners that each register/unregister themselves.
+        FormoAnalytics.installHistoryHooksOnce();
+        this._onPopStateListener = function () { return _this.onLocationChange(); };
+        this._onLocationChangeListener = function () { return _this.onLocationChange(); };
+        window.addEventListener("popstate", this._onPopStateListener);
+        window.addEventListener("locationchange", this._onLocationChangeListener);
+    };
+    /**
+     * Wrap history.pushState / replaceState exactly once per `history` object,
+     * regardless of how many SDK instances are constructed. Uses a Symbol
+     * marker so we recognize our own wrapper across module reloads in HMR.
+     */
+    FormoAnalytics.installHistoryHooksOnce = function () {
+        if (typeof history === "undefined" || typeof window === "undefined")
+            return;
+        var marker = Symbol.for("formo.historyWrapped");
+        if (history[marker])
+            return;
+        history[marker] = true;
+        var dispatch = function () { return window.dispatchEvent(new window.Event("locationchange")); };
+        var oldPushState = history.pushState;
+        history.pushState = function pushState() {
+            var args = [];
+            for (var _i = 0; _i < arguments.length; _i++) {
+                args[_i] = arguments[_i];
+            }
+            var ret = oldPushState.apply(this, args);
+            dispatch();
+            return ret;
+        };
+        var oldReplaceState = history.replaceState;
+        history.replaceState = function replaceState() {
+            var args = [];
+            for (var _i = 0; _i < arguments.length; _i++) {
+                args[_i] = arguments[_i];
+            }
+            var ret = oldReplaceState.apply(this, args);
+            dispatch();
+            return ret;
+        };
     };
     FormoAnalytics.prototype.trackPageHit = function (category, name, properties, context, callback) {
         return __awaiter(this, void 0, void 0, function () {
@@ -1492,6 +1572,12 @@ var FormoAnalytics = /** @class */ (function () {
                     return [2 /*return*/];
                 }
                 setTimeout(function () {
+                    // Drop in-flight page hits from an SDK instance that was torn down
+                    // between scheduling and firing (e.g. provider remount in React Strict
+                    // Mode / HMR). Otherwise the orphan instance would queue a page event
+                    // here with its stale, never-populated `currentAddress`.
+                    if (_this._pageHooksDisposed)
+                        return;
                     (function () { return __awaiter(_this, void 0, void 0, function () {
                         var e_7;
                         return __generator(this, function (_a) {
@@ -1899,7 +1985,9 @@ var FormoAnalytics = /** @class */ (function () {
             });
         });
     };
-    FormoAnalytics.prototype.buildSignatureEventPayload = function (method, params, response, chainId) {
+    FormoAnalytics.prototype.buildSignatureEventPayload = function (method, params, 
+    // Intentionally not read. Kept for positional call-site arity.
+    _response, chainId) {
         var _a;
         var rawAddress = method === "personal_sign"
             ? params[1]
@@ -1908,45 +1996,63 @@ var FormoAnalytics = /** @class */ (function () {
         if (!validAddress) {
             throw new Error("Invalid address in signature payload: ".concat(rawAddress));
         }
+        var effectiveChainId = (_a = chainId !== null && chainId !== void 0 ? chainId : this._evmChainId) !== null && _a !== void 0 ? _a : undefined;
+        this.backfillActiveWallet(validAddress, effectiveChainId);
         var basePayload = {
-            chainId: (_a = chainId !== null && chainId !== void 0 ? chainId : this._evmChainId) !== null && _a !== void 0 ? _a : undefined,
+            chainId: effectiveChainId,
             address: validAddress,
         };
         if (method === "personal_sign") {
             var message = Buffer.from(params[0].slice(2), "hex").toString("utf8");
-            return __assign(__assign(__assign({}, basePayload), { message: message }), (response ? { signatureHash: response } : {}));
+            return __assign(__assign({}, basePayload), { message: message });
         }
-        return __assign(__assign(__assign({}, basePayload), { message: params[1] }), (response ? { signatureHash: response } : {}));
+        // eth_signTypedData*: params[1] is the full EIP-712 struct.
+        return __assign(__assign({}, basePayload), { message: params[1] });
     };
     FormoAnalytics.prototype.buildTransactionEventPayload = function (params, provider) {
         return __awaiter(this, void 0, void 0, function () {
-            var _a, data, from, to, value, validAddress, _b;
-            var _c;
-            return __generator(this, function (_d) {
-                switch (_d.label) {
+            var _a, data, from, to, value, validAddress, chainId, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
                     case 0:
                         _a = params[0], data = _a.data, from = _a.from, to = _a.to, value = _a.value;
                         validAddress = (0, address_1.validateAndChecksumAddress)(from);
                         if (!validAddress) {
                             throw new Error("Invalid address in transaction payload: ".concat(from));
                         }
-                        _c = {};
                         _b = this._evmChainId;
                         if (_b) return [3 /*break*/, 2];
                         return [4 /*yield*/, this.getCurrentChainId(provider)];
                     case 1:
-                        _b = (_d.sent());
-                        _d.label = 2;
-                    case 2: return [2 /*return*/, (_c.chainId = _b,
-                            _c.data = data,
-                            _c.address = validAddress,
-                            _c.to = to,
-                            _c.value = value,
-                            _c)];
+                        _b = (_c.sent());
+                        _c.label = 2;
+                    case 2:
+                        chainId = _b;
+                        this.backfillActiveWallet(validAddress, chainId);
+                        return [2 /*return*/, {
+                                chainId: chainId,
+                                data: data,
+                                address: validAddress,
+                                to: to,
+                                value: value,
+                            }];
                 }
             });
         });
     };
+    /**
+     * 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.
+     */
+    FormoAnalytics.prototype.backfillActiveWallet = function (address, chainId) {
+        if (this._evmAddress)
+            return;
+        this.setChainState('evm', { address: address, chainId: chainId });
+    };
     /**
      * Polls for transaction receipt and emits tx.status = CONFIRMED or REVERTED.
      */
@@ -2017,7 +2123,8 @@ var FormoAnalytics = /** @class */ (function () {
         }
         this._providerListenersMap.delete(provider);
     };
-    // Explicitly untrack a provider: remove listeners, clear wrapper flag and tracking
+    // Explicitly untrack a provider: remove listeners, clear wrapper flag
+    // and tracking
     FormoAnalytics.prototype.untrackProvider = function (provider) {
         try {
             this.removeProviderListeners(provider);
@@ -2135,6 +2242,42 @@ var FormoAnalytics = /** @class */ (function () {
         }
         this.syncDerivedState();
     };
+    /**
+     * 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)
+     */
+    FormoAnalytics.prototype.syncWalletState = function (params) {
+        var chainId = params.chainId, address = params.address;
+        if (!address) {
+            if (chainId !== undefined && chainId !== null) {
+                this.clearChainState(chainId);
+            }
+            else {
+                this.clearChainState("evm");
+                this.clearChainState("solana");
+            }
+            return;
+        }
+        if (chainId === null || chainId === undefined)
+            return;
+        var validAddress = (0, address_1.validateAddress)(address, chainId);
+        if (!validAddress) {
+            logger_1.logger.warn("syncWalletState: invalid address (\"".concat(address, "\") for chain ").concat(chainId));
+            return;
+        }
+        this.setChainState(chainId, { address: validAddress });
+    };
     /**
      * Synchronize currentAddress/currentChainId from the active namespace.
      * Last-connected-chain-wins: _activeNamespace takes precedence.
@@ -2146,6 +2289,7 @@ var FormoAnalytics = /** @class */ (function () {
             if (state.address || state.chainId) {
                 this.currentAddress = state.address;
                 this.currentChainId = state.chainId;
+                this.persistActiveWallet();
                 return;
             }
         }
@@ -2156,10 +2300,77 @@ var FormoAnalytics = /** @class */ (function () {
             this.currentAddress = otherState.address;
             this.currentChainId = otherState.chainId;
             this._activeNamespace = other;
+            this.persistActiveWallet();
             return;
         }
         this.currentAddress = undefined;
         this.currentChainId = undefined;
+        this.persistActiveWallet();
+    };
+    /**
+     * 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.
+     */
+    FormoAnalytics.prototype.persistActiveWallet = function () {
+        try {
+            // Never write an identity cookie for an opted-out user; ensure any
+            // prior snapshot is removed instead.
+            if (this.hasOptedOutTracking()) {
+                (0, storage_1.cookie)().remove(constants_1.ACTIVE_WALLET_KEY);
+                return;
+            }
+            if (this.currentAddress) {
+                var value = JSON.stringify(__assign({ address: this.currentAddress }, (this.currentChainId !== undefined && { chainId: this.currentChainId })));
+                var domain = (0, cookiePolicy_1.getIdentityCookieDomain)(this.crossSubdomainCookies);
+                (0, storage_1.cookie)().set(constants_1.ACTIVE_WALLET_KEY, value, __assign(__assign({ path: "/", expires: new Date(Date.now() + constants_1.ACTIVE_WALLET_TTL_MS).toUTCString() }, (0, cookiePolicy_1.getIdentityCookieSecurity)()), (domain ? { domain: domain } : {})));
+            }
+            else {
+                (0, storage_1.cookie)().remove(constants_1.ACTIVE_WALLET_KEY);
+            }
+        }
+        catch (err) {
+            logger_1.logger.warn("Failed to persist current wallet snapshot", err);
+        }
+    };
+    /**
+     * Seed `currentAddress`/`currentChainId` from the persisted snapshot, if
+     * any. Called once during construction before the first page hit fires.
+     */
+    FormoAnalytics.prototype.loadActiveWallet = function () {
+        try {
+            // Never restore wallet identity into memory for an opted-out user
+            // (mirrors persistActiveWallet's guard); drop any stale snapshot.
+            if (this.hasOptedOutTracking()) {
+                (0, storage_1.cookie)().remove(constants_1.ACTIVE_WALLET_KEY);
+                return;
+            }
+            var raw = (0, storage_1.cookie)().get(constants_1.ACTIVE_WALLET_KEY);
+            if (!raw)
+                return;
+            var parsed = JSON.parse(raw);
+            if (!(parsed === null || parsed === void 0 ? void 0 : parsed.address))
+                return;
+            var namespace = (0, solana_1.isSolanaChainId)(parsed.chainId) ? "solana" : "evm";
+            var validated = (0, address_1.validateAddress)(parsed.address, parsed.chainId);
+            if (!validated) {
+                (0, storage_1.cookie)().remove(constants_1.ACTIVE_WALLET_KEY);
+                return;
+            }
+            var ns = this._chainState[namespace];
+            ns.address = validated;
+            if (parsed.chainId !== undefined)
+                ns.chainId = parsed.chainId;
+            this._activeNamespace = namespace;
+            this.currentAddress = validated;
+            this.currentChainId = parsed.chainId;
+        }
+        catch (err) {
+            logger_1.logger.warn("Failed to restore persisted wallet snapshot", err);
+            (0, storage_1.cookie)().remove(constants_1.ACTIVE_WALLET_KEY);
+        }
     };
     /**
      * Helper method to clear the active provider state

package/dist/cjs/src/constants/base.d.ts

@@ -1,5 +1,14 @@
 export declare const SESSION_TRAFFIC_SOURCE_KEY = "traffic-source";
 export declare const SESSION_USER_ID_KEY = "user-id";
+/**
+ * Persisted snapshot of the currently-active EVM/Solana wallet
+ * (address + chainId). Lets the SDK seed `currentAddress`/`currentChainId`
+ * at init so the first page hit after a reload carries the address, without
+ * having to wait for wagmi/EIP-1193 reconnection to fire.
+ */
+export declare const ACTIVE_WALLET_KEY = "active-wallet";
+/** TTL for the persisted active-wallet snapshot cookie. */
+export declare const ACTIVE_WALLET_TTL_MS: number;
 export declare const LOCAL_ANONYMOUS_ID_KEY = "anonymous-id";
 export declare const CONSENT_OPT_OUT_KEY = "opt-out-tracking";
 export declare const DEFAULT_PROVIDER_ICON = "data:image/svg+xml;base64,";

package/dist/cjs/src/constants/base.js

@@ -1,10 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BLOCKED_ADDRESSES = exports.DEAD_ADDRESS = exports.ZERO_ADDRESS = exports.DEFAULT_PROVIDER_ICON = exports.CONSENT_OPT_OUT_KEY = exports.LOCAL_ANONYMOUS_ID_KEY = exports.SESSION_USER_ID_KEY = exports.SESSION_TRAFFIC_SOURCE_KEY = void 0;
+exports.BLOCKED_ADDRESSES = exports.DEAD_ADDRESS = exports.ZERO_ADDRESS = exports.DEFAULT_PROVIDER_ICON = exports.CONSENT_OPT_OUT_KEY = exports.LOCAL_ANONYMOUS_ID_KEY = exports.ACTIVE_WALLET_TTL_MS = exports.ACTIVE_WALLET_KEY = exports.SESSION_USER_ID_KEY = exports.SESSION_TRAFFIC_SOURCE_KEY = void 0;
 exports.SESSION_TRAFFIC_SOURCE_KEY = "traffic-source";
 // SESSION_WALLET_DETECTED_KEY and SESSION_WALLET_IDENTIFIED_KEY
 // are now defined in src/session/index.ts
 exports.SESSION_USER_ID_KEY = "user-id";
+/**
+ * Persisted snapshot of the currently-active EVM/Solana wallet
+ * (address + chainId). Lets the SDK seed `currentAddress`/`currentChainId`
+ * at init so the first page hit after a reload carries the address, without
+ * having to wait for wagmi/EIP-1193 reconnection to fire.
+ */
+exports.ACTIVE_WALLET_KEY = "active-wallet";
+/** TTL for the persisted active-wallet snapshot cookie. */
+exports.ACTIVE_WALLET_TTL_MS = 24 * 60 * 60 * 1000;
 exports.LOCAL_ANONYMOUS_ID_KEY = "anonymous-id";
 // Consent management keys
 exports.CONSENT_OPT_OUT_KEY = "opt-out-tracking";