@formo/analytics 1.33.0 → 1.34.0

package/dist/esm/src/FormoAnalytics.js

@@ -72,6 +72,7 @@ import { parseChainId } from "./utils/chain";
 import { WagmiEventHandler } from "./wagmi";
 import { isSolanaChainId } from "./solana";
 import { SolanaManager } from "./solana/SolanaManager";
+import { identifyPrivyUser } from "./privy";
 /**
  * Constants for provider switching reasons
  */
@@ -87,7 +88,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: {},
@@ -203,7 +204,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;
@@ -393,7 +394,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()) {
@@ -550,79 +551,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_1, validAddress_1, err_1, address, providerName, userId, rdns, validAddress, domain, isAlreadyIdentified, e_1;
+            var maybeUser, opts, params, properties, _i, _a, providerDetail, provider, address_1, 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*/, 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.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.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.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_1 = _d.sent();
-                        if (!address_1) return [3 /*break*/, 6];
+                        if (!address_1) return [3 /*break*/, 8];
                         validAddress_1 = validateAndChecksumAddress(address_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.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({
@@ -630,26 +637,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.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.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.warn) === null || _b === void 0 ? void 0 : _b.call(logger, "identify() called without address - address is required");
@@ -658,20 +665,26 @@ var FormoAnalytics = /** @class */ (function () {
                         // Explicit identify
                         logger.info("Identify", address, userId, providerName, rdns);
                         validAddress = validateAddress(address);
-                        if (validAddress) {
-                            this.currentAddress = validAddress;
-                            this.persistActiveWallet();
-                        }
-                        else {
+                        if (!validAddress) {
                             (_c = logger.warn) === null || _c === void 0 ? void 0 : _c.call(logger, "Invalid address provided to identify:", address);
                             return [2 /*return*/];
                         }
-                        if (userId) {
-                            this.currentUserId = userId;
-                            domain = getIdentityCookieDomain(this.crossSubdomainCookies);
-                            cookie().set(SESSION_USER_ID_KEY, userId, __assign(__assign({ path: "/" }, 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 = getIdentityCookieDomain(this.crossSubdomainCookies);
+                                cookie().set(SESSION_USER_ID_KEY, userId, __assign(__assign({ path: "/" }, getIdentityCookieSecurity()), (domain ? { domain: domain } : {})));
+                            }
                         }
-                        isAlreadyIdentified = this.session.isWalletIdentified(validAddress, rdns || "");
+                        isAlreadyIdentified = this.session.isWalletIdentified(validAddress, rdns || "", userId, properties);
                         logger.debug("Identify: Checking deduplication", {
                             validAddress: validAddress,
                             rdns: rdns,
@@ -684,25 +697,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(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.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 = 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
@@ -719,7 +784,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.info("detect() skipped: tracking is suppressed for this visitor or environment");
@@ -1088,7 +1153,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);
@@ -1269,7 +1334,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()) {
@@ -1540,7 +1605,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.
@@ -1653,22 +1718,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.
@@ -1681,7 +1774,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 () {
@@ -1699,7 +1792,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 () {
@@ -1716,8 +1809,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
@@ -1730,7 +1823,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 () {
@@ -1769,7 +1862,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;
@@ -2382,7 +2475,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
@@ -2396,7 +2489,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.
@@ -2478,14 +2571,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()) {
                 cookie().remove(ACTIVE_WALLET_KEY);
                 return;

package/dist/esm/src/core.d.ts

@@ -1,8 +1,8 @@
 export * from "./FormoAnalytics";
 export * from "./types";
 export { formofy } from "./initialization";
-export { parsePrivyProperties } from "./privy";
-export type { PrivyUser, PrivyLinkedAccount, PrivyAccountType, PrivyProfileProperties, PrivyWalletInfo, } from "./privy";
+export { parsePrivyProperties, identifyPrivyUser } from "./privy";
+export type { IdentifyPrivyUserOptions, PrivyUser, PrivyLinkedAccount, PrivyAccountType, PrivyProfileProperties, PrivyWalletInfo, } from "./privy";
 export { SolanaManager } from "./solana";
 export { SOLANA_CHAIN_IDS, DEFAULT_SOLANA_CHAIN_ID, isSolanaChainId, } from "./solana";
 export type { SolanaOptions, SolanaCluster } from "./solana";

package/dist/esm/src/core.js

@@ -7,7 +7,7 @@
 export * from "./FormoAnalytics";
 export * from "./types";
 export { formofy } from "./initialization";
-export { parsePrivyProperties } from "./privy";
+export { parsePrivyProperties, identifyPrivyUser } from "./privy";
 export { SolanaManager } from "./solana";
 export { SOLANA_CHAIN_IDS, DEFAULT_SOLANA_CHAIN_ID, isSolanaChainId, } from "./solana";
 //# sourceMappingURL=core.js.map

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

@@ -18,15 +18,21 @@ declare class EventFactory implements IEventFactory {
     private getLanguage;
     private getLibraryVersion;
     private isExcludedQueryParam;
+    /**
+     * Normalize URL paths for analytics aggregation by stripping trailing slashes
+     * from non-root paths. Query strings and hash fragments are preserved by
+     * mutating only the URL pathname.
+     */
+    private normalizeUrlPath;
     /**
      * Strip excluded (sensitive) query parameters from a URL in place. Only the
      * query string is touched; the path and hash/fragment are left as-is.
      */
     private redactQueryParams;
     /**
-     * Return the given absolute URL with excluded query parameters removed. The
-     * input is returned unchanged when it is empty or cannot be parsed (e.g. an
-     * empty referrer).
+     * Return the given absolute URL with excluded query parameters removed and
+     * trailing slashes stripped from non-root paths. The input is returned
+     * unchanged when it is empty or cannot be parsed (e.g. an empty referrer).
      */
     private redactUrl;
     private extractUTMParameters;
@@ -35,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.
      */