@formo/analytics 1.24.0 → 1.26.0

package/dist/esm/src/{lib/event → event}/type.d.ts

@@ -1,4 +1,4 @@
-import { Address, APIEvent, IFormoEvent } from "../../types";
+import { Address, APIEvent, IFormoEvent } from "../types";
 export interface IEventManager {
     addEvent(event: APIEvent, address?: Address, userId?: string): Promise<void>;
 }

package/dist/esm/src/{lib/event → event}/utils.d.ts

@@ -1,4 +1,4 @@
-import { AnonymousID } from "../../types";
+import { AnonymousID } from "../types";
 declare const generateAnonymousId: (key: string) => AnonymousID;
 declare function getCookieDomain(hostname?: string): string;
 export { generateAnonymousId, getCookieDomain };

package/dist/esm/src/{lib/event → event}/utils.js

@@ -1,4 +1,4 @@
-import { generateNativeUUID } from "../../utils";
+import { generateNativeUUID } from "../utils";
 import { cookie } from "../storage";
 var generateAnonymousId = function (key) {
     var storedAnonymousId = cookie().get(key);

package/dist/esm/src/{lib/fetch.d.ts → fetch/index.d.ts}

@@ -1,3 +1,3 @@
 declare const _default: (input: string | URL | Request, init?: (RequestInit & import("fetch-retry").RequestInitRetryParams<typeof globalThis.fetch>) | undefined) => Promise<Response>;
 export default _default;
-//# sourceMappingURL=fetch.d.ts.map
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/src/{lib/fetch.js → fetch/index.js}

@@ -1,3 +1,3 @@
 import fetch from "fetch-retry";
 export default fetch(global.fetch);
-//# sourceMappingURL=fetch.js.map
+//# sourceMappingURL=index.js.map

package/dist/esm/src/provider/detection.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Provider detection utilities for identifying wallet providers
+ */
+import { EIP1193Provider } from "../types";
+/**
+ * Default icon for providers without custom icons
+ */
+export declare const DEFAULT_PROVIDER_ICON: "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHJlY3Qgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiBmaWxsPSIjRkZGIi8+CjxwYXRoIGQ9Ik0xNiA4TDggMjRoMTZMMTYgOHoiIGZpbGw9IiMzMzMiLz4KPC9zdmc+Cg==";
+/**
+ * Common wallet provider flags used for detection
+ */
+export interface WalletProviderFlags {
+    isMetaMask?: boolean;
+    isCoinbaseWallet?: boolean;
+    isWalletConnect?: boolean;
+    isTrust?: boolean;
+    isBraveWallet?: boolean;
+    isPhantom?: boolean;
+}
+/**
+ * Provider information returned by detection
+ */
+export interface ProviderInfo {
+    name: string;
+    rdns: string;
+    uuid: string;
+    icon: `data:image/${string}`;
+}
+/**
+ * Attempts to detect information about an injected provider by examining
+ * common wallet-specific flags and properties.
+ *
+ * @param provider The injected provider to analyze
+ * @returns Provider information with fallback values if detection fails
+ *
+ * @example
+ * ```typescript
+ * const provider = window.ethereum;
+ * const info = detectInjectedProviderInfo(provider);
+ * console.log(info.name); // "MetaMask" or "Injected Provider"
+ * ```
+ */
+export declare function detectInjectedProviderInfo(provider: EIP1193Provider): ProviderInfo;
+/**
+ * Validates that a provider implements the required EIP-1193 interface
+ *
+ * @param provider The provider to validate
+ * @returns true if the provider has all required methods
+ *
+ * @example
+ * ```typescript
+ * if (isValidProvider(window.ethereum)) {
+ *   // Safe to use provider
+ * }
+ * ```
+ */
+export declare function isValidProvider(provider: EIP1193Provider | undefined | null): provider is EIP1193Provider;
+//# sourceMappingURL=detection.d.ts.map

package/dist/esm/src/provider/detection.js

@@ -0,0 +1,98 @@
+/**
+ * Provider detection utilities for identifying wallet providers
+ */
+/**
+ * Default icon for providers without custom icons
+ */
+export var DEFAULT_PROVIDER_ICON = "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHJlY3Qgd2lkdGg9IjMyIiBoZWlnaHQ9IjMyIiBmaWxsPSIjRkZGIi8+CjxwYXRoIGQ9Ik0xNiA4TDggMjRoMTZMMTYgOHoiIGZpbGw9IiMzMzMiLz4KPC9zdmc+Cg==";
+/**
+ * Known wallet providers with their identifying flags and metadata
+ */
+var KNOWN_PROVIDERS = [
+    {
+        flag: 'isMetaMask',
+        name: 'MetaMask',
+        rdns: 'io.metamask',
+    },
+    {
+        flag: 'isCoinbaseWallet',
+        name: 'Coinbase Wallet',
+        rdns: 'com.coinbase.wallet',
+    },
+    {
+        flag: 'isWalletConnect',
+        name: 'WalletConnect',
+        rdns: 'com.walletconnect',
+    },
+    {
+        flag: 'isTrust',
+        name: 'Trust Wallet',
+        rdns: 'com.trustwallet',
+    },
+    {
+        flag: 'isBraveWallet',
+        name: 'Brave Wallet',
+        rdns: 'com.brave.wallet',
+    },
+    {
+        flag: 'isPhantom',
+        name: 'Phantom',
+        rdns: 'app.phantom',
+    },
+];
+/**
+ * Attempts to detect information about an injected provider by examining
+ * common wallet-specific flags and properties.
+ *
+ * @param provider The injected provider to analyze
+ * @returns Provider information with fallback values if detection fails
+ *
+ * @example
+ * ```typescript
+ * const provider = window.ethereum;
+ * const info = detectInjectedProviderInfo(provider);
+ * console.log(info.name); // "MetaMask" or "Injected Provider"
+ * ```
+ */
+export function detectInjectedProviderInfo(provider) {
+    // Default values for unknown providers
+    var name = "Injected Provider";
+    var rdns = "io.injected.provider";
+    // Cast to check for wallet-specific flags
+    var flags = provider;
+    // Check known providers in order of precedence
+    for (var _i = 0, KNOWN_PROVIDERS_1 = KNOWN_PROVIDERS; _i < KNOWN_PROVIDERS_1.length; _i++) {
+        var knownProvider = KNOWN_PROVIDERS_1[_i];
+        if (flags[knownProvider.flag]) {
+            name = knownProvider.name;
+            rdns = knownProvider.rdns;
+            break;
+        }
+    }
+    return {
+        name: name,
+        rdns: rdns,
+        uuid: "injected-".concat(rdns.replace(/[^a-zA-Z0-9]/g, "-")),
+        icon: DEFAULT_PROVIDER_ICON,
+    };
+}
+/**
+ * Validates that a provider implements the required EIP-1193 interface
+ *
+ * @param provider The provider to validate
+ * @returns true if the provider has all required methods
+ *
+ * @example
+ * ```typescript
+ * if (isValidProvider(window.ethereum)) {
+ *   // Safe to use provider
+ * }
+ * ```
+ */
+export function isValidProvider(provider) {
+    return (!!provider &&
+        typeof provider.request === "function" &&
+        typeof provider.on === "function" &&
+        typeof provider.removeListener === "function");
+}
+//# sourceMappingURL=detection.js.map

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

@@ -0,0 +1,6 @@
+/**
+ * Provider-related exports
+ */
+export { detectInjectedProviderInfo, isValidProvider, DEFAULT_PROVIDER_ICON, } from './detection';
+export type { WalletProviderFlags, ProviderInfo, } from './detection';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,5 @@
+/**
+ * Provider-related exports
+ */
+export { detectInjectedProviderInfo, isValidProvider, DEFAULT_PROVIDER_ICON, } from './detection';
+//# sourceMappingURL=index.js.map

package/dist/{cjs/src/lib → esm/src}/queue/EventQueue.d.ts

@@ -1,4 +1,4 @@
-import { IFormoEvent } from "../../types";
+import { IFormoEvent } from "../types";
 import { IEventQueue } from "./type";
 type Options = {
     apiHost: string;

package/dist/esm/src/{lib/queue → queue}/EventQueue.js

@@ -45,10 +45,10 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
-import { isNetworkError } from "../../validators";
-import { clampNumber, getActionDescriptor, hash, millisecondsToSecond, toDateHourMinute, } from "../../utils";
+import { isNetworkError } from "../validators";
+import { clampNumber, getActionDescriptor, hash, millisecondsToSecond, toDateHourMinute, } from "../utils";
 import { logger } from "../logger";
-import { EVENTS_API_REQUEST_HEADER } from "../../constants";
+import { EVENTS_API_REQUEST_HEADER } from "../constants";
 import fetch from "../fetch";
 var noop = function () { };
 var DEFAULT_RETRY = 3;

package/dist/{cjs/src/lib → esm/src}/queue/type.d.ts

@@ -1,4 +1,4 @@
-import { IFormoEvent } from "../../types";
+import { IFormoEvent } from "../types";
 export interface IEventQueue {
     enqueue(event: IFormoEvent, callback?: (...args: any) => void): Promise<void>;
     flush(callback?: (...args: any) => void): Promise<any>;

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;
@@ -112,6 +113,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 +141,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

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.24.0";
+export declare const version = "1.26.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.24.0';
+export var version = '1.26.0';
 //# sourceMappingURL=version.js.map

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

@@ -0,0 +1,69 @@
+/**
+ * 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;
+    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;
+    /**
+     * 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