@formo/analytics 1.33.1 → 1.34.1

package/README.md

@@ -29,6 +29,9 @@ You can install Formo on:
 
 Visit Formo's [Developer Docs](https://docs.formo.so) for detailed guides on local testing, debugging, and consent management.
 
+Using [Privy](./docs/PRIVY_INTEGRATION.md)? `identify(user)`
+clusters all of a Privy user's linked wallets under a single identity.
+
 ## Methodology
 
 Learn how Formo handles [onchain attribution](https://docs.formo.so/data/attribution) and [data collection](https://docs.formo.so/data/what-we-collect).

package/dist/cjs/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.
      */