@formo/analytics 1.33.1 → 1.34.1

package/dist/cjs/src/privy/utils.js

@@ -2,14 +2,134 @@
 /**
  * Utility functions for extracting profile properties from Privy user objects.
  */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parsePrivyProperties = parsePrivyProperties;
+exports.identifyPrivyUser = identifyPrivyUser;
+var logger_1 = require("../logger");
+/**
+ * Whether a Privy linked account is a usable wallet - an EVM/Solana wallet or
+ * smart wallet with an address.
+ */
+function isPrivyWalletAccount(account) {
+    return ((account.type === "wallet" || account.type === "smart_wallet") &&
+        !!account.address);
+}
+/**
+ * Coerce a Privy timestamp to epoch milliseconds, tolerating the forms a
+ * `PrivyUser` can actually arrive in: a `Date` (React SDK), an ISO string or
+ * epoch number (REST API / JSON round-trip). Returns undefined for anything
+ * unparseable rather than throwing or emitting NaN.
+ */
+function toEpochMillis(value) {
+    if (value instanceof Date) {
+        var time = value.getTime();
+        return Number.isNaN(time) ? undefined : time;
+    }
+    if (typeof value === "number") {
+        // Privy's REST API reports seconds; a Date-derived value is milliseconds.
+        // Anything below this threshold is far too old to be a millisecond
+        // timestamp, so treat it as seconds.
+        if (!Number.isFinite(value))
+            return undefined;
+        return value < 1e11 ? value * 1000 : value;
+    }
+    if (typeof value === "string") {
+        var parsed = Date.parse(value);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    return undefined;
+}
+/** A 0x-prefixed 20-byte hex string (prefix and hex are case-insensitive). */
+var EVM_ADDRESS_RE = /^0x[0-9a-f]{40}$/i;
+/**
+ * Compare two wallet addresses for equality. EVM addresses are hex and
+ * case-insensitive, so they are folded to lowercase; all other chains (notably
+ * Solana, whose Base58 addresses are case-sensitive) are compared exactly, so a
+ * case difference never matches the wrong wallet.
+ */
+function sameAddress(a, b) {
+    return EVM_ADDRESS_RE.test(a) && EVM_ADDRESS_RE.test(b)
+        ? a.toLowerCase() === b.toLowerCase()
+        : a === b;
+}
 /**
  * Extract profile properties and wallet addresses from a Privy user object.
  *
  * Parses the Privy user's linked accounts into a flat properties object
  * (email, social accounts, etc.) and extracts all linked wallet addresses.
  *
+ * For most apps prefer the {@link identifyPrivyUser} one-liner, which builds on
+ * this function and also forwards per-wallet metadata and handles event
+ * attribution. Use `parsePrivyProperties` directly only for advanced/custom
+ * flows.
+ *
  * @param user - The Privy user object from `usePrivy()`
  * @returns An object with `properties` and `wallets`
  *
@@ -28,17 +148,28 @@ exports.parsePrivyProperties = parsePrivyProperties;
  * ```
  */
 function parsePrivyProperties(user) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
     var accounts = user.linkedAccounts || [];
-    // Extract profile properties
+    // Extract profile properties.
+    //
+    // Privy's React SDK types `createdAt` as a Date, but PrivyUser is a
+    // structural interface - a user object from the REST API, or one that made a
+    // JSON round-trip through a cache, carries a string or epoch number instead.
+    // Calling .getTime() on those throws, and identify()'s outer catch would
+    // swallow it, so the whole one-liner would silently emit nothing. Normalize
+    // instead of trusting the declared type.
     var properties = {
         privyDid: user.id,
-        privyCreatedAt: (_a = user.createdAt) === null || _a === void 0 ? void 0 : _a.getTime(),
+        privyCreatedAt: toEpochMillis(user.createdAt),
     };
     // Email
-    if ((_b = user.email) === null || _b === void 0 ? void 0 : _b.address) {
+    if ((_a = user.email) === null || _a === void 0 ? void 0 : _a.address) {
         properties.email = user.email.address;
     }
+    // Phone
+    if ((_b = user.phone) === null || _b === void 0 ? void 0 : _b.number) {
+        properties.phone = user.phone.number;
+    }
     // Social accounts - extract usernames/identifiers
     if ((_c = user.apple) === null || _c === void 0 ? void 0 : _c.email) {
         properties.apple = user.apple.email;
@@ -73,7 +204,10 @@ function parsePrivyProperties(user) {
     if ((_o = user.tiktok) === null || _o === void 0 ? void 0 : _o.username) {
         properties.tiktok = user.tiktok.username;
     }
-    if ((_p = user.twitter) === null || _p === void 0 ? void 0 : _p.username) {
+    if ((_p = user.twitch) === null || _p === void 0 ? void 0 : _p.username) {
+        properties.twitch = user.twitch.username;
+    }
+    if ((_q = user.twitter) === null || _q === void 0 ? void 0 : _q.username) {
         properties.twitter = user.twitter.username;
     }
     // Fallback to linkedAccounts if convenience accessors are not populated
@@ -83,6 +217,13 @@ function parsePrivyProperties(user) {
             properties.email = emailAccount.address;
         }
     }
+    if (!properties.phone) {
+        // A phone account carries the value in `number`, not `address`.
+        var phoneAccount = accounts.find(function (a) { return a.type === "phone"; });
+        if (phoneAccount === null || phoneAccount === void 0 ? void 0 : phoneAccount.number) {
+            properties.phone = phoneAccount.number;
+        }
+    }
     if (!properties.apple) {
         var appleAccount = accounts.find(function (a) { return a.type === "apple_oauth"; });
         if (appleAccount === null || appleAccount === void 0 ? void 0 : appleAccount.email) {
@@ -155,12 +296,26 @@ function parsePrivyProperties(user) {
             properties.tiktok = tiktokAccount.username;
         }
     }
+    if (!properties.twitch) {
+        var twitchAccount = accounts.find(function (a) { return a.type === "twitch_oauth"; });
+        if (twitchAccount === null || twitchAccount === void 0 ? void 0 : twitchAccount.username) {
+            properties.twitch = twitchAccount.username;
+        }
+        else if (twitchAccount === null || twitchAccount === void 0 ? void 0 : twitchAccount.email) {
+            properties.twitch = twitchAccount.email;
+        }
+    }
     if (!properties.twitter) {
         var twitterAccount = accounts.find(function (a) { return a.type === "twitter_oauth"; });
         if (twitterAccount === null || twitterAccount === void 0 ? void 0 : twitterAccount.username) {
             properties.twitter = twitterAccount.username;
         }
     }
+    // Custom auth: the app's own user id for this Privy user.
+    var customAuthAccount = accounts.find(function (a) { return a.type === "custom_auth"; });
+    if (customAuthAccount === null || customAuthAccount === void 0 ? void 0 : customAuthAccount.customUserId) {
+        properties.customUserId = customAuthAccount.customUserId;
+    }
     // Use OAuth emails as fallback for email if still blank
     // Priority: email -> google -> apple -> linkedin
     if (!properties.email) {
@@ -174,18 +329,222 @@ function parsePrivyProperties(user) {
             properties.email = properties.linkedin;
         }
     }
-    // Extract wallet addresses
-    var wallets = accounts
-        .filter(function (a) { return (a.type === "wallet" || a.type === "smart_wallet") && a.address; })
-        .map(function (a) {
-        var _a, _b;
-        return ({
-            address: a.address,
-            walletClient: (_a = (a.walletClientType || a.walletClient)) !== null && _a !== void 0 ? _a : undefined,
-            chainType: (_b = a.chainType) !== null && _b !== void 0 ? _b : undefined,
-            isEmbedded: a.walletClientType === "privy" || a.walletClient === "privy",
+    // Extract wallet addresses. `fromCrossApp` is internal bookkeeping for the
+    // dedup below and is stripped from the returned wallets.
+    var wallets = [];
+    for (var _i = 0, accounts_1 = accounts; _i < accounts_1.length; _i++) {
+        var account = accounts_1[_i];
+        if (isPrivyWalletAccount(account)) {
+            wallets.push({
+                address: account.address,
+                walletClient: (_r = (account.walletClientType || account.walletClient)) !== null && _r !== void 0 ? _r : undefined,
+                chainType: (_s = account.chainType) !== null && _s !== void 0 ? _s : undefined,
+                isEmbedded: account.walletClientType === "privy" ||
+                    account.walletClient === "privy",
+            });
+            continue;
+        }
+        // A cross_app account (e.g. Abstract Global Wallet) has no top-level
+        // address - its wallets live in `embeddedWallets`/`smartWallets`. They are
+        // still wallets the user owns, so identify them for clustering too.
+        if (account.type === "cross_app") {
+            var crossAppWallets = __spreadArray(__spreadArray([], (account.embeddedWallets || []), true), (account.smartWallets || []), true);
+            for (var _u = 0, crossAppWallets_1 = crossAppWallets; _u < crossAppWallets_1.length; _u++) {
+                var w = crossAppWallets_1[_u];
+                if (!(w === null || w === void 0 ? void 0 : w.address))
+                    continue;
+                wallets.push({
+                    address: w.address,
+                    walletClient: "cross_app",
+                    chainType: (_t = w.chainType) !== null && _t !== void 0 ? _t : undefined,
+                    isEmbedded: true,
+                    fromCrossApp: true,
+                });
+            }
+        }
+    }
+    // Deduplicate: the same address can appear as both a `wallet` and a
+    // `smart_wallet`/cross-app entry, and identifying it twice would emit a
+    // redundant event (and, for the active wallet, a redundant promotion).
+    //
+    // Which duplicate wins is not just first-come: a cross_app entry carries only
+    // an address (so it's recorded as `cross_app`/embedded by default), while a
+    // top-level wallet entry carries the real walletClient, chainType, and
+    // embedded classification. Prefer the richer entry regardless of the order
+    // Privy happened to list the accounts in, so the metadata - and the
+    // last-external active-wallet fallback, which keys on isEmbedded - don't
+    // depend on account ordering.
+    var indexByAddress = new Map();
+    var deduped = [];
+    for (var _v = 0, wallets_1 = wallets; _v < wallets_1.length; _v++) {
+        var wallet = wallets_1[_v];
+        var key = EVM_ADDRESS_RE.test(wallet.address)
+            ? wallet.address.toLowerCase()
+            : wallet.address;
+        var existingIndex = indexByAddress.get(key);
+        if (existingIndex === undefined) {
+            indexByAddress.set(key, deduped.length);
+            deduped.push(wallet);
+            continue;
+        }
+        // Only upgrade a placeholder cross-app entry to a real wallet entry; never
+        // downgrade, and never let a second cross-app entry replace anything. The
+        // position is kept so wallet order stays stable.
+        if (!wallet.fromCrossApp && deduped[existingIndex].fromCrossApp) {
+            deduped[existingIndex] = wallet;
+        }
+    }
+    var uniqueWallets = deduped.map(function (_a) {
+        var _fromCrossApp = _a.fromCrossApp, info = __rest(_a, ["fromCrossApp"]);
+        return info;
+    });
+    return { properties: properties, wallets: uniqueWallets };
+}
+/**
+ * Identify every wallet linked to a Privy user under that user's Privy DID.
+ *
+ * This is the one-liner replacement for hand-rolling a loop over
+ * {@link parsePrivyProperties}. For each linked wallet it calls
+ * `analytics.identify({ address, userId: user.id }, …)` with the shared
+ * profile properties plus that wallet's `wallet_client`, `chain_type`, and
+ * `is_embedded` metadata. Because every wallet is tagged with the same Privy
+ * `userId`, Formo can cluster them server-side into a single user.
+ *
+ * Attribution: only the active wallet (see
+ * {@link IdentifyPrivyUserOptions.activeAddress}) promotes the SDK's current
+ * address/user; every other linked wallet is recorded purely for clustering and
+ * does not repoint attribution. Because the clustering identifies don't touch
+ * active state, a connected wallet that isn't linked in Privy is left untouched
+ * rather than overwritten. This does not change the public `identify()` API.
+ *
+ * Before emitting, it reconciles the SDK's chain id with the active wallet's
+ * chain namespace (clearing a stale EVM chain id when a Solana wallet becomes
+ * active, and vice versa), so identifies aren't dropped by an `excludeChains`
+ * gate and later events aren't paired with the wrong chain. This happens here,
+ * so the direct helper and the `formo.identify(user)` form
+ * behave identically.
+ *
+ * Returns the active linked wallet's `{ address, chainType }` (the one now
+ * owning attribution), or `undefined` when no linked wallet matched the
+ * requested active address (or the user had no wallets).
+ *
+ * All linked wallet addresses used here come from `user.linkedAccounts`, which
+ * is fully available on the frontend from Privy's `usePrivy()` hook.
+ *
+ * Note: `identify()` is keyed on a wallet address, so a Privy user with no
+ * linked wallet is a no-op (nothing is emitted). Attaching a user identity that
+ * has no wallet is out of scope for this address-keyed helper.
+ *
+ * @param analytics - The Formo analytics instance (e.g. from `useFormo()`)
+ * @param user - The Privy user object from `usePrivy()`
+ * @param options - See {@link IdentifyPrivyUserOptions}
+ *
+ * @example
+ * ```ts
+ * import { identifyPrivyUser } from '@formo/analytics';
+ *
+ * const { user } = usePrivy();
+ * const { wallets } = useWallets();
+ * if (user) {
+ *   // activeAddress is optional - omit it if the SDK already tracks the
+ *   // connected wallet via a wagmi/EIP-1193 connect.
+ *   await identifyPrivyUser(formo, user, {
+ *     activeAddress: wallets[0]?.address,
+ *   });
+ * }
+ * ```
+ */
+function identifyPrivyUser(analytics_1, user_1) {
+    return __awaiter(this, arguments, void 0, function (analytics, user, options) {
+        var target, _a, properties, wallets, baseProperties, activeWallet, identify, _i, wallets_2, wallet, walletProperties;
+        var _b, _c, _d, _e;
+        if (options === void 0) { options = {}; }
+        return __generator(this, function (_f) {
+            switch (_f.label) {
+                case 0:
+                    if (!analytics || !user)
+                        return [2 /*return*/, undefined];
+                    target = analytics;
+                    // If tracking is suppressed for this visitor/route (opt-out / timezone / host /
+                    // path), do nothing. The inner identify() calls would each be gated anyway,
+                    // but the chain reconciliation below runs BEFORE them - so without this guard
+                    // it would clear an excluded chain id while no identify actually happens,
+                    // leaving later events on an allowed route unable to apply `excludeChains`.
+                    if ((_b = target.isTrackingSuppressed) === null || _b === void 0 ? void 0 : _b.call(target))
+                        return [2 /*return*/, undefined];
+                    _a = parsePrivyProperties(user), properties = _a.properties, wallets = _a.wallets;
+                    // identify() is keyed on a wallet address, so with no linked wallets there is
+                    // nothing to attach the Privy identity to. Log it so a walletless user (or a
+                    // pre-wallet account-creation flow) doesn't silently disappear.
+                    if (wallets.length === 0) {
+                        logger_1.logger.info("identifyPrivyUser: user has no linked wallets; nothing to identify", user.id);
+                        return [2 /*return*/, undefined];
+                    }
+                    baseProperties = __assign(__assign({}, properties), options.properties);
+                    activeWallet = resolveActiveWallet(wallets, (_c = options.activeAddress) !== null && _c !== void 0 ? _c : target.currentAddress, (_d = user.wallet) === null || _d === void 0 ? void 0 : _d.address);
+                    // Reconcile the chain BEFORE emitting any identify. identify() runs each event
+                    // through the tracking gate (which enforces `excludeChains` against the
+                    // current chain id); if the active wallet is on a different chain namespace
+                    // than the stale current chain id (e.g. a Solana wallet while an EVM chain was
+                    // current, and that EVM chain is excluded), reconciling first prevents the
+                    // clustering identifies from being silently dropped. Doing it here - rather
+                    // than in the identify(user,{privy:true}) dispatch - means the direct
+                    // identifyPrivyUser() entry point gets the same treatment.
+                    // Pass the address too: Privy omits chainType on smart_wallet and cross_app
+                    // entries, and a 0x address is enough to identify the EVM namespace.
+                    (_e = target.syncPrivyActiveChain) === null || _e === void 0 ? void 0 : _e.call(target, activeWallet === null || activeWallet === void 0 ? void 0 : activeWallet.chainType, activeWallet === null || activeWallet === void 0 ? void 0 : activeWallet.address);
+                    identify = target.identify.bind(analytics);
+                    _i = 0, wallets_2 = wallets;
+                    _f.label = 1;
+                case 1:
+                    if (!(_i < wallets_2.length)) return [3 /*break*/, 4];
+                    wallet = wallets_2[_i];
+                    walletProperties = __assign(__assign({}, baseProperties), { is_embedded: wallet.isEmbedded });
+                    if (wallet.walletClient)
+                        walletProperties.wallet_client = wallet.walletClient;
+                    if (wallet.chainType)
+                        walletProperties.chain_type = wallet.chainType;
+                    return [4 /*yield*/, identify({
+                            address: wallet.address,
+                            userId: user.id,
+                            setActive: wallet === activeWallet,
+                        }, walletProperties)];
+                case 2:
+                    _f.sent();
+                    _f.label = 3;
+                case 3:
+                    _i++;
+                    return [3 /*break*/, 1];
+                case 4: return [2 /*return*/, activeWallet
+                        ? { address: activeWallet.address, chainType: activeWallet.chainType }
+                        : undefined];
+            }
         });
     });
-    return { properties: properties, wallets: wallets };
+}
+/**
+ * Choose the linked wallet that should own event attribution.
+ *
+ * An explicit `activeAddress` (a caller override, or the SDK's already-connected
+ * wallet) is matched strictly and never falls back: a connected wallet that is
+ * not in `linkedAccounts` resolves to `undefined`, so the sync leaves the
+ * current wallet untouched. With no active address, prefer Privy's surfaced
+ * primary (`user.wallet`), then a best-effort guess (embedded wallets first, so
+ * the last external wallet). Address comparison is chain-appropriate so Solana
+ * casing isn't mismatched.
+ */
+function resolveActiveWallet(wallets, activeAddress, primaryAddress) {
+    if (activeAddress) {
+        return wallets.find(function (w) { return sameAddress(w.address, activeAddress); });
+    }
+    if (primaryAddress) {
+        var primary = wallets.find(function (w) { return sameAddress(w.address, primaryAddress); });
+        if (primary)
+            return primary;
+    }
+    var external = wallets.filter(function (w) { return !w.isEmbedded; });
+    return external.length > 0
+        ? external[external.length - 1]
+        : wallets[wallets.length - 1];
 }
 //# sourceMappingURL=utils.js.map

package/dist/cjs/src/session/index.d.ts

@@ -4,6 +4,7 @@
  * Handles tracking of detected wallets and identified wallet-address pairs
  * using cookies to maintain state across page loads within a session.
  */
+import type { IFormoEventProperties } from "../types/events";
 /**
  * Cookie keys for session tracking
  * NOTE: These values must match the original constants in constants/base.ts
@@ -29,25 +30,91 @@ export interface IFormoAnalyticsSession {
      * Check if a wallet-address pair has been identified in this session
      * @param address The wallet address
      * @param rdns The reverse domain name (RDNS) of the wallet provider
+     * @param userId Optional external user ID (e.g. a Privy DID). When provided,
+     *   it is folded into the dedup key so attaching a new user ID to an
+     *   already-identified wallet re-emits instead of being silently deduped.
+     * @param properties Optional identify properties. Fingerprinted into the
+     *   dedup key so an identify whose properties have *changed* (e.g. a Privy
+     *   user linked a new social account) re-emits, while an unchanged repeat
+     *   still dedupes.
      */
-    isWalletIdentified(address: string, rdns: string): boolean;
+    isWalletIdentified(address: string, rdns: string, userId?: string, properties?: IFormoEventProperties): boolean;
     /**
      * Mark a wallet-address pair as identified in this session
      * @param address The wallet address
      * @param rdns The reverse domain name (RDNS) of the wallet provider
+     * @param userId Optional external user ID (e.g. a Privy DID). See
+     *   {@link isWalletIdentified} for how it affects the dedup key.
+     * @param properties Optional identify properties. See
+     *   {@link isWalletIdentified}.
      */
-    markWalletIdentified(address: string, rdns: string): void;
+    markWalletIdentified(address: string, rdns: string, userId?: string, properties?: IFormoEventProperties): void;
 }
 export declare class FormoAnalyticsSession implements IFormoAnalyticsSession {
     /**
-     * Generate a unique key for wallet identification tracking
-     * Combines address and RDNS to track specific wallet-address combinations
+     * Generate a unique key for wallet identification tracking.
+     *
+     * Combines address, RDNS, and (optionally) the external user ID and a
+     * fingerprint of the identify's properties, so the key identifies a specific
+     * wallet-user-profile combination rather than just an address.
+     *
+     * Folding the user ID in means the same wallet identified first anonymously
+     * and later with a user ID (e.g. after a Privy login attaches a DID) produces
+     * two distinct keys, so the second identify is not deduped.
+     *
+     * Folding the properties hash in means a *changed* profile re-emits. This
+     * matters for account linking: a Privy user who links a Google account keeps
+     * the same wallets and the same DID, so without the hash every already-seen
+     * wallet would dedupe and the new `google` property would never reach Formo
+     * until the session expired. An identify repeated with identical properties
+     * still dedupes, so this does not turn a re-render into an event.
+     *
+     * Key shapes, by component count - each is unambiguous, so they cannot
+     * collide with one another:
+     *
+     * | Components | Shape | When |
+     * | --- | --- | --- |
+     * | 1 | `address` | no rdns, no userId, no properties |
+     * | 2 | `address:rdns` | rdns only |
+     * | 3 | `address:rdns:userId` | userId, no properties |
+     * | 4 | `address:rdns:userId:hash` | properties present |
+     *
+     * Shapes 1 and 2 are unchanged from before user IDs and property hashes
+     * existed, so keys already stored in browsers still match (backward
+     * compatible). An identify that carries properties moves to shape 4, so the
+     * first identify after an upgrade re-emits once per wallet - a one-off, and
+     * the correct outcome, since those properties were never recorded under the
+     * new key.
      *
      * @param address The wallet address
      * @param rdns The reverse domain name of the wallet provider
+     * @param userId Optional external user ID (e.g. a Privy DID)
+     * @param properties Optional identify properties, fingerprinted into the key
      * @returns A unique identification key
      */
     private generateIdentificationKey;
+    /**
+     * Build the dedup key plus the **identity prefix** it belongs to.
+     *
+     * The identity prefix is the key with the properties hash stripped -
+     * `address:rdns:userId` - i.e. *which wallet-user this is*, independent of
+     * *what profile it last had*. `markWalletIdentified` uses it to drop that
+     * identity's previous state before storing the new one, which matters twice:
+     *
+     * - **Reversion.** Keeping every state seen would make dedup mean "have I
+     *   ever seen this exact profile", so a profile that goes A → B → A (link
+     *   then unlink an account) would find the old A key and emit nothing. Dedup
+     *   should mean "is this the same as this wallet's *last* identify", so only
+     *   the current state is retained.
+     * - **Growth.** Otherwise each profile change adds a key per wallet, and an
+     *   8-wallet user linking a few accounts would push the cookie into eviction.
+     *   Superseding keeps it at one entry per wallet-user.
+     *
+     * The prefix is only defined for keys that have a userId and/or a properties
+     * hash (3+ components). The legacy 1- and 2-component shapes are the whole
+     * identity already, so there is nothing to supersede.
+     */
+    private buildIdentificationKey;
     /**
      * Check if a wallet provider has been detected in this session
      *
@@ -69,7 +136,7 @@ export declare class FormoAnalyticsSession implements IFormoAnalyticsSession {
      * @param rdns The reverse domain name of the wallet provider
      * @returns true if this wallet-address pair has been identified
      */
-    isWalletIdentified(address: string, rdns: string): boolean;
+    isWalletIdentified(address: string, rdns: string, userId?: string, properties?: IFormoEventProperties): boolean;
     /**
      * Mark a wallet-address combination as identified in this session
      * Prevents duplicate identification events from being emitted
@@ -77,6 +144,6 @@ export declare class FormoAnalyticsSession implements IFormoAnalyticsSession {
      * @param address The wallet address
      * @param rdns The reverse domain name of the wallet provider
      */
-    markWalletIdentified(address: string, rdns: string): void;
+    markWalletIdentified(address: string, rdns: string, userId?: string, properties?: IFormoEventProperties): void;
 }
 //# sourceMappingURL=index.d.ts.map