P-2343 Add Privy integration for multi-account user identity clustering

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).

src/core.ts

@@ -9,8 +9,9 @@ export * from "./FormoAnalytics";
 export * from "./types";
 export { formofy } from "./initialization";
 
-export { parsePrivyProperties } from "./privy";
+export { parsePrivyProperties, identifyPrivyUser } from "./privy";
 export type {
+  IdentifyPrivyUserOptions,
   PrivyUser,
   PrivyLinkedAccount,
   PrivyAccountType,

src/event/EventFactory.ts

@@ -231,7 +231,7 @@ 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.
    */
@@ -808,7 +808,17 @@ class EventFactory implements IEventFactory {
       const chainId = 'chainId' in event ? (event.chainId as ChainID) : undefined;
       formoEvent.address = this.validateEventAddress(address, chainId);
     }
-    formoEvent.user_id = userId || null;
+    // An identify event asserts an explicit identity in its own payload (e.g. a
+    // Privy DID for each wallet being clustered). Keep that payload user_id
+    // rather than overwriting it with the active-session user id - otherwise a
+    // clustering identify that intentionally leaves the active user unchanged
+    // (setActive:false) would be stripped of its DID, defeating server-side
+    // wallet clustering. Fall back to the active-session user id when the
+    // identify payload carries none; all other events use the session user id.
+    formoEvent.user_id =
+      event.type === "identify"
+        ? formoEvent.user_id ?? userId ?? null
+        : userId || null;
 
     return formoEvent as IFormoEvent;
   }

src/privy/index.ts

@@ -1,11 +1,16 @@
 /**
  * Privy integration module
  *
- * Provides utilities for enriching wallet profiles with Privy user data.
- * This module exports the property extraction utility and related types.
+ * Provides utilities for enriching wallet profiles with Privy user data:
+ * `parsePrivyProperties` (low-level parsing) and `identifyPrivyUser` (identify
+ * every linked wallet under the user's DID). The same behavior is also
+ * available as `formo.identify(user, { privy: true })`.
+ *
+ * This module is React-free so it can be used from the `core` entry.
  */
 
-export { parsePrivyProperties } from "./utils";
+export { parsePrivyProperties, identifyPrivyUser } from "./utils";
+export type { IdentifyPrivyUserOptions } from "./utils";
 export type {
   PrivyUser,
   PrivyLinkedAccount,

src/privy/types.ts

@@ -75,6 +75,17 @@ export interface PrivyLinkedAccount {
   firstName?: string | null;
   lastName?: string | null;
 
+  // Passkey-specific fields
+  credentialId?: string | null;
+
+  // Custom-auth-specific fields
+  customUserId?: string | null;
+
+  // Cross-app-specific fields. A cross_app account has no top-level `address`;
+  // its wallets live in these arrays (e.g. Abstract Global Wallet).
+  embeddedWallets?: Array<{ address: string; chainType?: string | null }> | null;
+  smartWallets?: Array<{ address: string; chainType?: string | null }> | null;
+
   // Verification timestamps
   firstVerifiedAt?: Date | null;
   latestVerifiedAt?: Date | null;
@@ -91,8 +102,12 @@ export interface PrivyUser {
   /** Privy user ID in DID format (e.g., "did:privy:cm3np...") */
   id: string;
 
-  /** Account creation timestamp */
-  createdAt?: Date;
+  /**
+   * Account creation timestamp. Privy's React SDK supplies a `Date`, but a user
+   * object from the REST API or one that made a JSON round-trip carries an ISO
+   * string or epoch number, so all three are accepted and normalized.
+   */
+  createdAt?: Date | string | number;
 
   /** All linked accounts */
   linkedAccounts?: PrivyLinkedAccount[];
@@ -132,6 +147,8 @@ export interface PrivyUser {
   instagram?: { subject: string; username: string | null };
   spotify?: { subject: string; email: string | null; name: string | null };
   tiktok?: { subject: string; username: string | null; name: string | null };
+  /** Privy's Twitch account exposes only subject/username - no email. */
+  twitch?: { subject: string; username: string | null };
   line?: { subject: string; name: string | null; email: string | null };
   telegram?: {
     telegramUserId: string;
@@ -159,9 +176,11 @@ export interface PrivyProfileProperties {
   privyDid: string;
   privyCreatedAt?: number;
   email?: string;
+  phone?: string;
   apple?: string;
   discord?: string;
   twitter?: string;
+  twitch?: string;
   farcaster?: string;
   github?: string;
   google?: string;
@@ -171,6 +190,8 @@ export interface PrivyProfileProperties {
   telegram?: string;
   tiktok?: string;
   instagram?: string;
+  /** The `customUserId` of a linked `custom_auth` account, when present. */
+  customUserId?: string;
   [key: string]: unknown;
 }