@formo/analytics 1.25.0 → 1.27.0

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

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Wagmi integration module
+ *
+ * Provides integration with Wagmi v2 for wallet event tracking.
+ * This module exports the WagmiEventHandler and related types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WagmiEventHandler = void 0;
+var WagmiEventHandler_1 = require("./WagmiEventHandler");
+Object.defineProperty(exports, "WagmiEventHandler", { enumerable: true, get: function () { return WagmiEventHandler_1.WagmiEventHandler; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,146 @@
+/**
+ * Wagmi-specific type definitions for wallet event tracking
+ *
+ * These types provide TypeScript interfaces for Wagmi v2 integration,
+ * allowing the SDK to hook into Wagmi's config.subscribe() and MutationCache
+ * to track wallet events without wrapping EIP-1193 providers.
+ */
+/**
+ * Wagmi config state structure
+ * Based on Wagmi v2 internal state
+ */
+export interface WagmiState {
+    chainId?: number;
+    connections: Map<string, WagmiConnection>;
+    current?: string;
+    status: 'connected' | 'disconnected' | 'connecting' | 'reconnecting';
+}
+/**
+ * Wagmi connection information
+ */
+export interface WagmiConnection {
+    accounts: readonly string[];
+    chainId: number;
+    connector: WagmiConnector;
+}
+/**
+ * Wagmi connector interface
+ */
+export interface WagmiConnector {
+    id: string;
+    name: string;
+    type: string;
+    uid: string;
+}
+/**
+ * Wagmi config interface
+ * This is the config object returned by createConfig() or getDefaultConfig() (RainbowKit)
+ *
+ * Note: Different Wagmi wrappers (RainbowKit, etc.) may expose state differently:
+ * - Some use getState() method
+ * - Some expose state as a direct property
+ * We support both patterns for maximum compatibility.
+ */
+export interface WagmiConfig {
+    subscribe<TData>(selector: (state: WagmiState) => TData, listener: (selectedState: TData, previousSelectedState: TData) => void, options?: {
+        equalityFn?: (a: TData, b: TData) => boolean;
+        fireImmediately?: boolean;
+    }): () => void;
+    /**
+     * Get state method - available in some Wagmi versions
+     */
+    getState?(): WagmiState;
+    /**
+     * Direct state property - available in RainbowKit and some Wagmi setups
+     */
+    state?: WagmiState;
+}
+/**
+ * React Query (TanStack Query) mutation state
+ */
+export interface MutationState {
+    status: 'idle' | 'pending' | 'success' | 'error';
+    data?: any;
+    error?: Error | null;
+    variables?: any;
+    context?: any;
+}
+/**
+ * React Query mutation object
+ */
+export interface Mutation {
+    state: MutationState;
+    options: {
+        mutationKey?: readonly unknown[];
+        [key: string]: any;
+    };
+    mutationId: number;
+}
+/**
+ * React Query mutation cache event
+ */
+export interface MutationCacheEvent {
+    type: 'added' | 'removed' | 'updated';
+    mutation: Mutation;
+}
+/**
+ * React Query MutationCache interface
+ */
+export interface MutationCache {
+    subscribe(listener: (event: MutationCacheEvent) => void): () => void;
+}
+/**
+ * React Query query state
+ */
+export interface QueryState {
+    status: 'pending' | 'success' | 'error';
+    data?: any;
+    error?: Error | null;
+    fetchStatus: 'fetching' | 'paused' | 'idle';
+}
+/**
+ * React Query query object
+ */
+export interface Query {
+    state: QueryState;
+    queryKey: readonly unknown[];
+    queryHash: string;
+}
+/**
+ * React Query query cache event
+ */
+export interface QueryCacheEvent {
+    type: 'added' | 'removed' | 'updated';
+    query: Query;
+}
+/**
+ * React Query QueryCache interface
+ */
+export interface QueryCache {
+    subscribe(listener: (event: QueryCacheEvent) => void): () => void;
+}
+/**
+ * React Query QueryClient interface
+ */
+export interface QueryClient {
+    getMutationCache(): MutationCache;
+    getQueryCache(): QueryCache;
+}
+/**
+ * Unsubscribe function returned by subscriptions
+ */
+export type UnsubscribeFn = () => void;
+/**
+ * Wagmi mutation key types for identifying wallet operations
+ */
+export type WagmiMutationKey = 'signMessage' | 'signTypedData' | 'sendTransaction' | 'writeContract';
+/**
+ * Internal tracking state for Wagmi event handler
+ */
+export interface WagmiTrackingState {
+    lastChainId?: number;
+    lastAddress?: string;
+    lastStatus?: WagmiState['status'];
+    isProcessing: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/src/wagmi/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Wagmi-specific type definitions for wallet event tracking
+ *
+ * These types provide TypeScript interfaces for Wagmi v2 integration,
+ * allowing the SDK to hook into Wagmi's config.subscribe() and MutationCache
+ * to track wallet events without wrapping EIP-1193 providers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,74 @@
+/**
+ * Utility functions for Wagmi event handling
+ *
+ * Provides ABI encoding utilities for extracting transaction data from
+ * writeContract mutations without requiring viem as a direct dependency.
+ */
+/**
+ * Flatten a nested object into a flat object with underscore-separated keys.
+ * Only leaf values (primitives) are included; intermediate objects are not.
+ *
+ * Example:
+ *   Input: { o: { x: "100", inner: { a: "42", b: "0xRecipient" } } }
+ *   Output: { o_x: "100", o_inner_a: "42", o_inner_b: "0xRecipient" }
+ *
+ * @param obj - The object to flatten
+ * @param prefix - Optional prefix for keys (used in recursion)
+ * @returns A flat object with underscore-separated keys
+ */
+export declare function flattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+/**
+ * ABI function item type
+ */
+export interface AbiItem {
+    type: string;
+    name?: string;
+    inputs?: AbiInput[];
+    outputs?: AbiOutput[];
+    stateMutability?: string;
+}
+export interface AbiInput {
+    name: string;
+    type: string;
+    indexed?: boolean;
+    components?: AbiInput[];
+    internalType?: string;
+}
+export interface AbiOutput {
+    name: string;
+    type: string;
+    components?: AbiOutput[];
+    internalType?: string;
+}
+/**
+ * Encode writeContract data using viem's encodeFunctionData
+ *
+ * @param abi - The contract ABI
+ * @param functionName - The function name to encode
+ * @param args - The function arguments
+ * @returns The encoded calldata or undefined if encoding fails
+ */
+export declare function encodeWriteContractData(abi: AbiItem[], functionName: string, args?: unknown[]): string | undefined;
+/**
+ * Extract function arguments as a name-value map from ABI and args array
+ *
+ * @param abi - The contract ABI
+ * @param functionName - The function name
+ * @param args - The function arguments array
+ * @returns A map of argument names to values, or undefined if extraction fails
+ */
+export declare function extractFunctionArgs(abi: AbiItem[], functionName: string, args?: unknown[]): Record<string, unknown> | undefined;
+/**
+ * Build safe function args with collision handling and struct flattening.
+ *
+ * This function:
+ * 1. Prefixes top-level args that collide with reserved fields (e.g., 'to' -> 'arg_to')
+ * 2. Flattens nested struct values for easier querying (e.g., order.maker -> order_maker)
+ * 3. Skips flattened keys that would collide with existing top-level args
+ *
+ * @param functionArgs - The extracted function arguments
+ * @param reservedFields - Set of reserved field names that need prefixing
+ * @returns Safe function args object, or undefined if input is undefined
+ */
+export declare function buildSafeFunctionArgs(functionArgs: Record<string, unknown> | undefined, reservedFields: Set<string>): Record<string, unknown> | undefined;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * Utility functions for Wagmi event handling
+ *
+ * Provides ABI encoding utilities for extracting transaction data from
+ * writeContract mutations without requiring viem as a direct dependency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenObject = flattenObject;
+exports.encodeWriteContractData = encodeWriteContractData;
+exports.extractFunctionArgs = extractFunctionArgs;
+exports.buildSafeFunctionArgs = buildSafeFunctionArgs;
+var logger_1 = require("../logger");
+/**
+ * Flatten a nested object into a flat object with underscore-separated keys.
+ * Only leaf values (primitives) are included; intermediate objects are not.
+ *
+ * Example:
+ *   Input: { o: { x: "100", inner: { a: "42", b: "0xRecipient" } } }
+ *   Output: { o_x: "100", o_inner_a: "42", o_inner_b: "0xRecipient" }
+ *
+ * @param obj - The object to flatten
+ * @param prefix - Optional prefix for keys (used in recursion)
+ * @returns A flat object with underscore-separated keys
+ */
+function flattenObject(obj, prefix) {
+    if (prefix === void 0) { prefix = ""; }
+    var result = {};
+    for (var _i = 0, _a = Object.entries(obj); _i < _a.length; _i++) {
+        var _b = _a[_i], key = _b[0], value = _b[1];
+        var newKey = prefix ? "".concat(prefix, "_").concat(key) : key;
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            // Recursively flatten nested objects
+            var nested = flattenObject(value, newKey);
+            Object.assign(result, nested);
+        }
+        else {
+            // Leaf value (primitive or array) - add directly
+            result[newKey] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Recursively convert all BigInt values to strings for JSON serialization
+ * Handles nested objects, arrays, and deeply nested structures (e.g., Solidity structs)
+ *
+ * @param value - The value to convert
+ * @returns The value with all BigInt converted to strings
+ */
+function convertBigIntToString(value) {
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(convertBigIntToString);
+    }
+    if (value !== null && typeof value === "object") {
+        var result = {};
+        for (var _i = 0, _a = Object.entries(value); _i < _a.length; _i++) {
+            var _b = _a[_i], key = _b[0], val = _b[1];
+            result[key] = convertBigIntToString(val);
+        }
+        return result;
+    }
+    return value;
+}
+// Cached viem module reference
+var viemModule;
+/**
+ * Try to load viem synchronously via require
+ * Returns null if viem is not available
+ */
+function tryLoadViem() {
+    if (viemModule !== undefined) {
+        return viemModule;
+    }
+    try {
+        // Use require to load viem synchronously
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        var viem = require("viem");
+        if (viem === null || viem === void 0 ? void 0 : viem.encodeFunctionData) {
+            viemModule = {
+                encodeFunctionData: viem.encodeFunctionData,
+            };
+            return viemModule;
+        }
+    }
+    catch (_a) {
+        // viem is not available
+    }
+    viemModule = null;
+    return null;
+}
+/**
+ * Encode writeContract data using viem's encodeFunctionData
+ *
+ * @param abi - The contract ABI
+ * @param functionName - The function name to encode
+ * @param args - The function arguments
+ * @returns The encoded calldata or undefined if encoding fails
+ */
+function encodeWriteContractData(abi, functionName, args) {
+    try {
+        var viem = tryLoadViem();
+        if (!viem) {
+            logger_1.logger.debug("WagmiEventHandler: viem not available, cannot encode function data");
+            return undefined;
+        }
+        var data = viem.encodeFunctionData({
+            abi: abi,
+            functionName: functionName,
+            args: args || [],
+        });
+        return data;
+    }
+    catch (error) {
+        logger_1.logger.warn("WagmiEventHandler: Failed to encode function data", error);
+        return undefined;
+    }
+}
+/**
+ * Extract function arguments as a name-value map from ABI and args array
+ *
+ * @param abi - The contract ABI
+ * @param functionName - The function name
+ * @param args - The function arguments array
+ * @returns A map of argument names to values, or undefined if extraction fails
+ */
+function extractFunctionArgs(abi, functionName, args) {
+    if (!abi || !functionName || !args || !Array.isArray(args)) {
+        return undefined;
+    }
+    try {
+        // Find the function in the ABI
+        var abiItem = abi.find(function (item) { return item.type === "function" && item.name === functionName; });
+        if (!(abiItem === null || abiItem === void 0 ? void 0 : abiItem.inputs) || !Array.isArray(abiItem.inputs)) {
+            return undefined;
+        }
+        var result_1 = {};
+        abiItem.inputs.forEach(function (input, index) {
+            if (index < args.length) {
+                var argValue = args[index];
+                var argName = input.name || "arg".concat(index);
+                // Recursively convert BigInt to string for JSON serialization
+                // Handles: direct BigInt, arrays with BigInt, nested objects/structs with BigInt
+                result_1[argName] = convertBigIntToString(argValue);
+            }
+        });
+        return result_1;
+    }
+    catch (error) {
+        logger_1.logger.warn("WagmiEventHandler: Failed to extract function args", error);
+        return undefined;
+    }
+}
+/**
+ * Build safe function args with collision handling and struct flattening.
+ *
+ * This function:
+ * 1. Prefixes top-level args that collide with reserved fields (e.g., 'to' -> 'arg_to')
+ * 2. Flattens nested struct values for easier querying (e.g., order.maker -> order_maker)
+ * 3. Skips flattened keys that would collide with existing top-level args
+ *
+ * @param functionArgs - The extracted function arguments
+ * @param reservedFields - Set of reserved field names that need prefixing
+ * @returns Safe function args object, or undefined if input is undefined
+ */
+function buildSafeFunctionArgs(functionArgs, reservedFields) {
+    if (!functionArgs) {
+        return undefined;
+    }
+    var result = {};
+    for (var _i = 0, _a = Object.entries(functionArgs); _i < _a.length; _i++) {
+        var _b = _a[_i], key = _b[0], val = _b[1];
+        var safeKey = reservedFields.has(key) ? "arg_".concat(key) : key;
+        result[safeKey] = val;
+        // If the value is a nested object (struct), flatten it
+        // Skip flattened keys that would overwrite existing top-level args
+        if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+            var flattened = flattenObject(val, safeKey);
+            for (var _c = 0, _d = Object.entries(flattened); _c < _d.length; _c++) {
+                var _e = _d[_c], flatKey = _e[0], flatVal = _e[1];
+                if (!(flatKey in result)) {
+                    result[flatKey] = flatVal;
+                }
+                else {
+                    logger_1.logger.debug("WagmiEventHandler: Skipping flattened key collision", {
+                        flatKey: flatKey,
+                        existingValue: result[flatKey],
+                    });
+                }
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=utils.js.map

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

@@ -24,6 +24,16 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     private _injectedProviderDetail?;
     private _processingAccountsChanged;
     private _seenProviders;
+    /**
+     * Wagmi event handler for tracking wallet events via Wagmi v2
+     * Only initialized when options.wagmi is provided
+     */
+    private wagmiHandler?;
+    /**
+     * Flag indicating if Wagmi mode is enabled
+     * When true, EIP-1193 provider wrapping is skipped
+     */
+    private isWagmiMode;
     config: Config;
     currentChainId?: ChainID;
     currentAddress?: Address;
@@ -34,12 +44,6 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @returns true if there's a provider mismatch, false otherwise
      */
     private isProviderMismatch;
-    /**
-     * Check if a provider is in a valid state for switching
-     * @param provider The provider to validate
-     * @returns true if the provider is in a valid state
-     */
-    private isProviderInValidState;
     private constructor();
     static init(writeKey: string, options?: Options): Promise<FormoAnalytics>;
     /**
@@ -57,6 +61,12 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @returns {void}
      */
     reset(): void;
+    /**
+     * Clean up resources and event listeners
+     * Call this when destroying the analytics instance
+     * @returns {void}
+     */
+    cleanup(): void;
     /**
      * Emits a connect wallet event.
      * @param {ChainID} params.chainId
@@ -129,7 +139,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @param {(...args: unknown[]) => void} callback
      * @returns {Promise<void>}
      */
-    transaction({ status, chainId, address, data, to, value, transactionHash, }: {
+    transaction({ status, chainId, address, data, to, value, transactionHash, function_name, function_args, }: {
         status: TransactionStatus;
         chainId: ChainID;
         address: Address;
@@ -137,6 +147,8 @@ export declare class FormoAnalytics implements 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>;
     /**
      * Emits an identify event with current wallet address and provider info.
@@ -193,7 +205,13 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @returns {boolean} True if the user has opted out
      */
     hasOptedOutTracking(): boolean;
-    private trackProvider;
+    /**
+     * Track an EIP-1193 provider by wrapping its request method and adding event listeners
+     * Note: This is only used in non-Wagmi mode. When Wagmi is enabled, all tracking
+     * happens through Wagmi's connector system instead of EIP-1193/EIP-6963.
+     * @param provider The EIP-1193 provider to track
+     */
+    private trackEIP1193Provider;
     private trackProviders;
     private addProviderListener;
     private registerAccountsChangedListener;
@@ -229,19 +247,13 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @param eventType The wallet event type to check
      * @returns {boolean} True if the event type should be autocaptured
      */
-    private isAutocaptureEnabled;
+    isAutocaptureEnabled(eventType: "connect" | "disconnect" | "signature" | "transaction" | "chain"): boolean;
     /**
      * Get provider information for a given provider
      * @param provider The provider to get info for
      * @returns Provider information
      */
     private getProviderInfo;
-    /**
-     * Attempts to detect information about an injected provider
-     * @param provider The injected provider to analyze
-     * @returns Provider information with fallback values
-     */
-    private detectInjectedProviderInfo;
     private getProviders;
     get providers(): readonly EIP6963ProviderDetail[];
     private detectWallets;