@formo/analytics 1.33.1 → 1.34.1

package/dist/cjs/src/FormoAnalytics.js

@@ -75,6 +75,8 @@ var chain_1 = require("./utils/chain");
 var wagmi_1 = require("./wagmi");
 var solana_1 = require("./solana");
 var SolanaManager_1 = require("./solana/SolanaManager");
+// Internal: the Privy identify is reached through identify(user), not exported.
+var utils_1 = require("./privy/utils");
 /**
  * Constants for provider switching reasons
  */
@@ -90,7 +92,7 @@ var FormoAnalytics = /** @class */ (function () {
         var _a, _b, _c;
         this.writeKey = writeKey;
         this.options = options;
-        // Per-chain namespace state — isolates EVM and Solana connection state
+        // Per-chain namespace state - isolates EVM and Solana connection state
         this._chainState = {
             evm: {},
             solana: {},
@@ -206,7 +208,7 @@ var FormoAnalytics = /** @class */ (function () {
         this.trackPageHits();
     }
     Object.defineProperty(FormoAnalytics.prototype, "_provider", {
-        // EVM state accessors — EVM listener paths must use these instead of
+        // EVM state accessors - EVM listener paths must use these instead of
         // currentAddress/currentChainId to avoid cross-namespace reads.
         get: function () {
             return this._chainState.evm.provider;
@@ -396,7 +398,7 @@ var FormoAnalytics = /** @class */ (function () {
                             return [2 /*return*/];
                         }
                         // connect() persists wallet/chain state (active-wallet cookie,
-                        // currentAddress/currentChainId) before trackEvent's consent check —
+                        // currentAddress/currentChainId) before trackEvent's consent check -
                         // gate the whole method so a suppressed visitor or excluded environment
                         // (opt-out / timezone / host / path) leaves no session state.
                         if (this.isTrackingSuppressed()) {
@@ -553,79 +555,85 @@ var FormoAnalytics = /** @class */ (function () {
             });
         });
     };
-    /**
-     * Emits an identify event with current wallet address and provider info.
-     *
-     * @param {string} params.address - Wallet address
-     * @param {string} params.userId - External user ID
-     * @param {string} params.rdns - Provider reverse domain name
-     * @param {string} params.providerName - Provider display name
-     * @param {IFormoEventProperties} properties - Additional properties to include with the identify event
-     * @param {IFormoEventContext} context
-     * @param {(...args: unknown[]) => void} callback
-     * @returns {Promise<void>}
-     *
-     * @example
-     * ```ts
-     * // Basic identify
-     * formo.identify({ address: '0x...', userId: 'user123' });
-     *
-     * // With Privy user
-     * import { parsePrivyProperties } from '@formo/analytics';
-     * const { user } = usePrivy();
-     * if (user) {
-     *   const { properties, wallets } = parsePrivyProperties(user);
-     *   for (const wallet of wallets) {
-     *     formo.identify({ address: wallet.address, userId: user.id }, properties);
-     *   }
-     * }
-     * ```
-     */
-    FormoAnalytics.prototype.identify = function (params, properties, context, callback) {
+    FormoAnalytics.prototype.identify = function (paramsOrUser, propertiesOrOptions, context, callback) {
         return __awaiter(this, void 0, void 0, function () {
-            var _i, _a, providerDetail, provider, address_2, validAddress_1, err_1, address, providerName, userId, rdns, validAddress, domain, isAlreadyIdentified, e_1;
+            var maybeUser, opts, params, properties, _i, _a, providerDetail, provider, address_2, validAddress_1, err_1, address, providerName, userId, rdns, setActive, validAddress, domain, isAlreadyIdentified, e_1;
             var _b, _c;
             return __generator(this, function (_d) {
                 switch (_d.label) {
                     case 0:
-                        _d.trys.push([0, 12, , 13]);
+                        _d.trys.push([0, 14, , 15]);
+                        maybeUser = paramsOrUser;
+                        if (!(maybeUser &&
+                            typeof maybeUser.id === "string" &&
+                            maybeUser.address === undefined)) return [3 /*break*/, 2];
+                        opts = (propertiesOrOptions !== null && propertiesOrOptions !== void 0 ? propertiesOrOptions : {});
+                        // identifyPrivyUser records every linked wallet for clustering WITHOUT
+                        // touching active state (internal setActive:false), promotes only the
+                        // resolved active wallet, and reconciles the chain id with that wallet's
+                        // namespace before emitting. It reads this.currentAddress itself to
+                        // preserve an already-connected wallet, so this dispatch is a thin
+                        // pass-through and both entry points behave identically.
+                        return [4 /*yield*/, (0, utils_1.identifyPrivyUser)(this, maybeUser, {
+                                activeAddress: opts.activeAddress,
+                                properties: opts.properties,
+                            })];
+                    case 1:
+                        // identifyPrivyUser records every linked wallet for clustering WITHOUT
+                        // touching active state (internal setActive:false), promotes only the
+                        // resolved active wallet, and reconciles the chain id with that wallet's
+                        // namespace before emitting. It reads this.currentAddress itself to
+                        // preserve an already-connected wallet, so this dispatch is a thin
+                        // pass-through and both entry points behave identically.
+                        _d.sent();
+                        return [2 /*return*/];
+                    case 2:
+                        params = paramsOrUser;
+                        properties = propertiesOrOptions;
                         // identify() writes the user-id cookie and marks wallet
-                        // identification before trackEvent's consent check — gate the whole
+                        // identification before trackEvent's consent check - gate the whole
                         // method so a suppressed visitor or excluded environment (opt-out /
                         // timezone / host / path) gets no identity persistence.
-                        if (this.isTrackingSuppressed()) {
-                            logger_1.logger.info("identify() skipped: tracking is suppressed for this visitor or environment");
+                        //
+                        // The chain check belongs here and NOT in isTrackingSuppressed(), which
+                        // identifyPrivyUser calls before it reconciles the chain. Folding it in
+                        // there would block a Privy sync that reconciliation was about to make
+                        // valid (activating a Solana wallet while an excluded EVM chain id is
+                        // still current). By the time the Privy path reaches this guard it has
+                        // already reconciled, so each inner identify is judged on the right chain.
+                        if (this.isTrackingSuppressed() || this.isCurrentChainExcluded()) {
+                            logger_1.logger.info("identify() skipped: tracking is suppressed for this visitor, environment, or chain");
                             return [2 /*return*/];
                         }
-                        if (!!params) return [3 /*break*/, 10];
+                        if (!!params) return [3 /*break*/, 12];
                         // If no params provided, auto-identify
                         logger_1.logger.info("Auto-identifying with providers:", this._providers.map(function (p) { return p.info.name; }));
                         _i = 0, _a = this._providers;
-                        _d.label = 1;
-                    case 1:
-                        if (!(_i < _a.length)) return [3 /*break*/, 9];
+                        _d.label = 3;
+                    case 3:
+                        if (!(_i < _a.length)) return [3 /*break*/, 11];
                         providerDetail = _a[_i];
                         provider = providerDetail.provider;
                         if (!provider)
-                            return [3 /*break*/, 8];
-                        _d.label = 2;
-                    case 2:
-                        _d.trys.push([2, 7, , 8]);
+                            return [3 /*break*/, 10];
+                        _d.label = 4;
+                    case 4:
+                        _d.trys.push([4, 9, , 10]);
                         return [4 /*yield*/, this.getAddress(provider)];
-                    case 3:
+                    case 5:
                         address_2 = _d.sent();
-                        if (!address_2) return [3 /*break*/, 6];
+                        if (!address_2) return [3 /*break*/, 8];
                         validAddress_1 = (0, address_1.validateAndChecksumAddress)(address_2);
                         logger_1.logger.info("Auto-identify: Checking deduplication", {
                             validAddress: validAddress_1,
                             rdns: providerDetail.info.rdns,
                             providerName: providerDetail.info.name,
                             isAlreadyIdentified: validAddress_1
-                                ? this.session.isWalletIdentified(validAddress_1, providerDetail.info.rdns)
+                                ? this.session.isWalletIdentified(validAddress_1, providerDetail.info.rdns, undefined, properties)
                                 : false,
                         });
                         if (!(validAddress_1 &&
-                            !this.session.isWalletIdentified(validAddress_1, providerDetail.info.rdns))) return [3 /*break*/, 5];
+                            !this.session.isWalletIdentified(validAddress_1, providerDetail.info.rdns, undefined, properties))) return [3 /*break*/, 7];
                         logger_1.logger.info("Auto-identifying", validAddress_1, providerDetail.info.name, providerDetail.info.rdns);
                         // NOTE: do not set this.currentAddress without explicit connect or identify
                         return [4 /*yield*/, this.identify({
@@ -633,26 +641,26 @@ var FormoAnalytics = /** @class */ (function () {
                                 providerName: providerDetail.info.name,
                                 rdns: providerDetail.info.rdns,
                             }, properties, context, callback)];
-                    case 4:
+                    case 6:
                         // NOTE: do not set this.currentAddress without explicit connect or identify
                         _d.sent();
-                        return [3 /*break*/, 6];
-                    case 5:
+                        return [3 /*break*/, 8];
+                    case 7:
                         if (validAddress_1) {
                             logger_1.logger.info("Auto-identify: Skipping already identified wallet", validAddress_1, providerDetail.info.name, providerDetail.info.rdns);
                         }
-                        _d.label = 6;
-                    case 6: return [3 /*break*/, 8];
-                    case 7:
+                        _d.label = 8;
+                    case 8: return [3 /*break*/, 10];
+                    case 9:
                         err_1 = _d.sent();
                         logger_1.logger.error("Failed to identify provider ".concat(providerDetail.info.name, ":"), err_1);
-                        return [3 /*break*/, 8];
-                    case 8:
-                        _i++;
-                        return [3 /*break*/, 1];
-                    case 9: return [2 /*return*/];
+                        return [3 /*break*/, 10];
                     case 10:
-                        address = params.address, providerName = params.providerName, userId = params.userId, rdns = params.rdns;
+                        _i++;
+                        return [3 /*break*/, 3];
+                    case 11: return [2 /*return*/];
+                    case 12:
+                        address = params.address, providerName = params.providerName, userId = params.userId, rdns = params.rdns, setActive = params.setActive;
                         // Runtime validation: address is required
                         if (!address) {
                             (_b = logger_1.logger.warn) === null || _b === void 0 ? void 0 : _b.call(logger_1.logger, "identify() called without address - address is required");
@@ -661,20 +669,26 @@ var FormoAnalytics = /** @class */ (function () {
                         // Explicit identify
                         logger_1.logger.info("Identify", address, userId, providerName, rdns);
                         validAddress = (0, address_1.validateAddress)(address);
-                        if (validAddress) {
-                            this.currentAddress = validAddress;
-                            this.persistActiveWallet();
-                        }
-                        else {
+                        if (!validAddress) {
                             (_c = logger_1.logger.warn) === null || _c === void 0 ? void 0 : _c.call(logger_1.logger, "Invalid address provided to identify:", address);
                             return [2 /*return*/];
                         }
-                        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(__assign({ path: "/" }, (0, cookiePolicy_1.getIdentityCookieSecurity)()), (domain ? { domain: domain } : {})));
+                        // Promote this wallet to the SDK's active identity - the (currentAddress,
+                        // currentUserId) pair later events are attributed to - unless the caller
+                        // opts out with setActive:false. A non-active identify still emits its
+                        // event and marks dedup below (for clustering), it just doesn't repoint
+                        // attribution. Gating address and userId together prevents leaving the
+                        // active address paired with a different wallet's user id.
+                        if (setActive !== false) {
+                            this.currentAddress = validAddress;
+                            this.persistActiveWallet();
+                            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(__assign({ path: "/" }, (0, cookiePolicy_1.getIdentityCookieSecurity)()), (domain ? { domain: domain } : {})));
+                            }
                         }
-                        isAlreadyIdentified = this.session.isWalletIdentified(validAddress, rdns || "");
+                        isAlreadyIdentified = this.session.isWalletIdentified(validAddress, rdns || "", userId, properties);
                         logger_1.logger.debug("Identify: Checking deduplication", {
                             validAddress: validAddress,
                             rdns: rdns,
@@ -687,25 +701,77 @@ var FormoAnalytics = /** @class */ (function () {
                             return [2 /*return*/];
                         }
                         // Mark as identified before emitting the event
-                        this.session.markWalletIdentified(validAddress, rdns || "");
+                        this.session.markWalletIdentified(validAddress, rdns || "", userId, properties);
                         return [4 /*yield*/, this.trackEvent(constants_1.EventType.IDENTIFY, {
                                 address: validAddress,
                                 providerName: providerName,
                                 userId: userId,
                                 rdns: rdns,
                             }, properties, context, callback)];
-                    case 11:
+                    case 13:
                         _d.sent();
-                        return [3 /*break*/, 13];
-                    case 12:
+                        return [3 /*break*/, 15];
+                    case 14:
                         e_1 = _d.sent();
                         logger_1.logger.log("identify error", e_1);
-                        return [3 /*break*/, 13];
-                    case 13: return [2 /*return*/];
+                        return [3 /*break*/, 15];
+                    case 15: return [2 /*return*/];
                 }
             });
         });
     };
+    /**
+     * Reconcile currentChainId with a newly-activated Privy wallet's chain
+     * namespace. identify() sets currentAddress but never touches the chain id
+     * (that comes from connect()/chain()/wagmi), so activating e.g. a Solana
+     * wallet while an EVM chain id is current would leave the address paired with
+     * a mismatched chain in events, excludeChains, and the active-wallet cookie.
+     *
+     * We can't infer the wallet's specific chain id from Privy's chainType, so on
+     * a namespace mismatch we clear the chain id rather than assert a wrong one; a
+     * real wallet connect will set the correct chain. Same-namespace activations
+     * (and wallets whose namespace can't be determined) leave the chain id alone.
+     *
+     * Privy doesn't always supply `chainType`: a `smart_wallet` entry is
+     * `{ type, address, smartWalletType }`, and `cross_app` wallets are bare
+     * `{ address }`. A `0x`-prefixed 20-byte address is unambiguously EVM though,
+     * so fall back to the address shape - otherwise activating an EVM smart
+     * wallet while a Solana chain id is current would leave the address paired
+     * with the wrong chain, and an `excludeChains` gate could drop the identify
+     * after it was already dedup-marked.
+     *
+     * @internal Not part of the public IFormoAnalytics contract - invoked by
+     * `identifyPrivyUser` (via a structural cast) before it emits, so both the
+     * `identify(user,{privy:true})` and direct `identifyPrivyUser()` paths
+     * reconcile the chain.
+     */
+    FormoAnalytics.prototype.syncPrivyActiveChain = function (chainType, address) {
+        if (this.currentChainId === undefined || this.currentChainId === null)
+            return;
+        var walletIsSolana;
+        var namespace = chainType === null || chainType === void 0 ? void 0 : chainType.toLowerCase();
+        // Only recognized namespaces decide. An unknown or future chainType
+        // ("bitcoin", "cosmos", …) must stay undecided rather than defaulting to
+        // EVM, which would wrongly clear a valid Solana chain id.
+        if (namespace === "solana") {
+            walletIsSolana = true;
+        }
+        else if (namespace === "ethereum") {
+            walletIsSolana = false;
+        }
+        else if (!namespace && address && /^0x[0-9a-f]{40}$/i.test(address)) {
+            // Only the EVM shape is inferable: a non-0x address could be Solana,
+            // Bitcoin, Cosmos, … so absence of 0x proves nothing.
+            walletIsSolana = false;
+        }
+        if (walletIsSolana === undefined)
+            return;
+        var currentIsSolana = (0, solana_1.isSolanaChainId)(this.currentChainId);
+        if (walletIsSolana !== currentIsSolana) {
+            this.currentChainId = undefined;
+            this.persistActiveWallet();
+        }
+    };
     /**
      * Emits a detect wallet event with current wallet provider info.
      * @param {string} params.providerName
@@ -722,7 +788,7 @@ var FormoAnalytics = /** @class */ (function () {
                 switch (_c.label) {
                     case 0:
                         // detect() marks wallet detection (a cookie write) before
-                        // trackEvent's consent check — gate it for a suppressed visitor or
+                        // trackEvent's consent check - gate it for a suppressed visitor or
                         // excluded environment (opt-out / timezone / host / path).
                         if (this.isTrackingSuppressed()) {
                             logger_1.logger.info("detect() skipped: tracking is suppressed for this visitor or environment");
@@ -1091,7 +1157,7 @@ var FormoAnalytics = /** @class */ (function () {
                         wasDisconnected = !this._evmAddress;
                         // Update state regardless of whether connect *event* tracking is enabled,
                         // so disconnect events keep valid address/chainId values. (excludeChains is
-                        // NOT suppression — it still updates state so currentChainId can gate
+                        // NOT suppression - it still updates state so currentChainId can gate
                         // events.)
                         if (this.isTrackingSuppressed()) {
                             this.clearStaleEvmWalletOnSwitchWhileSuppressed(address);
@@ -1272,7 +1338,7 @@ var FormoAnalytics = /** @class */ (function () {
                             }
                             isActiveProvider = this._provider === provider;
                             // Update state from active provider so disconnect events keep valid
-                            // address/chainId values — except while suppressed, where we must not
+                            // address/chainId values - except while suppressed, where we must not
                             // LEARN identity (only drop a stale EVM wallet on a switch).
                             if (isActiveProvider) {
                                 if (this.isTrackingSuppressed()) {
@@ -1543,7 +1609,7 @@ var FormoAnalytics = /** @class */ (function () {
         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
+        // 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.
@@ -1656,22 +1722,50 @@ var FormoAnalytics = /** @class */ (function () {
      * 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
+     * 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
+     * @internal Also read by `identifyPrivyUser` (via a structural cast) so the
+     * Privy sync skips chain reconciliation and emission for suppressed visitors.
      */
     FormoAnalytics.prototype.isTrackingSuppressed = function () {
         return this.hasOptedOutTracking() || this.isCurrentEnvironmentExcluded();
     };
     /**
-     * Whether the current environment is excluded from tracking — the visitor's
+     * 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.
+     */
+    FormoAnalytics.prototype.isCurrentChainExcluded = function () {
+        if (this.options.tracking === null ||
+            typeof this.options.tracking !== "object" ||
+            Array.isArray(this.options.tracking)) {
+            return false;
+        }
+        var _a = this.options.tracking.excludeChains, excludeChains = _a === void 0 ? [] : _a;
+        return (excludeChains.length > 0 &&
+            !!this.currentChainId &&
+            excludeChains.includes(this.currentChainId));
+    };
+    /**
+     * 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,
+     * 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.
@@ -1684,7 +1778,7 @@ var FormoAnalytics = /** @class */ (function () {
     };
     /**
      * Whether the current hostname matches a configured `tracking.excludeHosts`
-     * entry (exact match). Current-page-level — see isCurrentEnvironmentExcluded.
+     * entry (exact match). Current-page-level - see isCurrentEnvironmentExcluded.
      * @returns {boolean} True if the current hostname is excluded
      */
     FormoAnalytics.prototype.isHostExcluded = function () {
@@ -1702,7 +1796,7 @@ var FormoAnalytics = /** @class */ (function () {
     };
     /**
      * Whether the current pathname matches a configured `tracking.excludePaths`
-     * entry (exact match). Current-page-level — see isCurrentEnvironmentExcluded.
+     * entry (exact match). Current-page-level - see isCurrentEnvironmentExcluded.
      * @returns {boolean} True if the current pathname is excluded
      */
     FormoAnalytics.prototype.isPathExcluded = function () {
@@ -1719,8 +1813,8 @@ var FormoAnalytics = /** @class */ (function () {
         return excludePaths.includes(window.location.pathname);
     };
     /**
-     * Whether the current call is in a visitor-level suppression state — opt-out
-     * or excluded timezone — for which any persisted identity cookie should be
+     * 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
@@ -1733,7 +1827,7 @@ var FormoAnalytics = /** @class */ (function () {
     /**
      * Whether the visitor's browser-resolved timezone matches a configured
      * `tracking.excludeTimezones` entry (case-insensitive). Client-side and
-     * best-effort — see TrackingOptions.excludeTimezones.
+     * best-effort - see TrackingOptions.excludeTimezones.
      * @returns {boolean} True if the current timezone is excluded
      */
     FormoAnalytics.prototype.isTimezoneExcluded = function () {
@@ -1772,7 +1866,7 @@ var FormoAnalytics = /** @class */ (function () {
             typeof this.options.tracking === "object" &&
             !Array.isArray(this.options.tracking)) {
             var _a = this.options.tracking.excludeChains, excludeChains = _a === void 0 ? [] : _a;
-            // Environment exclusions (timezone / host / path) — no identify / connect
+            // Environment exclusions (timezone / host / path) - no identify / connect
             // / track events while excluded. Host/path are exact-match.
             if (this.isCurrentEnvironmentExcluded()) {
                 return false;
@@ -2385,7 +2479,7 @@ var FormoAnalytics = /** @class */ (function () {
      * WITHOUT emitting an event.
      *
      * Integrations (e.g. the wagmi handler) must call this on every
-     * connect / chain-change / disconnect — even when the corresponding
+     * 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
@@ -2399,7 +2493,7 @@ var FormoAnalytics = /** @class */ (function () {
         var chainId = params.chainId, address = params.address;
         if (this.isTrackingSuppressed()) {
             // While suppressed (opt-out / timezone / excluded host or path) we must
-            // never LEARN a new wallet — but we must still CLEAR stale identity.
+            // never LEARN a new wallet - but we must still CLEAR stale identity.
             // Otherwise a disconnect or wallet switch observed on a suppressed route
             // would leave the previously-learned address in memory and in the
             // active-wallet cookie, attaching it to later allowed-page events.
@@ -2481,14 +2575,14 @@ var FormoAnalytics = /** @class */ (function () {
     /**
      * 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
+     * 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 {
             // Visitor-level suppression (opt-out or excluded timezone): purge any
-            // prior snapshot — these are stable for the session, so deletion is safe.
+            // prior snapshot - these are stable for the session, so deletion is safe.
             if (this.isPersistedIdentityPurgeRequired()) {
                 (0, storage_1.cookie)().remove(constants_1.ACTIVE_WALLET_KEY);
                 return;

package/dist/cjs/src/event/EventFactory.d.ts

@@ -41,7 +41,7 @@ declare class EventFactory implements IEventFactory {
     /**
      * Returns the document referrer with same-host referrers filtered out.
      * Internal navigation populates `document.referrer` with the previous page
-     * on the same site, which is not an attribution signal — treating it as
+     * on the same site, which is not an attribution signal - treating it as
      * "external" would otherwise let an internal URL become the session's
      * first-touch referrer after a direct landing.
      */

package/dist/cjs/src/event/EventFactory.js

@@ -70,6 +70,7 @@ var mergeDeepRight_1 = __importDefault(require("../ramda/mergeDeepRight"));
 var storage_1 = require("../storage");
 var version_1 = require("../version");
 var constants_2 = require("./constants");
+var sanitize_1 = require("./sanitize");
 var utils_2 = require("./utils");
 var browsers_1 = require("../browser/browsers");
 var ISO_3166_ALPHA_2_REGEX = /^[A-Z]{2}$/;
@@ -138,7 +139,7 @@ var EventFactory = /** @class */ (function () {
         /**
          * Returns the document referrer with same-host referrers filtered out.
          * Internal navigation populates `document.referrer` with the previous page
-         * on the same site, which is not an attribution signal — treating it as
+         * on the same site, which is not an attribution signal - treating it as
          * "external" would otherwise let an internal URL become the session's
          * first-touch referrer after a direct landing.
          */
@@ -157,12 +158,16 @@ var EventFactory = /** @class */ (function () {
         };
         this.getTrafficSources = function (url) {
             var urlObj = new URL(url);
-            var contextTrafficSources = __assign(__assign(__assign({}, _this.extractUTMParameters(url)), _this.extractClickIdParameters(urlObj)), { ref: _this.extractReferralParameter(urlObj), referrer: _this.getExternalReferrer() });
+            // Sanitize at the source so scanner-injected garbage (XSS probes in
+            // utm_*/click-id/ref query params) never wins the context-over-stored
+            // merge below, never gets persisted, and never reaches an event.
+            var contextTrafficSources = (0, sanitize_1.sanitizeTrafficSources)(__assign(__assign(__assign({}, _this.extractUTMParameters(url)), _this.extractClickIdParameters(urlObj)), { ref: _this.extractReferralParameter(urlObj), referrer: _this.getExternalReferrer() }));
             // Sticky traffic sources may have been persisted by an older SDK version or
             // a looser config, before the current excludeQueryParams was in effect.
             // Honor the current denylist on the way out so excluded values can never
-            // resurface from session storage (or get re-persisted below).
-            var storedTrafficSources = _this.redactStoredTrafficSources((0, storage_1.session)().get(constants_1.SESSION_TRAFFIC_SOURCE_KEY) || {});
+            // resurface from session storage (or get re-persisted below). Sanitizing
+            // here too flushes poisoned values persisted by a pre-sanitization SDK.
+            var storedTrafficSources = (0, sanitize_1.sanitizeTrafficSources)(_this.redactStoredTrafficSources((0, storage_1.session)().get(constants_1.SESSION_TRAFFIC_SOURCE_KEY) || {}));
             var mergedClickIds = {};
             for (var _i = 0, CLICK_ID_PARAMS_2 = constants_2.CLICK_ID_PARAMS; _i < CLICK_ID_PARAMS_2.length; _i++) {
                 var p = CLICK_ID_PARAMS_2[_i];
@@ -593,8 +598,9 @@ var EventFactory = /** @class */ (function () {
     EventFactory.prototype.create = function (event, address, userId) {
         return __awaiter(this, void 0, void 0, function () {
             var formoEvent, _a, chainId;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
+            var _b, _c;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
                     case 0:
                         formoEvent = {};
                         _a = event.type;
@@ -612,39 +618,39 @@ var EventFactory = /** @class */ (function () {
                         return [3 /*break*/, 17];
                     case 1: return [4 /*yield*/, this.generatePageEvent(event.category, event.name, event.properties, event.context)];
                     case 2:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 3: return [4 /*yield*/, this.generateDetectWalletEvent(event.providerName, event.rdns, event.properties, event.context)];
                     case 4:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 5: return [4 /*yield*/, this.generateIdentifyEvent(event.providerName, event.rdns, event.address, event.userId, event.properties, event.context)];
                     case 6:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 7: return [4 /*yield*/, this.generateChainChangedEvent(event.chainId, event.address, event.properties, event.context)];
                     case 8:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 9: return [4 /*yield*/, this.generateConnectEvent(event.chainId, event.address, event.properties, event.context)];
                     case 10:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 11: return [4 /*yield*/, this.generateDisconnectEvent(event.chainId, event.address, event.properties, event.context)];
                     case 12:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 13: return [4 /*yield*/, this.generateSignatureEvent(event.status, event.chainId, event.address, event.message, event.properties, event.context)];
                     case 14:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 15: return [4 /*yield*/, this.generateTransactionEvent(event.status, event.chainId, event.address, event.data, event.to, event.value, event.transactionHash, event.function_name, event.function_args, event.properties, event.context)];
                     case 16:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 17: return [4 /*yield*/, this.generateTrackEvent(event.event, event.properties, event.context)];
                     case 18:
-                        formoEvent = _b.sent();
+                        formoEvent = _d.sent();
                         return [3 /*break*/, 19];
                     case 19:
                         // Set address if not already set by the specific event generator
@@ -655,7 +661,17 @@ var EventFactory = /** @class */ (function () {
                             chainId = 'chainId' in event ? event.chainId : undefined;
                             formoEvent.address = this.validateEventAddress(address, chainId);
                         }
-                        formoEvent.user_id = userId || null;
+                        // An identify event asserts an explicit identity in its own payload (e.g. a
+                        // Privy DID for each wallet being clustered). Keep that payload user_id
+                        // rather than overwriting it with the active-session user id - otherwise a
+                        // clustering identify that intentionally leaves the active user unchanged
+                        // (setActive:false) would be stripped of its DID, defeating server-side
+                        // wallet clustering. Fall back to the active-session user id when the
+                        // identify payload carries none; all other events use the session user id.
+                        formoEvent.user_id =
+                            event.type === "identify"
+                                ? (_c = (_b = formoEvent.user_id) !== null && _b !== void 0 ? _b : userId) !== null && _c !== void 0 ? _c : null
+                                : userId || null;
                         return [2 /*return*/, formoEvent];
                 }
             });

package/dist/cjs/src/event/sanitize.d.ts

@@ -0,0 +1,13 @@
+import { ITrafficSource } from "../types";
+declare const sanitizeClickId: (value: string) => string;
+declare const sanitizeRef: (value: string) => string;
+declare const sanitizeUtm: (value: string) => string;
+/**
+ * Sanitize every traffic-source field of a (possibly sparse) traffic-source
+ * object. `referrer` is left untouched: it is a browser-set URL already
+ * handled by redactUrl, not an attacker-controlled query parameter. Unknown
+ * keys fall through to the UTM rule, the most permissive one.
+ */
+declare const sanitizeTrafficSources: <T extends Partial<ITrafficSource>>(trafficSources: T) => T;
+export { sanitizeClickId, sanitizeRef, sanitizeUtm, sanitizeTrafficSources };
+//# sourceMappingURL=sanitize.d.ts.map