@formo/analytics 1.26.0 → 1.28.0

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

@@ -2,9 +2,18 @@ import { LogLevel } from "../logger";
 import { IFormoEventContext, IFormoEventProperties, SignatureStatus, TransactionStatus } from "./events";
 import { EIP1193Provider } from "./provider";
 import { ReactNode } from "react";
+import { SolanaOptions } from "../solana/types";
 export type Nullable<T> = T | null;
 export type ChainID = number;
 export type Address = string;
+export type ChainNamespace = 'evm' | 'solana';
+export interface ChainState {
+    address?: Address;
+    chainId?: ChainID;
+}
+export interface EvmChainState extends ChainState {
+    provider?: EIP1193Provider;
+}
 export type ValidInputTypes = Uint8Array | bigint | string | number | boolean;
 export interface IFormoAnalytics {
     page(category?: string, name?: string, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
@@ -41,6 +50,8 @@ export interface IFormoAnalytics {
         to?: string;
         value?: string;
         transactionHash?: string;
+        function_name?: string;
+        function_args?: Record<string, unknown>;
     }, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
     identify(params: {
         address: Address;
@@ -149,6 +160,14 @@ export interface Options {
      * @requires @tanstack/react-query@>=5.0.0 (for mutation tracking)
      */
     wagmi?: WagmiOptions;
+    /**
+     * Solana Wallet Adapter integration configuration
+     * When provided, the SDK will track Solana wallet events in addition to EVM wallet events
+     * This works alongside EIP-1193/Wagmi tracking - you can track both EVM and Solana wallets
+     * @requires @solana/wallet-adapter-base (optional peer dependency)
+     * @requires @solana/wallet-adapter-react (optional peer dependency, for React apps)
+     */
+    solana?: SolanaOptions;
     /**
      * Custom API host for sending events through your own domain to bypass ad blockers
      * - If not provided, events are sent directly to events.formo.so
@@ -172,6 +191,12 @@ export interface Options {
      * @example { queryParams: ["via"], pathPattern: "/r/([^/]+)" }
      */
     referral?: ReferralOptions;
+    /**
+     * Optional error handler for analytics network failures.
+     * Called when event flush fails after all retries.
+     * If not provided, errors are silently swallowed.
+     */
+    errorHandler?: (err: Error) => void;
     ready?: (formo: IFormoAnalytics) => void;
 }
 export interface FormoAnalyticsProviderProps {

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

@@ -44,9 +44,9 @@ export interface DetectAPIEvent {
 }
 export interface IdentifyAPIEvent {
     type: "identify";
-    address: string;
-    providerName: string;
-    rdns: string;
+    address: Address;
+    providerName?: string;
+    rdns?: string;
     userId?: Nullable<string>;
 }
 export interface ChainAPIEvent {
@@ -59,10 +59,13 @@ export interface TransactionAPIEvent {
     status: TransactionStatus;
     chainId: ChainID;
     address: Address;
-    data: string;
-    to: string;
-    value: string;
+    data?: string;
+    to?: string;
+    value?: string;
     transactionHash?: string;
+    function_name?: string;
+    function_args?: Record<string, unknown>;
+    builder_codes?: string;
 }
 export interface SignatureAPIEvent {
     type: "signature";

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

@@ -26,4 +26,25 @@ export declare const getValidAddress: (address: Address | null | undefined) => s
  */
 export declare const isBlockedAddress: (address: Address | null | undefined) => boolean;
 export declare const toChecksumAddress: (address: Address) => string;
+/**
+ * Validates an EVM address and returns it in checksummed format.
+ * @param address The address to validate
+ * @returns The checksummed address or undefined if invalid
+ */
+export declare const validateAndChecksumAddress: (address: string) => Address | undefined;
+/**
+ * Validates an address for both EVM and Solana chains.
+ * For EVM addresses, returns checksummed format.
+ * For Solana addresses, returns the Base58 address as-is.
+ *
+ * When chainId is explicitly provided, validation is strict:
+ * - Solana chainId → only Solana validation
+ * - Non-Solana chainId → only EVM validation
+ * When chainId is omitted, EVM is tried first with Solana fallback.
+ *
+ * @param address The address to validate
+ * @param chainId Optional chain ID to determine address type
+ * @returns The validated address or undefined if invalid
+ */
+export declare const validateAddress: (address: string, chainId?: number) => Address | undefined;
 //# sourceMappingURL=address.d.ts.map

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

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toChecksumAddress = exports.isBlockedAddress = exports.getValidAddress = exports.isValidAddress = void 0;
+exports.validateAddress = exports.validateAndChecksumAddress = exports.toChecksumAddress = exports.isBlockedAddress = exports.getValidAddress = exports.isValidAddress = void 0;
 var keccak_js_1 = require("ethereum-cryptography/keccak.js");
 var utils_js_1 = require("ethereum-cryptography/utils.js");
 var validators_1 = require("../validators");
 var object_1 = require("../validators/object");
 var constants_1 = require("../constants");
+var address_1 = require("../solana/address");
+var types_1 = require("../solana/types");
 /**
  * Private helper function to validate and trim an address
  * @param address The address to validate and trim
@@ -85,4 +87,49 @@ var toChecksumAddress = function (address) {
     return checksumAddress;
 };
 exports.toChecksumAddress = toChecksumAddress;
+/**
+ * Validates an EVM address and returns it in checksummed format.
+ * @param address The address to validate
+ * @returns The checksummed address or undefined if invalid
+ */
+var validateAndChecksumAddress = function (address) {
+    var validAddress = (0, exports.getValidAddress)(address);
+    return validAddress ? (0, exports.toChecksumAddress)(validAddress) : undefined;
+};
+exports.validateAndChecksumAddress = validateAndChecksumAddress;
+/**
+ * Validates an address for both EVM and Solana chains.
+ * For EVM addresses, returns checksummed format.
+ * For Solana addresses, returns the Base58 address as-is.
+ *
+ * When chainId is explicitly provided, validation is strict:
+ * - Solana chainId → only Solana validation
+ * - Non-Solana chainId → only EVM validation
+ * When chainId is omitted, EVM is tried first with Solana fallback.
+ *
+ * @param address The address to validate
+ * @param chainId Optional chain ID to determine address type
+ * @returns The validated address or undefined if invalid
+ */
+var validateAddress = function (address, chainId) {
+    var solanaChainIds = Object.values(types_1.SOLANA_CHAIN_IDS);
+    // Explicit Solana chainId → validate ONLY as Solana
+    if (chainId !== undefined && chainId !== null && solanaChainIds.includes(chainId)) {
+        return (0, address_1.getValidSolanaAddress)(address) || undefined;
+    }
+    // Explicit non-Solana chainId → validate ONLY as EVM
+    if (chainId !== undefined && chainId !== null) {
+        return (0, exports.validateAndChecksumAddress)(address);
+    }
+    // No chainId → try EVM first, then Solana fallback
+    var validEvmAddress = (0, exports.validateAndChecksumAddress)(address);
+    if (validEvmAddress) {
+        return validEvmAddress;
+    }
+    if ((0, address_1.isSolanaAddress)(address)) {
+        return (0, address_1.getValidSolanaAddress)(address) || undefined;
+    }
+    return undefined;
+};
+exports.validateAddress = validateAddress;
 //# sourceMappingURL=address.js.map

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

@@ -0,0 +1,30 @@
+/**
+ * ERC-8021 Builder Code Extraction
+ *
+ * Extracts builder codes from transaction calldata by parsing the ERC-8021
+ * data suffix. The suffix is appended to the end of calldata and parsed
+ * backwards:
+ *
+ *   [original calldata] [schemaData] [schemaId (1 byte)] [ercMarker (16 bytes)]
+ *
+ * Schema 0 (canonical registry):
+ *   [codes (variable ASCII)] [codesLength (1 byte)] [schemaId 0x00] [ercMarker]
+ *
+ * Schema 1 (custom registry):
+ *   [registryAddress (20 bytes)] [chainId (variable)] [chainIdLength (1 byte)]
+ *   [codes (variable ASCII)] [codesLength (1 byte)] [schemaId 0x01] [ercMarker]
+ *
+ * - ercMarker: 0x80218021802180218021802180218021 (16 bytes)
+ * - codes: ASCII-encoded entity codes delimited by 0x2C (comma)
+ *
+ * @see https://docs.base.org/base-chain/builder-codes/builder-codes
+ * @see https://www.erc8021.com/
+ */
+/**
+ * Extract builder codes from transaction calldata by parsing the ERC-8021 suffix.
+ *
+ * @param data - The transaction calldata hex string (with or without 0x prefix)
+ * @returns A comma-separated string of builder codes (e.g. "uniswap,base"), or undefined if no valid ERC-8021 suffix is found
+ */
+export declare function extractBuilderCodes(data: string | undefined | null): string | undefined;
+//# sourceMappingURL=builderCode.d.ts.map

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

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * ERC-8021 Builder Code Extraction
+ *
+ * Extracts builder codes from transaction calldata by parsing the ERC-8021
+ * data suffix. The suffix is appended to the end of calldata and parsed
+ * backwards:
+ *
+ *   [original calldata] [schemaData] [schemaId (1 byte)] [ercMarker (16 bytes)]
+ *
+ * Schema 0 (canonical registry):
+ *   [codes (variable ASCII)] [codesLength (1 byte)] [schemaId 0x00] [ercMarker]
+ *
+ * Schema 1 (custom registry):
+ *   [registryAddress (20 bytes)] [chainId (variable)] [chainIdLength (1 byte)]
+ *   [codes (variable ASCII)] [codesLength (1 byte)] [schemaId 0x01] [ercMarker]
+ *
+ * - ercMarker: 0x80218021802180218021802180218021 (16 bytes)
+ * - codes: ASCII-encoded entity codes delimited by 0x2C (comma)
+ *
+ * @see https://docs.base.org/base-chain/builder-codes/builder-codes
+ * @see https://www.erc8021.com/
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBuilderCodes = extractBuilderCodes;
+/** The 16-byte ERC-8021 marker appended at the very end of calldata */
+var ERC_MARKER = "80218021802180218021802180218021";
+/** Length of the ERC marker in hex characters (16 bytes = 32 hex chars) */
+var ERC_MARKER_HEX_LENGTH = 32;
+/** Supported schema IDs */
+var SCHEMA_ID_CANONICAL = "00";
+var SCHEMA_ID_CUSTOM_REGISTRY = "01";
+/** Comma delimiter (0x2C) used to separate multiple codes */
+var COMMA_BYTE = 0x2c;
+/**
+ * Decode the codes field from a hex string into a comma-separated string.
+ * Validates that all bytes are printable ASCII (0x20–0x7E).
+ *
+ * @param codesHex - Hex string of the codes field
+ * @returns Comma-separated builder codes string, or undefined if invalid
+ */
+function decodeCodes(codesHex) {
+    var bytes = [];
+    for (var i = 0; i < codesHex.length; i += 2) {
+        var byte = parseInt(codesHex.slice(i, i + 2), 16);
+        // Reject NaN (invalid hex), non-printable or non-ASCII bytes
+        if (isNaN(byte) || byte < 0x20 || byte > 0x7e) {
+            return undefined;
+        }
+        bytes.push(byte);
+    }
+    // Split on comma delimiter and decode each code as ASCII
+    var codes = [];
+    var current = [];
+    for (var _i = 0, bytes_1 = bytes; _i < bytes_1.length; _i++) {
+        var byte = bytes_1[_i];
+        if (byte === COMMA_BYTE) {
+            if (current.length > 0) {
+                codes.push(String.fromCharCode.apply(String, current));
+                current = [];
+            }
+        }
+        else {
+            current.push(byte);
+        }
+    }
+    // Push the last code segment
+    if (current.length > 0) {
+        codes.push(String.fromCharCode.apply(String, current));
+    }
+    return codes.length > 0 ? codes.join(",") : undefined;
+}
+/**
+ * Read codesLength and codes from the hex string ending at the given position.
+ *
+ * @param hex - Full hex string (lowercase, no 0x prefix)
+ * @param endPos - Hex char position where codesLength byte ends (i.e. start of schemaId)
+ * @returns Object with decoded codes string and the hex char position where codes start, or undefined
+ */
+function readCodes(hex, endPos) {
+    // Read codesLength (1 byte before endPos)
+    var codesLengthStart = endPos - 2;
+    if (codesLengthStart < 0) {
+        return undefined;
+    }
+    var codesLength = parseInt(hex.slice(codesLengthStart, endPos), 16);
+    if (codesLength === 0 || isNaN(codesLength)) {
+        return undefined;
+    }
+    // Read the codes field
+    var codesHexLength = codesLength * 2;
+    var codesStart = codesLengthStart - codesHexLength;
+    if (codesStart < 0) {
+        return undefined;
+    }
+    var codesHex = hex.slice(codesStart, codesLengthStart);
+    var codes = decodeCodes(codesHex);
+    if (!codes) {
+        return undefined;
+    }
+    return { codes: codes, codesStart: codesStart };
+}
+/**
+ * Extract builder codes from transaction calldata by parsing the ERC-8021 suffix.
+ *
+ * @param data - The transaction calldata hex string (with or without 0x prefix)
+ * @returns A comma-separated string of builder codes (e.g. "uniswap,base"), or undefined if no valid ERC-8021 suffix is found
+ */
+function extractBuilderCodes(data) {
+    if (!data || typeof data !== "string") {
+        return undefined;
+    }
+    // Normalize: remove 0x prefix and work with lowercase hex
+    var hex = data.startsWith("0x") || data.startsWith("0X")
+        ? data.slice(2).toLowerCase()
+        : data.toLowerCase();
+    // Minimum suffix: 1+ byte codes + 1 byte codesLength + 1 byte schemaId + 16 bytes marker = 19 bytes = 38 hex chars
+    if (hex.length < 38) {
+        return undefined;
+    }
+    // Step 1: Check last 16 bytes for ERC marker
+    var markerStart = hex.length - ERC_MARKER_HEX_LENGTH;
+    var marker = hex.slice(markerStart);
+    if (marker !== ERC_MARKER) {
+        return undefined;
+    }
+    // Step 2: Read schemaId (1 byte before the marker)
+    var schemaIdStart = markerStart - 2;
+    if (schemaIdStart < 0) {
+        return undefined;
+    }
+    var schemaId = hex.slice(schemaIdStart, markerStart);
+    // Step 3: Parse based on schemaId
+    if (schemaId === SCHEMA_ID_CANONICAL || schemaId === SCHEMA_ID_CUSTOM_REGISTRY) {
+        // Both Schema 0 and Schema 1 have codes in the same position
+        // (immediately before schemaId when parsing backwards)
+        var result = readCodes(hex, schemaIdStart);
+        return result === null || result === void 0 ? void 0 : result.codes;
+    }
+    // Unknown schema - cannot parse
+    return undefined;
+}
+//# sourceMappingURL=builderCode.js.map

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

@@ -1,5 +1,6 @@
 export * from "./address";
 export * from "./base";
+export * from "./builderCode";
 export * from "./converter";
 export * from "./generate";
 export * from "./hash";

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

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./address"), exports);
 __exportStar(require("./base"), exports);
+__exportStar(require("./builderCode"), exports);
 __exportStar(require("./converter"), exports);
 __exportStar(require("./generate"), exports);
 __exportStar(require("./hash"), exports);

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

@@ -1,2 +1,2 @@
-export declare const version = "1.26.0";
+export declare const version = "1.28.0";
 //# 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.26.0';
+exports.version = '1.28.0';
 //# sourceMappingURL=version.js.map

package/dist/cjs/src/wagmi/WagmiEventHandler.d.ts

@@ -18,6 +18,16 @@ export declare class WagmiEventHandler {
      * Key format: `${mutationId}:${status}`
      */
     private processedMutations;
+    /**
+     * Track processed query states to prevent duplicate event emissions
+     * Key format: `${queryHash}:${status}`
+     */
+    private processedQueries;
+    /**
+     * Store transaction details from BROADCASTED events for use in CONFIRMED/REVERTED
+     * Key: transactionHash, Value: transaction details including the original sender address
+     */
+    private pendingTransactions;
     constructor(formoAnalytics: FormoAnalytics, wagmiConfig: WagmiConfig, queryClient?: QueryClient);
     /**
      * Set up listeners for wallet connection, disconnection, and chain changes
@@ -35,6 +45,20 @@ export declare class WagmiEventHandler {
      * Set up mutation tracking for signatures and transactions
      */
     private setupMutationTracking;
+    /**
+     * Set up query tracking for transaction confirmations
+     * Listens for waitForTransactionReceipt queries to detect CONFIRMED status
+     */
+    private setupQueryTracking;
+    /**
+     * Handle query cache events (transaction confirmations)
+     */
+    private handleQueryEvent;
+    /**
+     * Handle waitForTransactionReceipt query completion
+     * Emits CONFIRMED or REVERTED transaction status
+     */
+    private handleTransactionReceiptQuery;
     /**
      * Handle mutation cache events (signatures, transactions)
      */