@formo/analytics 1.33.1 → 1.34.1

package/dist/cjs/src/event/sanitize.js

@@ -0,0 +1,94 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeTrafficSources = exports.sanitizeUtm = exports.sanitizeRef = exports.sanitizeClickId = void 0;
+var constants_1 = require("./constants");
+/**
+ * Traffic-source value sanitization.
+ *
+ * Vulnerability scanners (e.g. Acunetix) crawl customer sites injecting XSS
+ * probes such as `javascript:domxssExecutionSink(1,"'\"><xsstag>()locxss")`
+ * or `<script>alert(1)</script>` into every query parameter. Without
+ * validation those payloads are captured verbatim as utm_* / click-id / ref
+ * values, persisted as sticky session traffic sources, and pollute the
+ * customer's attribution reporting. Each field class gets the tightest rule
+ * its legitimate values allow (verified against production data):
+ *
+ * - Click IDs are opaque platform-generated tokens (base64url-ish); every
+ *   legitimate production value matches the strict token pattern.
+ * - Referral codes are short tokens; >99.5% of production values match the
+ *   strict pattern and none of the remainder are legitimate (scanner
+ *   payloads, mangled encodings, URLs glued to codes).
+ * - UTM values are free-form (spaces, unicode, `+` are legitimate), so they
+ *   only reject markup/quote characters, dangerous URL schemes, control and
+ *   zero-width characters, and absurd lengths.
+ *
+ * Invalid values are dropped to "" — the same representation as "parameter
+ * absent" — rather than repaired, so a poisoned value can never be persisted
+ * or reported.
+ */
+var CLICK_ID_PATTERN = /^[A-Za-z0-9._-]{1,255}$/;
+var REF_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+var UTM_MAX_LENGTH = 255;
+// Markup/quote/backslash characters plus C0/C1 control characters and
+// zero-width / bidi / BOM / replacement characters (mangled-encoding
+// markers). Explicit ranges instead of \p{C} to avoid the `u`-flag
+// property-escape requirement.
+var UTM_FORBIDDEN_CHARS = /[<>"'`\\\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060\ufeff\ufffd]/;
+// Values smuggling an executable/URL scheme, e.g. `javascript:alert(1)`.
+var FORBIDDEN_SCHEME_PREFIX = /^\s*(javascript|data|vbscript):/i;
+var sanitizeClickId = function (value) {
+    return CLICK_ID_PATTERN.test(value) ? value : "";
+};
+exports.sanitizeClickId = sanitizeClickId;
+var sanitizeRef = function (value) {
+    return REF_PATTERN.test(value) ? value : "";
+};
+exports.sanitizeRef = sanitizeRef;
+var sanitizeUtm = function (value) {
+    return value.length <= UTM_MAX_LENGTH &&
+        !UTM_FORBIDDEN_CHARS.test(value) &&
+        !FORBIDDEN_SCHEME_PREFIX.test(value)
+        ? value
+        : "";
+};
+exports.sanitizeUtm = sanitizeUtm;
+var CLICK_ID_KEYS = new Set(constants_1.CLICK_ID_PARAMS);
+/**
+ * Sanitize every traffic-source field of a (possibly sparse) traffic-source
+ * object. `referrer` is left untouched: it is a browser-set URL already
+ * handled by redactUrl, not an attacker-controlled query parameter. Unknown
+ * keys fall through to the UTM rule, the most permissive one.
+ */
+var sanitizeTrafficSources = function (trafficSources) {
+    var result = __assign({}, trafficSources);
+    for (var _i = 0, _a = Object.keys(result); _i < _a.length; _i++) {
+        var key = _a[_i];
+        var value = result[key];
+        if (typeof value !== "string" || value === "" || key === "referrer") {
+            continue;
+        }
+        if (CLICK_ID_KEYS.has(key)) {
+            result[key] = sanitizeClickId(value);
+        }
+        else if (key === "ref") {
+            result[key] = sanitizeRef(value);
+        }
+        else {
+            result[key] = sanitizeUtm(value);
+        }
+    }
+    return result;
+};
+exports.sanitizeTrafficSources = sanitizeTrafficSources;
+//# sourceMappingURL=sanitize.js.map

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

@@ -1,8 +1,14 @@
 /**
  * Privy integration module
  *
- * Provides utilities for enriching wallet profiles with Privy user data.
- * This module exports the property extraction utility and related types.
+ * Exports `parsePrivyProperties`, which parses a Privy user into a flat
+ * properties object and the list of linked wallets without emitting anything -
+ * useful for inspecting or displaying what an identify would send.
+ *
+ * The identify itself is `formo.identify(user)`, which recognises a Privy user
+ * by shape. The function behind it lives in ./utils and is internal.
+ *
+ * This module is React-free so it can be used from the `core` entry.
  */
 export { parsePrivyProperties } from "./utils";
 export type { PrivyUser, PrivyLinkedAccount, PrivyAccountType, PrivyProfileProperties, PrivyWalletInfo, } from "./types";

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

@@ -2,8 +2,14 @@
 /**
  * Privy integration module
  *
- * Provides utilities for enriching wallet profiles with Privy user data.
- * This module exports the property extraction utility and related types.
+ * Exports `parsePrivyProperties`, which parses a Privy user into a flat
+ * properties object and the list of linked wallets without emitting anything -
+ * useful for inspecting or displaying what an identify would send.
+ *
+ * The identify itself is `formo.identify(user)`, which recognises a Privy user
+ * by shape. The function behind it lives in ./utils and is internal.
+ *
+ * This module is React-free so it can be used from the `core` entry.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parsePrivyProperties = void 0;

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

@@ -38,6 +38,16 @@ export interface PrivyLinkedAccount {
     telegramUserId?: string | null;
     firstName?: string | null;
     lastName?: string | null;
+    credentialId?: string | null;
+    customUserId?: string | null;
+    embeddedWallets?: Array<{
+        address: string;
+        chainType?: string | null;
+    }> | null;
+    smartWallets?: Array<{
+        address: string;
+        chainType?: string | null;
+    }> | null;
     firstVerifiedAt?: Date | null;
     latestVerifiedAt?: Date | null;
 }
@@ -51,8 +61,12 @@ export interface PrivyLinkedAccount {
 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[];
     /** Optional custom metadata */
@@ -123,6 +137,11 @@ export interface PrivyUser {
         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;
@@ -150,9 +169,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;
@@ -162,6 +183,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;
 }
 /**

package/dist/cjs/src/privy/utils.d.ts

@@ -2,12 +2,19 @@
  * Utility functions for extracting profile properties from Privy user objects.
  */
 import { PrivyProfileProperties, PrivyUser, PrivyWalletInfo } from "./types";
+import { IFormoAnalytics } from "../types/base";
+import { IFormoEventProperties } from "../types/events";
 /**
  * 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`
  *
@@ -29,4 +36,97 @@ export declare function parsePrivyProperties(user: PrivyUser): {
     properties: PrivyProfileProperties;
     wallets: PrivyWalletInfo[];
 };
+/**
+ * Options for {@link identifyPrivyUser}.
+ */
+export interface IdentifyPrivyUserOptions {
+    /**
+     * Optional override for the wallet that should own event attribution - the
+     * one promoted to the SDK's current address/user, while every other linked
+     * wallet is recorded only for clustering.
+     *
+     * You usually don't need this. When omitted, the helper first uses the wallet
+     * the SDK already treats as active (a prior wagmi/EIP-1193 connect), then
+     * Privy's own surfaced wallet (`user.wallet`), then a best-effort guess
+     * (embedded wallets deprioritized, so the last external wallet). Pass it only
+     * when you want to pin attribution to a specific wallet - e.g. the currently
+     * connected wallet from `useWallets()[0]?.address`, which reflects the live
+     * active wallet more precisely than `user.wallet`.
+     *
+     * Matched strictly: if it doesn't correspond to one of the user's linked
+     * wallets, no wallet is promoted and the SDK's current wallet is left as-is
+     * (so a connected wallet that isn't linked in Privy is preserved).
+     */
+    activeAddress?: string;
+    /**
+     * Extra properties merged into every identify call, on top of the profile
+     * properties parsed from the Privy user (email, socials, DID, …) and the
+     * per-wallet metadata (`wallet_client`, `chain_type`, `is_embedded`).
+     *
+     * Identify events are deduped per `(wallet, user, properties)` within a
+     * session, so changing these properties re-emits with the updated profile
+     * rather than being swallowed. The flip side: a value that changes on every
+     * call (a timestamp, a random id) makes every identify a new event. Pass
+     * stable identity metadata here and put volatile values on `track()` events.
+     */
+    properties?: IFormoEventProperties;
+}
+/**
+ * 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,
+ *   });
+ * }
+ * ```
+ */
+export declare function identifyPrivyUser(analytics: IFormoAnalytics, user: PrivyUser, options?: IdentifyPrivyUserOptions): Promise<{
+    address: string;
+    chainType?: string;
+} | undefined>;
 //# sourceMappingURL=utils.d.ts.map