@formo/analytics 1.24.0 → 1.26.0

package/dist/cjs/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/cjs/src/session/index.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FormoAnalyticsSession = exports.SESSION_WALLET_IDENTIFIED_KEY = exports.SESSION_WALLET_DETECTED_KEY = void 0;
+var storage_1 = require("../storage");
+var logger_1 = require("../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
+ */
+exports.SESSION_WALLET_DETECTED_KEY = "wallet-detected";
+exports.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 = (0, storage_1.cookie)().get(exports.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 = (0, storage_1.cookie)().get(exports.SESSION_WALLET_DETECTED_KEY)) === null || _a === void 0 ? void 0 : _a.split(",")) || [];
+        if (!rdnses.includes(rdns)) {
+            rdnses.push(rdns);
+            (0, storage_1.cookie)().set(exports.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 = (0, storage_1.cookie)().get(exports.SESSION_WALLET_IDENTIFIED_KEY);
+        var identifiedWallets = (cookieValue === null || cookieValue === void 0 ? void 0 : cookieValue.split(",")) || [];
+        var isIdentified = identifiedWallets.includes(identifiedKey);
+        logger_1.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 = (0, storage_1.cookie)().get(exports.SESSION_WALLET_IDENTIFIED_KEY)) === null || _a === void 0 ? void 0 : _a.split(",")) || [];
+        if (!identifiedWallets.includes(identifiedKey)) {
+            identifiedWallets.push(identifiedKey);
+            var newValue = identifiedWallets.join(",");
+            (0, storage_1.cookie)().set(exports.SESSION_WALLET_IDENTIFIED_KEY, newValue, {
+                // Expires by the end of the day
+                expires: new Date(Date.now() + 86400 * 1000).toUTCString(),
+                path: "/",
+            });
+            logger_1.logger.debug("Session: Marked wallet as identified", {
+                identifiedKey: identifiedKey,
+                hasRdns: !!rdns,
+            });
+        }
+        else {
+            logger_1.logger.info("Session: Wallet already marked as identified", {
+                identifiedKey: identifiedKey,
+                existingWallets: identifiedWallets,
+                hasRdns: !!rdns,
+            });
+        }
+    };
+    return FormoAnalyticsSession;
+}());
+exports.FormoAnalyticsSession = FormoAnalyticsSession;
+//# sourceMappingURL=index.js.map

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 var constant_1 = require("../constant");
-var hash_1 = require("../../../utils/hash");
+var hash_1 = require("../../utils/hash");
 var StorageBlueprint = /** @class */ (function () {
     function StorageBlueprint(writeKey) {
         this.writeKey = writeKey;

package/dist/cjs/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/cjs/src/validators/object.js

@@ -2,8 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isNullish = void 0;
 var isNullish = function (item) {
-    // Using "null" value intentionally for validation
-    // eslint-disable-next-line no-null/no-null
     return item === undefined || item === null;
 };
 exports.isNullish = isNullish;

package/dist/cjs/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/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.24.0';
+exports.version = '1.26.0';
 //# sourceMappingURL=version.js.map

package/dist/cjs/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