@formo/analytics 1.25.0 → 1.27.0

package/dist/esm/src/session/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Session management for Formo Analytics
+ *
+ * Handles tracking of detected wallets and identified wallet-address pairs
+ * using cookies to maintain state across page loads within a session.
+ */
+/**
+ * Cookie keys for session tracking
+ * NOTE: These values must match the original constants in constants/base.ts
+ * to maintain backward compatibility with existing user sessions
+ */
+export declare const SESSION_WALLET_DETECTED_KEY = "wallet-detected";
+export declare const SESSION_WALLET_IDENTIFIED_KEY = "wallet-identified";
+/**
+ * Interface for session management operations
+ */
+export interface IFormoAnalyticsSession {
+    /**
+     * Check if a wallet has been detected in this session
+     * @param rdns The reverse domain name (RDNS) of the wallet provider
+     */
+    isWalletDetected(rdns: string): boolean;
+    /**
+     * Mark a wallet as detected in this session
+     * @param rdns The reverse domain name (RDNS) of the wallet provider
+     */
+    markWalletDetected(rdns: string): void;
+    /**
+     * Check if a wallet-address pair has been identified in this session
+     * @param address The wallet address
+     * @param rdns The reverse domain name (RDNS) of the wallet provider
+     */
+    isWalletIdentified(address: string, rdns: string): boolean;
+    /**
+     * Mark a wallet-address pair as identified in this session
+     * @param address The wallet address
+     * @param rdns The reverse domain name (RDNS) of the wallet provider
+     */
+    markWalletIdentified(address: string, rdns: string): void;
+}
+/**
+ * Implementation of session management using cookies
+ *
+ * Tracks:
+ * - Detected wallets (by RDNS) - to prevent duplicate detection events
+ * - Identified wallet-address pairs - to prevent duplicate identification events
+ *
+ * Session data expires at end of day (86400 seconds).
+ */
+export declare class FormoAnalyticsSession implements IFormoAnalyticsSession {
+    /**
+     * Generate a unique key for wallet identification tracking
+     * Combines address and RDNS to track specific wallet-address combinations
+     *
+     * @param address The wallet address
+     * @param rdns The reverse domain name of the wallet provider
+     * @returns A unique identification key
+     */
+    private generateIdentificationKey;
+    /**
+     * Check if a wallet provider has been detected in this session
+     *
+     * @param rdns The reverse domain name of the wallet provider
+     * @returns true if the wallet has been detected
+     */
+    isWalletDetected(rdns: string): boolean;
+    /**
+     * Mark a wallet provider as detected in this session
+     * Prevents duplicate detection events from being emitted
+     *
+     * @param rdns The reverse domain name of the wallet provider
+     */
+    markWalletDetected(rdns: string): void;
+    /**
+     * Check if a specific wallet-address combination has been identified
+     *
+     * @param address The wallet address
+     * @param rdns The reverse domain name of the wallet provider
+     * @returns true if this wallet-address pair has been identified
+     */
+    isWalletIdentified(address: string, rdns: string): boolean;
+    /**
+     * Mark a wallet-address combination as identified in this session
+     * Prevents duplicate identification events from being emitted
+     *
+     * @param address The wallet address
+     * @param rdns The reverse domain name of the wallet provider
+     */
+    markWalletIdentified(address: string, rdns: string): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/src/session/index.js

@@ -0,0 +1,123 @@
+/**
+ * Session management for Formo Analytics
+ *
+ * Handles tracking of detected wallets and identified wallet-address pairs
+ * using cookies to maintain state across page loads within a session.
+ */
+import { cookie } from "../storage";
+import { logger } from "../logger";
+/**
+ * Cookie keys for session tracking
+ * NOTE: These values must match the original constants in constants/base.ts
+ * to maintain backward compatibility with existing user sessions
+ */
+export var SESSION_WALLET_DETECTED_KEY = "wallet-detected";
+export var SESSION_WALLET_IDENTIFIED_KEY = "wallet-identified";
+/**
+ * Implementation of session management using cookies
+ *
+ * Tracks:
+ * - Detected wallets (by RDNS) - to prevent duplicate detection events
+ * - Identified wallet-address pairs - to prevent duplicate identification events
+ *
+ * Session data expires at end of day (86400 seconds).
+ */
+var FormoAnalyticsSession = /** @class */ (function () {
+    function FormoAnalyticsSession() {
+    }
+    /**
+     * Generate a unique key for wallet identification tracking
+     * Combines address and RDNS to track specific wallet-address combinations
+     *
+     * @param address The wallet address
+     * @param rdns The reverse domain name of the wallet provider
+     * @returns A unique identification key
+     */
+    FormoAnalyticsSession.prototype.generateIdentificationKey = function (address, rdns) {
+        // If rdns is missing, use address-only key as fallback for empty identifies
+        return rdns ? "".concat(address, ":").concat(rdns) : address;
+    };
+    /**
+     * Check if a wallet provider has been detected in this session
+     *
+     * @param rdns The reverse domain name of the wallet provider
+     * @returns true if the wallet has been detected
+     */
+    FormoAnalyticsSession.prototype.isWalletDetected = function (rdns) {
+        var _a;
+        var rdnses = ((_a = cookie().get(SESSION_WALLET_DETECTED_KEY)) === null || _a === void 0 ? void 0 : _a.split(",")) || [];
+        return rdnses.includes(rdns);
+    };
+    /**
+     * Mark a wallet provider as detected in this session
+     * Prevents duplicate detection events from being emitted
+     *
+     * @param rdns The reverse domain name of the wallet provider
+     */
+    FormoAnalyticsSession.prototype.markWalletDetected = function (rdns) {
+        var _a;
+        var rdnses = ((_a = cookie().get(SESSION_WALLET_DETECTED_KEY)) === null || _a === void 0 ? void 0 : _a.split(",")) || [];
+        if (!rdnses.includes(rdns)) {
+            rdnses.push(rdns);
+            cookie().set(SESSION_WALLET_DETECTED_KEY, rdnses.join(","), {
+                // Expires by the end of the day
+                expires: new Date(Date.now() + 86400 * 1000).toUTCString(),
+                path: "/",
+            });
+        }
+    };
+    /**
+     * Check if a specific wallet-address combination has been identified
+     *
+     * @param address The wallet address
+     * @param rdns The reverse domain name of the wallet provider
+     * @returns true if this wallet-address pair has been identified
+     */
+    FormoAnalyticsSession.prototype.isWalletIdentified = function (address, rdns) {
+        var identifiedKey = this.generateIdentificationKey(address, rdns);
+        var cookieValue = cookie().get(SESSION_WALLET_IDENTIFIED_KEY);
+        var identifiedWallets = (cookieValue === null || cookieValue === void 0 ? void 0 : cookieValue.split(",")) || [];
+        var isIdentified = identifiedWallets.includes(identifiedKey);
+        logger.debug("Session: Checking wallet identification", {
+            identifiedKey: identifiedKey,
+            isIdentified: isIdentified,
+            hasRdns: !!rdns,
+        });
+        return isIdentified;
+    };
+    /**
+     * Mark a wallet-address combination as identified in this session
+     * Prevents duplicate identification events from being emitted
+     *
+     * @param address The wallet address
+     * @param rdns The reverse domain name of the wallet provider
+     */
+    FormoAnalyticsSession.prototype.markWalletIdentified = function (address, rdns) {
+        var _a;
+        var identifiedKey = this.generateIdentificationKey(address, rdns);
+        var identifiedWallets = ((_a = cookie().get(SESSION_WALLET_IDENTIFIED_KEY)) === null || _a === void 0 ? void 0 : _a.split(",")) || [];
+        if (!identifiedWallets.includes(identifiedKey)) {
+            identifiedWallets.push(identifiedKey);
+            var newValue = identifiedWallets.join(",");
+            cookie().set(SESSION_WALLET_IDENTIFIED_KEY, newValue, {
+                // Expires by the end of the day
+                expires: new Date(Date.now() + 86400 * 1000).toUTCString(),
+                path: "/",
+            });
+            logger.debug("Session: Marked wallet as identified", {
+                identifiedKey: identifiedKey,
+                hasRdns: !!rdns,
+            });
+        }
+        else {
+            logger.info("Session: Wallet already marked as identified", {
+                identifiedKey: identifiedKey,
+                existingWallets: identifiedWallets,
+                hasRdns: !!rdns,
+            });
+        }
+    };
+    return FormoAnalyticsSession;
+}());
+export { FormoAnalyticsSession };
+//# sourceMappingURL=index.js.map

package/dist/esm/src/{lib/storage → storage}/built-in/blueprint.js

@@ -1,5 +1,5 @@
 import { KEY_PREFIX } from "../constant";
-import { secureHash } from "../../../utils/hash";
+import { secureHash } from "../../utils/hash";
 var StorageBlueprint = /** @class */ (function () {
     function StorageBlueprint(writeKey) {
         this.writeKey = writeKey;

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

@@ -1,4 +1,4 @@
-import { LogLevel } from "../lib";
+import { LogLevel } from "../logger";
 import { IFormoEventContext, IFormoEventProperties, SignatureStatus, TransactionStatus } from "./events";
 import { EIP1193Provider } from "./provider";
 import { ReactNode } from "react";
@@ -9,6 +9,7 @@ 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>;
     reset(): void;
+    cleanup(): void;
     detect(params: {
         rdns: string;
         providerName: string;
@@ -40,6 +41,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;
@@ -112,6 +115,23 @@ export interface ReferralOptions {
      */
     pathPattern?: string;
 }
+/**
+ * Configuration options for Wagmi integration
+ * Allows the SDK to hook into Wagmi v2 wallet events instead of wrapping EIP-1193 providers
+ */
+export interface WagmiOptions {
+    /**
+     * Wagmi config instance from createConfig()
+     * The SDK will subscribe to this config's state changes to track wallet events
+     */
+    config: any;
+    /**
+     * Optional QueryClient instance from @tanstack/react-query
+     * Required for tracking signature and transaction events via mutation cache
+     * If not provided, only connection/disconnection/chain events will be tracked
+     */
+    queryClient?: any;
+}
 export interface Options {
     provider?: EIP1193Provider;
     tracking?: boolean | TrackingOptions;
@@ -123,6 +143,14 @@ export interface Options {
      * @default true
      */
     autocapture?: boolean | AutocaptureOptions;
+    /**
+     * Wagmi integration configuration
+     * When provided, the SDK will hook into Wagmi's event system instead of wrapping EIP-1193 providers
+     * This replaces the default provider tracking with Wagmi's config.subscribe() and MutationCache
+     * @requires wagmi@>=2.0.0
+     * @requires @tanstack/react-query@>=5.0.0 (for mutation tracking)
+     */
+    wagmi?: WagmiOptions;
     /**
      * 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
@@ -146,6 +174,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/esm/src/types/events.d.ts

@@ -59,10 +59,12 @@ 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>;
 }
 export interface SignatureAPIEvent {
     type: "signature";

package/dist/esm/src/validators/object.js

@@ -1,6 +1,4 @@
 export var isNullish = function (item) {
-    // Using "null" value intentionally for validation
-    // eslint-disable-next-line no-null/no-null
     return item === undefined || item === null;
 };
 //# sourceMappingURL=object.js.map

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

@@ -1,2 +1,2 @@
-export declare const version = "1.25.0";
+export declare const version = "1.27.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/esm/src/version.js

@@ -1,4 +1,4 @@
 // This file is auto-generated by scripts/update-version.js during npm version
 // Do not edit manually - it will be overwritten
-export var version = '1.25.0';
+export var version = '1.27.0';
 //# sourceMappingURL=version.js.map

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

@@ -0,0 +1,93 @@
+/**
+ * WagmiEventHandler
+ *
+ * Handles wallet event tracking by hooking into Wagmi v2's config.subscribe()
+ * and TanStack Query's MutationCache. This replaces the EIP-1193 provider
+ * wrapping approach when Wagmi mode is enabled.
+ */
+import { FormoAnalytics } from "../FormoAnalytics";
+import { WagmiConfig, QueryClient } from "./types";
+export declare class WagmiEventHandler {
+    private formo;
+    private wagmiConfig;
+    private queryClient?;
+    private unsubscribers;
+    private trackingState;
+    /**
+     * Track processed mutation states to prevent duplicate event emissions
+     * 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
+     */
+    private setupConnectionListeners;
+    /**
+     * Handle status changes (connect/disconnect)
+     */
+    private handleStatusChange;
+    /**
+     * Handle chain ID changes
+     */
+    private handleChainChange;
+    /**
+     * 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)
+     */
+    private handleMutationEvent;
+    /**
+     * Handle signature mutations (signMessage, signTypedData)
+     */
+    private handleSignatureMutation;
+    /**
+     * Handle transaction mutations (sendTransaction, writeContract)
+     */
+    private handleTransactionMutation;
+    /**
+     * Get the current Wagmi state
+     * Supports both getState() method and direct state property access
+     * for compatibility with different Wagmi wrappers (RainbowKit, etc.)
+     */
+    private getState;
+    /**
+     * Get the currently connected address from Wagmi state
+     */
+    private getConnectedAddress;
+    /**
+     * Get the connector name from Wagmi state
+     */
+    private getConnectorName;
+    /**
+     * Clean up all subscriptions
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=WagmiEventHandler.d.ts.map