@formo/analytics 1.33.1 → 1.34.1

package/dist/cjs/src/session/index.js

@@ -21,6 +21,172 @@ exports.FormoAnalyticsSession = exports.SESSION_WALLET_IDENTIFIED_KEY = exports.
 var storage_1 = require("../storage");
 var cookiePolicy_1 = require("../storage/cookiePolicy");
 var logger_1 = require("../logger");
+/**
+ * Serialize a value so that equal values always produce the same string,
+ * regardless of object key insertion order.
+ *
+ * `JSON.stringify` preserves insertion order, so `{a:1,b:2}` and `{b:2,a:1}`
+ * would hash differently and re-emit an identify that carries identical
+ * properties. Object keys are therefore sorted; arrays keep their order, since
+ * order is meaningful there.
+ *
+ * **This function must never throw.** It runs inside `identify()` *after* the
+ * active address/user have been updated, so a throw would leave the SDK with
+ * mutated identity state and no emitted event. `JSON.stringify` throws on
+ * circular references and on `BigInt` - both realistic here, since a web3 app
+ * can easily pass a token balance (`123n`) or a wallet object with a back
+ * reference in `properties`. Every such case is therefore handled explicitly
+ * and degrades to a stable marker instead of an exception.
+ *
+ * Totality here is only about *dedup*: it guarantees the fingerprint step can't
+ * be what loses an identify. It does **not** make such values sendable - the
+ * event queue still serializes with native `JSON.stringify`, so a `BigInt` or
+ * circular value in `properties` fails downstream exactly as it does for
+ * `track()`. That is a separate, pre-existing SDK-wide limitation.
+ *
+ * It mirrors `JSON.stringify`'s own value semantics so the fingerprint tracks
+ * **what actually goes on the wire**, not what happens to be in the object:
+ *
+ * - `undefined`, functions, and symbols are *omitted* as object properties and
+ *   become `null` as array elements, exactly as JSON does. Two property sets
+ *   that serialize identically must fingerprint identically, or dedup emits a
+ *   second identify carrying a byte-identical payload.
+ * - `null` stays `null`, so a real value → `null` update is never mistaken for
+ *   an omitted key.
+ * - `NaN`/`Infinity` become `null`, because that is what is sent.
+ * - `toJSON()` is honored, so `Date` and `URL` reflect their serialized form
+ *   rather than their (often empty) enumerable keys.
+ * - `Map`/`Set` have no enumerable own properties and no `toJSON`, so they send
+ *   as `{}` - and therefore canonicalize as `{}`.
+ *
+ * The exceptions are the two things JSON *cannot* represent: `BigInt` and
+ * circular references both make `JSON.stringify` throw. They get distinct
+ * markers instead, because this function must never throw - it runs inside
+ * `identify()` *after* the active address/user have been updated, so a throw
+ * would leave the SDK with mutated identity state and no emitted event.
+ *
+ * Totality here is only about *dedup*: it guarantees the fingerprint step can't
+ * be what loses an identify. It does **not** make such values sendable - the
+ * event queue still serializes with native `JSON.stringify`, so a `BigInt` or
+ * circular value in `properties` fails downstream exactly as it does for
+ * `track()`. That is a separate, pre-existing SDK-wide limitation.
+ *
+ * Returns `undefined` when JSON would omit the value entirely.
+ */
+function stableStringify(value, seen) {
+    if (seen === void 0) { seen = new Set(); }
+    // JSON omits these as object properties; array elements are mapped to "null"
+    // by the caller below.
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "function")
+        return undefined;
+    if (typeof value === "symbol")
+        return undefined;
+    if (value === null)
+        return "null";
+    // JSON.stringify throws on BigInt, so it has no wire form to mirror.
+    if (typeof value === "bigint")
+        return "bigint:".concat(value.toString());
+    if (typeof value === "number") {
+        // NaN and Infinity are sent as null.
+        return Number.isFinite(value) ? JSON.stringify(value) : "null";
+    }
+    if (typeof value !== "object") {
+        // Remaining primitives: string, boolean.
+        return JSON.stringify(value);
+    }
+    // Cycle guard: a repeated reference within the current path is replaced by a
+    // marker rather than recursing forever. JSON.stringify would throw here.
+    if (seen.has(value))
+        return '"[circular]"';
+    seen.add(value);
+    try {
+        // JSON calls toJSON() before inspecting the value, so do it first. This is
+        // what makes an invalid Date canonicalize as null (Date.prototype.toJSON
+        // returns null rather than throwing) and a URL reflect its href.
+        var maybeToJSON = value.toJSON;
+        if (typeof maybeToJSON === "function") {
+            return stableStringify(maybeToJSON.call(value), seen);
+        }
+        if (Array.isArray(value)) {
+            return "[".concat(value
+                .map(function (item) { var _a; return (_a = stableStringify(item, seen)) !== null && _a !== void 0 ? _a : "null"; })
+                .join(","), "]");
+        }
+        // Everything else, Map and Set included, serializes from its enumerable own
+        // properties. Keys are sorted so insertion order can't change the result.
+        var record = value;
+        var parts = [];
+        for (var _i = 0, _a = Object.keys(record).sort(); _i < _a.length; _i++) {
+            var key = _a[_i];
+            var encoded = stableStringify(record[key], seen);
+            if (encoded === undefined)
+                continue; // JSON omits this property
+            parts.push("".concat(JSON.stringify(key), ":").concat(encoded));
+        }
+        return "{".concat(parts.join(","), "}");
+    }
+    finally {
+        // Only guard against cycles, not repeated siblings: the same object used
+        // twice in one payload must serialize the same both times.
+        seen.delete(value);
+    }
+}
+/**
+ * Short, stable fingerprint of an identify's properties (two FNV-1a lanes,
+ * base36).
+ *
+ * Folded into the dedup key so that re-identifying a known wallet with *changed*
+ * properties re-emits, while an unchanged repeat still dedupes. Kept short
+ * because every key is stored in a size-bounded cookie.
+ *
+ * Two independent lanes (different offset bases, combined into ~64 bits) rather
+ * than one: a single 32-bit lane collides readily - `{"x":"xefn1fnkq0"}` and
+ * `{"x":"filot3n704"}` both hash to `1mgjpo5` - and a collision here silently
+ * suppresses a legitimately changed profile for the rest of the session. At 64
+ * bits that is no longer a practical concern, for six more characters per key.
+ */
+function fingerprintProperties(properties) {
+    var _a;
+    if (!properties)
+        return undefined;
+    var serialized;
+    try {
+        // Canonicalize first, then decide emptiness from the result. Anything that
+        // serializes to `{}` - a literal `{}`, or an object whose every value JSON
+        // omits - carries no wire payload, so it keeps the legacy no-hash key shape
+        // rather than getting a hash of "{}". Doing this inside the guard matters:
+        // reading properties can run user code (a Proxy with a throwing ownKeys
+        // trap), and this whole function must be total.
+        var canonical = stableStringify(properties);
+        if (canonical === undefined || canonical === "{}")
+            return undefined;
+        serialized = canonical;
+    }
+    catch (error) {
+        // stableStringify handles every value type it knows about, but reading a
+        // property can still run arbitrary user code (a throwing getter, an exotic
+        // Proxy). Identity state has already been updated by the time we get here,
+        // so failing closed to a constant is the safe outcome: dedup degrades to
+        // the pre-fingerprint behavior (identify once per session for this wallet)
+        // instead of the whole identify being swallowed by the catch in identify().
+        (_a = logger_1.logger.warn) === null || _a === void 0 ? void 0 : _a.call(logger_1.logger, "Session: failed to fingerprint identify properties", error);
+        return "nohash";
+    }
+    var lane1 = 0x811c9dc5;
+    var lane2 = 0x01000193;
+    for (var i = 0; i < serialized.length; i++) {
+        var code = serialized.charCodeAt(i);
+        lane1 ^= code;
+        lane1 = Math.imul(lane1, 0x01000193);
+        // A second lane with a different seed and multiplier, fed the position as
+        // well as the character, so the two lanes don't move together.
+        lane2 ^= code + i;
+        lane2 = Math.imul(lane2, 0x85ebca6b);
+    }
+    return "".concat((lane1 >>> 0).toString(36)).concat((lane2 >>> 0).toString(36));
+}
 /**
  * Cookie keys for session tracking
  * NOTE: These values must match the original constants in constants/base.ts
@@ -38,20 +204,130 @@ exports.SESSION_WALLET_IDENTIFIED_KEY = "wallet-identified";
  * Session data expires at end of day (86400 seconds).
  */
 var MAX_SESSION_ENTRIES = 20;
+/**
+ * Byte budget for the identified-wallet cookie, measured on the value as the
+ * browser actually stores it.
+ *
+ * A Privy user can identify far more than 20 wallets in one session (an 8+
+ * wallet user is the motivating case), so a fixed entry count would evict
+ * `(wallet, userId)` keys and let a later sync re-emit them. Instead we bound
+ * the store by serialized size and evict oldest only when it would overflow the
+ * cookie - so every identity that fits is retained.
+ *
+ * The budget must be applied to the **encoded** length. Key components are
+ * already percent-encoded, and `CookieStorage.set()` then encodes the whole
+ * joined value again, so `%3A` becomes `%253A` and each `,` separator becomes
+ * `%2C`. Measuring the raw string underestimates what is written: 37 realistic
+ * DID-bearing keys measure 3500 raw but 3956 encoded, and a non-ASCII external
+ * user id inflates far more than that. Overflowing makes the browser reject the
+ * write outright, so nothing is persisted and every identify re-emits for the
+ * rest of the session - the exact failure the store exists to prevent.
+ */
+var MAX_COOKIE_BYTES = 4096;
+/** Reserve for the cookie name plus path/expires/SameSite/Secure attributes. */
+var COOKIE_OVERHEAD_RESERVE = 512;
+var MAX_IDENTIFIED_ENCODED_BYTES = MAX_COOKIE_BYTES - COOKIE_OVERHEAD_RESERVE;
+/** Length of a cookie value as written, i.e. after CookieStorage encodes it. */
+function encodedCookieLength(value) {
+    return encodeURIComponent(value).length;
+}
 var FormoAnalyticsSession = /** @class */ (function () {
     function FormoAnalyticsSession() {
     }
     /**
-     * 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
      */
-    FormoAnalyticsSession.prototype.generateIdentificationKey = function (address, rdns) {
-        // If rdns is missing, use address-only key as fallback for empty identifies
-        return rdns ? "".concat(address, ":").concat(rdns) : address;
+    FormoAnalyticsSession.prototype.generateIdentificationKey = function (address, rdns, userId, properties) {
+        return this.buildIdentificationKey(address, rdns, userId, properties).key;
+    };
+    /**
+     * 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.
+     */
+    FormoAnalyticsSession.prototype.buildIdentificationKey = function (address, rdns, userId, properties) {
+        // Percent-encode each component before joining. The identified-wallet list
+        // is persisted comma-joined in a cookie and later split on commas, so a raw
+        // comma in an arbitrary external userId would corrupt the key and defeat
+        // dedup (the same identify would re-emit on every call). Encoding also keeps
+        // the ":" separator unambiguous. Addresses and RDNS contain no reserved
+        // characters, so their encoded form is unchanged - existing stored keys
+        // still match (backward compatible).
+        // An identify with no properties keeps the pre-hash key shape, so the
+        // common `identify({ address })` call is unaffected.
+        var propertiesHash = fingerprintProperties(properties);
+        var parts = [encodeURIComponent(address)];
+        if (userId || propertiesHash) {
+            // Once any later slot is set, always emit the intervening slots (even when
+            // empty) so the tuple has a fixed shape. Otherwise a userId that happens to
+            // equal a provider RDNS (e.g. "io.metamask") would produce the same key as
+            // an anonymous `address:rdns` identify and be wrongly deduped. userId and
+            // hash keys are new, so this shape has no backward-compat cost.
+            parts.push(encodeURIComponent(rdns || ""));
+            parts.push(encodeURIComponent(userId || ""));
+            var identityPrefix = parts.join(":");
+            if (propertiesHash)
+                parts.push(propertiesHash);
+            return { key: parts.join(":"), identityPrefix: identityPrefix };
+        }
+        if (rdns) {
+            parts.push(encodeURIComponent(rdns));
+        }
+        return { key: parts.join(":") };
     };
     /**
      * Check if a wallet provider has been detected in this session
@@ -90,8 +366,8 @@ var FormoAnalyticsSession = /** @class */ (function () {
      * @param rdns The reverse domain name of the wallet provider
      * @returns true if this wallet-address pair has been identified
      */
-    FormoAnalyticsSession.prototype.isWalletIdentified = function (address, rdns) {
-        var identifiedKey = this.generateIdentificationKey(address, rdns);
+    FormoAnalyticsSession.prototype.isWalletIdentified = function (address, rdns, userId, properties) {
+        var identifiedKey = this.generateIdentificationKey(address, rdns, userId, properties);
         var cookieValue = (0, storage_1.cookie)().get(exports.SESSION_WALLET_IDENTIFIED_KEY);
         var identifiedWallets = (cookieValue === null || cookieValue === void 0 ? void 0 : cookieValue.split(",")) || [];
         var isIdentified = identifiedWallets.includes(identifiedKey);
@@ -109,17 +385,38 @@ var FormoAnalyticsSession = /** @class */ (function () {
      * @param address The wallet address
      * @param rdns The reverse domain name of the wallet provider
      */
-    FormoAnalyticsSession.prototype.markWalletIdentified = function (address, rdns) {
+    FormoAnalyticsSession.prototype.markWalletIdentified = function (address, rdns, userId, properties) {
         var _a;
-        var identifiedKey = this.generateIdentificationKey(address, rdns);
+        var _b = this.buildIdentificationKey(address, rdns, userId, properties), identifiedKey = _b.key, identityPrefix = _b.identityPrefix;
         var identifiedWallets = ((_a = (0, storage_1.cookie)().get(exports.SESSION_WALLET_IDENTIFIED_KEY)) === null || _a === void 0 ? void 0 : _a.split(",")) || [];
         var alreadyExists = identifiedWallets.includes(identifiedKey);
         if (!alreadyExists) {
-            identifiedWallets.push(identifiedKey);
-            if (identifiedWallets.length > MAX_SESSION_ENTRIES) {
-                identifiedWallets.splice(0, identifiedWallets.length - MAX_SESSION_ENTRIES);
+            // Supersede this wallet-user's previous profile state rather than
+            // accumulating one key per state. Without this, a profile that reverts to
+            // an earlier value (link then unlink an account) would match the stale key
+            // and emit nothing, and every profile change would grow the cookie.
+            if (identityPrefix) {
+                identifiedWallets = identifiedWallets.filter(function (entry) {
+                    return entry !== identityPrefix &&
+                        !entry.startsWith("".concat(identityPrefix, ":"));
+                });
             }
+            identifiedWallets.push(identifiedKey);
+            // Bound the stored list by serialized size (not a fixed entry count) so a
+            // many-wallet Privy user's identities all persist, evicting oldest only if
+            // the value would overflow the cookie.
+            //
+            // `shift()` drops the oldest from the front while the new key was pushed
+            // to the back, and the loop stops at one entry, so the just-added key can
+            // never be evicted. A single key is bounded by its components (address +
+            // rdns + external user id + a 13-char hash) and cannot on its own approach
+            // the budget, so there is no oversized-single-entry case to handle.
             var newValue = identifiedWallets.join(",");
+            while (identifiedWallets.length > 1 &&
+                encodedCookieLength(newValue) > MAX_IDENTIFIED_ENCODED_BYTES) {
+                identifiedWallets.shift();
+                newValue = identifiedWallets.join(",");
+            }
             (0, storage_1.cookie)().set(exports.SESSION_WALLET_IDENTIFIED_KEY, newValue, __assign({ 
                 // Expires by the end of the day
                 expires: new Date(Date.now() + 86400 * 1000).toUTCString(), path: "/" }, (0, cookiePolicy_1.getIdentityCookieSecurity)()));

package/dist/cjs/src/solana/SolanaManager.d.ts

@@ -29,7 +29,7 @@ export declare class SolanaManager {
      *
      * @example
      * ```tsx
-     * import { createClient } from '@solana-foundation/framework-kit';
+     * import { createClient, autoDiscover } from '@solana/client';
      *
      * const client = createClient({ endpoint: '...', walletConnectors: autoDiscover() });
      * formo.solana.setStore(client.store);

package/dist/cjs/src/solana/SolanaManager.js

@@ -40,7 +40,7 @@ var SolanaManager = /** @class */ (function () {
      *
      * @example
      * ```tsx
-     * import { createClient } from '@solana-foundation/framework-kit';
+     * import { createClient, autoDiscover } from '@solana/client';
      *
      * const client = createClient({ endpoint: '...', walletConnectors: autoDiscover() });
      * formo.solana.setStore(client.store);

package/dist/cjs/src/solana/storeTypes.d.ts

@@ -1,7 +1,7 @@
 /**
  * Type definitions for framework-kit's zustand store integration.
  *
- * These types mirror the state shape of @solana-foundation/framework-kit's
+ * These types mirror the state shape of framework-kit's
  * vanilla zustand store, allowing the SDK to subscribe to wallet and
  * transaction state changes without wrapping any wallet methods.
  *

package/dist/cjs/src/solana/storeTypes.js

@@ -2,7 +2,7 @@
 /**
  * Type definitions for framework-kit's zustand store integration.
  *
- * These types mirror the state shape of @solana-foundation/framework-kit's
+ * These types mirror the state shape of framework-kit's
  * vanilla zustand store, allowing the SDK to subscribe to wallet and
  * transaction state changes without wrapping any wallet methods.
  *

package/dist/cjs/src/solana/types.d.ts

@@ -54,11 +54,11 @@ export interface SolanaOptions {
      * When provided, wallet connect/disconnect and transaction events are tracked
      * automatically by subscribing to zustand store state changes.
      *
-     * This is the recommended approach for apps using @solana-foundation/framework-kit.
+     * This is the recommended approach for apps using framework-kit.
      *
      * @example
      * ```tsx
-     * import { createClient } from '@solana-foundation/framework-kit';
+     * import { createClient, autoDiscover } from '@solana/client';
      * const client = createClient({ endpoint, walletConnectors: autoDiscover() });
      * const formo = await Formo.init(writeKey, { solana: { store: client.store } });
      * ```

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

@@ -2,6 +2,7 @@ import { LogLevel } from "../logger";
 import { IFormoEventContext, IFormoEventProperties, SignatureStatus, TransactionStatus } from "./events";
 import { EIP1193Provider } from "./provider";
 import { SolanaOptions } from "../solana/types";
+import type { PrivyUser } from "../privy/types";
 export type Nullable<T> = T | null;
 export type ChainID = number;
 export type Address = string;
@@ -51,6 +52,21 @@ export interface IFormoAnalytics {
         function_name?: string;
         function_args?: Record<string, unknown>;
     }, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
+    /**
+     * Privy form. Pass the `usePrivy()` user directly and the SDK identifies
+     * every wallet linked to that Privy account under the user's DID in a single
+     * call, forwarding each wallet's metadata. Only the active wallet (explicit
+     * `activeAddress`, else the already-connected wallet, else Privy's
+     * `user.wallet`) takes over event attribution - the rest are recorded purely
+     * for identity clustering.
+     *
+     * Recognized by shape: a Privy user has a string `id` and no `address`,
+     * while an address-keyed identify always has an `address`.
+     */
+    identify(user: PrivyUser, options?: {
+        activeAddress?: string;
+        properties?: IFormoEventProperties;
+    }): Promise<void>;
     identify(params: {
         address: Address;
         providerName?: string;
@@ -75,7 +91,7 @@ export interface TrackingOptions {
     /**
      * IANA timezone names to opt out of tracking entirely. When the visitor's
      * resolved timezone (via `Intl.DateTimeFormat().resolvedOptions().timeZone`)
-     * matches one of these, no events are enqueued or sent — including `identify`
+     * matches one of these, no events are enqueued or sent - including `identify`
      * and `connect`. Matched case-insensitively against the full timezone string.
      *
      * Note: this is client-side, timezone-derived geolocation. It is best-effort

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

@@ -1,2 +1,2 @@
-export declare const version = "1.30.1";
+export declare const version = "1.34.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/cjs/src/version.js

@@ -3,5 +3,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
 // This file is auto-generated by scripts/update-version.js during npm version
 // Do not edit manually - it will be overwritten
-exports.version = '1.30.1';
+exports.version = '1.34.1';
 //# sourceMappingURL=version.js.map

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

@@ -1,6 +1,7 @@
 import { EIP6963ProviderDetail } from "mipd";
 import { Address, ChainID, Config, EIP1193Provider, IFormoAnalytics, IFormoEventContext, IFormoEventProperties, Options, SignatureStatus, TransactionStatus } from "./types";
 import { SolanaManager } from "./solana/SolanaManager";
+import type { PrivyUser } from "./privy";
 export declare class FormoAnalytics implements IFormoAnalytics {
     readonly writeKey: string;
     options: Options;
@@ -189,23 +190,50 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * // Basic identify
      * formo.identify({ address: '0x...', userId: 'user123' });
      *
-     * // With Privy user
-     * import { parsePrivyProperties } from '@formo/analytics';
+     * // Privy: pass the usePrivy() user to identify every linked wallet under
+     * // the user's DID in one call. Attribution stays on the already-connected
+     * // wallet when there is one, else Privy's primary (user.wallet); pass
+     * // `activeAddress` to pin a specific wallet.
      * const { user } = usePrivy();
-     * if (user) {
-     *   const { properties, wallets } = parsePrivyProperties(user);
-     *   for (const wallet of wallets) {
-     *     formo.identify({ address: wallet.address, userId: user.id }, properties);
-     *   }
-     * }
+     * if (user) formo.identify(user);
      * ```
      */
+    identify(user: PrivyUser, options?: {
+        activeAddress?: string;
+        properties?: IFormoEventProperties;
+    }): Promise<void>;
     identify(params?: {
         address: Address;
         providerName?: string;
         userId?: string;
         rdns?: string;
     }, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
+    /**
+     * 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.
+     */
+    syncPrivyActiveChain(chainType?: string, address?: string): void;
     /**
      * Emits a detect wallet event with current wallet provider info.
      * @param {string} params.providerName
@@ -286,20 +314,38 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * 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.
+     */
+    isTrackingSuppressed(): boolean;
+    /**
+     * 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.
      */
-    private isTrackingSuppressed;
+    private isCurrentChainExcluded;
     /**
-     * Whether the current environment is excluded from tracking — the visitor's
+     * 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.
@@ -308,19 +354,19 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     private isCurrentEnvironmentExcluded;
     /**
      * 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
      */
     private isHostExcluded;
     /**
      * 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
      */
     private isPathExcluded;
     /**
-     * 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
@@ -331,7 +377,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     /**
      * 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
      */
     private isTimezoneExcluded;
@@ -445,7 +491,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * 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
@@ -467,7 +513,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     /**
      * 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.
      */