@formo/analytics 1.25.0 → 1.27.0

package/dist/cjs/src/queue/EventQueue.d.ts

@@ -0,0 +1,56 @@
+import { IFormoEvent, IFormoEventPayload } from "../types";
+import { IEventQueue } from "./type";
+type IFormoEventFlushPayload = IFormoEventPayload & {
+    sent_at: string;
+};
+type Options = {
+    apiHost: string;
+    flushAt?: number;
+    flushInterval?: number;
+    host?: string;
+    retryCount?: number;
+    errorHandler?: any;
+    maxQueueSize?: number;
+};
+export declare class EventQueue implements IEventQueue {
+    private writeKey;
+    private apiHost;
+    private queue;
+    private timer;
+    private flushAt;
+    private flushIntervalMs;
+    private flushed;
+    private maxQueueSize;
+    private errorHandler;
+    private retryCount;
+    private pendingFlush;
+    private payloadHashes;
+    constructor(writeKey: string, options: Options);
+    private generateMessageId;
+    enqueue(event: IFormoEvent, callback?: (...args: any) => void): Promise<void>;
+    flush(callback?: (...args: any) => void): Promise<void | IFormoEventFlushPayload[]>;
+    /**
+     * Returns the UTF-8 byte length of a string. The browser's keepalive limit
+     * is enforced on the wire (UTF-8 bytes), not on JS string length (UTF-16
+     * code units). Non-ASCII characters (CJK, emoji) can be 2–4x larger in
+     * UTF-8 than their string .length suggests.
+     */
+    private static byteLength;
+    /**
+     * Splits events into batches that respect the browser's 64KB keepalive
+     * payload size limit. Each batch pairs its serialized data with the
+     * original queue items (for per-item callback reporting) and a flag
+     * indicating whether keepalive is safe to use.
+     */
+    private splitIntoBatches;
+    /**
+     * Sends batches sequentially, notifying per-item callbacks on success/failure.
+     * Returns the first error encountered (if any) so the caller can report it.
+     */
+    private sendBatches;
+    private isErrorRetryable;
+    private isDuplicate;
+    private onPageLeave;
+}
+export {};
+//# sourceMappingURL=EventQueue.d.ts.map

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

@@ -51,12 +51,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EventQueue = void 0;
-var validators_1 = require("../../validators");
-var utils_1 = require("../../utils");
+var validators_1 = require("../validators");
+var utils_1 = require("../utils");
 var logger_1 = require("../logger");
-var constants_1 = require("../../constants");
+var constants_1 = require("../constants");
 var fetch_1 = __importDefault(require("../fetch"));
 var noop = function () { };
+var safeCall = function (fn) {
+    var args = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args[_i - 1] = arguments[_i];
+    }
+    try {
+        fn.apply(void 0, args);
+    }
+    catch ( /* swallow */_a) { /* swallow */ }
+};
 var DEFAULT_RETRY = 3;
 var MAX_RETRY = 5;
 var MIN_RETRY = 1;
@@ -66,6 +76,10 @@ var MIN_FLUSH_AT = 1;
 var DEFAULT_QUEUE_SIZE = 1024 * 500; // 500kB
 var MAX_QUEUE_SIZE = 1024 * 500; // 500kB
 var MIN_QUEUE_SIZE = 200; // 200 bytes
+// Browsers enforce a 64KB limit on the total body size of in-flight
+// keepalive fetch requests. Payloads exceeding this are silently cancelled,
+// producing a TypeError: Failed to fetch that cannot be resolved by retrying.
+var KEEPALIVE_PAYLOAD_LIMIT = 64 * 1024; // 64kB
 var DEFAULT_FLUSH_INTERVAL = 1000 * 30; // 1 MINUTE
 var MAX_FLUSH_INTERVAL = 1000 * 300; // 5 MINUTES
 var MIN_FLUSH_INTERVAL = 1000 * 10; // 10 SECONDS
@@ -150,7 +164,6 @@ var EventQueue = /** @class */ (function () {
             });
         }); });
     }
-    //#region Public functions
     EventQueue.prototype.generateMessageId = function (event) {
         return __awaiter(this, void 0, void 0, function () {
             var formattedTimestamp, eventForHashing, eventString;
@@ -206,7 +219,7 @@ var EventQueue = /** @class */ (function () {
     };
     EventQueue.prototype.flush = function (callback) {
         return __awaiter(this, void 0, void 0, function () {
-            var err_1, items, sentAt, data, done;
+            var items, sentAt, data, batches;
             var _this = this;
             return __generator(this, function (_a) {
                 switch (_a.label) {
@@ -220,75 +233,171 @@ var EventQueue = /** @class */ (function () {
                             callback();
                             return [2 /*return*/, Promise.resolve()];
                         }
-                        _a.label = 1;
-                    case 1:
-                        _a.trys.push([1, 4, , 5]);
-                        if (!this.pendingFlush) return [3 /*break*/, 3];
+                        if (!this.pendingFlush) return [3 /*break*/, 2];
                         return [4 /*yield*/, this.pendingFlush];
-                    case 2:
+                    case 1:
                         _a.sent();
-                        _a.label = 3;
-                    case 3: return [3 /*break*/, 5];
-                    case 4:
-                        err_1 = _a.sent();
-                        this.pendingFlush = null;
-                        throw err_1;
-                    case 5:
+                        _a.label = 2;
+                    case 2:
                         items = this.queue.splice(0, this.flushAt);
                         this.payloadHashes.clear();
                         sentAt = new Date().toISOString();
                         data = items.map(function (item) { return (__assign(__assign({}, item.message), { sent_at: sentAt })); });
-                        done = function (err) {
-                            items.forEach(function (_a) {
-                                var message = _a.message, callback = _a.callback;
-                                return callback(err, message, data);
-                            });
-                            callback(err, data);
-                        };
-                        return [2 /*return*/, (this.pendingFlush = (0, fetch_1.default)("".concat(this.apiHost), {
-                                headers: (0, constants_1.EVENTS_API_REQUEST_HEADER)(this.writeKey),
-                                method: "POST",
-                                body: JSON.stringify(data),
-                                keepalive: true,
-                                retries: this.retryCount,
-                                retryDelay: function (attempt) { return Math.pow(2, attempt) * 1000; }, // exponential backoff
-                                retryOn: function (_, error) { return _this.isErrorRetryable(error); },
-                            })
-                                .then(function () {
-                                done();
+                        batches = this.splitIntoBatches(items, data);
+                        return [2 /*return*/, (this.pendingFlush = this.sendBatches(batches, data)
+                                .then(function (firstError) {
+                                if (firstError) {
+                                    safeCall(callback, firstError, data);
+                                    if (typeof _this.errorHandler === "function") {
+                                        safeCall(_this.errorHandler, firstError);
+                                    }
+                                }
+                                else {
+                                    safeCall(callback, undefined, data);
+                                }
                                 return Promise.resolve(data);
                             })
                                 .catch(function (err) {
+                                // Defensive: should not be reachable since sendBatches catches
+                                // all errors internally, but guard against unexpected failures.
+                                safeCall(callback, err, data);
                                 if (typeof _this.errorHandler === "function") {
-                                    done(err);
-                                    return _this.errorHandler(err);
-                                }
-                                if (err.response) {
-                                    var error = new Error(err.response.statusText);
-                                    done(error);
-                                    throw error;
+                                    safeCall(_this.errorHandler, err);
                                 }
-                                done(err);
-                                throw err;
+                                // Do NOT re-throw — analytics errors should never
+                                // propagate as unhandled rejections to the host app
                             }))];
                 }
             });
         });
     };
-    //#region Utility functions
-    EventQueue.prototype.isErrorRetryable = function (error) {
-        var _a, _b, _c;
+    /**
+     * Returns the UTF-8 byte length of a string. The browser's keepalive limit
+     * is enforced on the wire (UTF-8 bytes), not on JS string length (UTF-16
+     * code units). Non-ASCII characters (CJK, emoji) can be 2–4x larger in
+     * UTF-8 than their string .length suggests.
+     */
+    EventQueue.byteLength = function (str) {
+        return new TextEncoder().encode(str).byteLength;
+    };
+    /**
+     * Splits events into batches that respect the browser's 64KB keepalive
+     * payload size limit. Each batch pairs its serialized data with the
+     * original queue items (for per-item callback reporting) and a flag
+     * indicating whether keepalive is safe to use.
+     */
+    EventQueue.prototype.splitIntoBatches = function (items, data) {
+        var serialized = JSON.stringify(data);
+        if (EventQueue.byteLength(serialized) <= KEEPALIVE_PAYLOAD_LIMIT) {
+            return [{ data: data, items: items, keepalive: true }];
+        }
+        var batches = [];
+        var currentData = [];
+        var currentItems = [];
+        var currentSize = 2; // account for JSON array brackets "[]"
+        for (var i = 0; i < data.length; i++) {
+            var event_1 = data[i];
+            var eventSize = EventQueue.byteLength(JSON.stringify(event_1));
+            var sizeWithEvent = currentSize + (currentData.length > 0 ? 1 : 0) + eventSize;
+            if (sizeWithEvent > KEEPALIVE_PAYLOAD_LIMIT) {
+                if (currentData.length > 0) {
+                    batches.push({ data: currentData, items: currentItems, keepalive: true });
+                }
+                // If a single event exceeds the limit, send it without keepalive
+                if (eventSize + 2 > KEEPALIVE_PAYLOAD_LIMIT) {
+                    batches.push({ data: [event_1], items: [items[i]], keepalive: false });
+                    currentData = [];
+                    currentItems = [];
+                    currentSize = 2;
+                }
+                else {
+                    currentData = [event_1];
+                    currentItems = [items[i]];
+                    currentSize = 2 + eventSize;
+                }
+            }
+            else {
+                currentData.push(event_1);
+                currentItems.push(items[i]);
+                currentSize = sizeWithEvent;
+            }
+        }
+        if (currentData.length > 0) {
+            batches.push({ data: currentData, items: currentItems, keepalive: true });
+        }
+        return batches;
+    };
+    /**
+     * Sends batches sequentially, notifying per-item callbacks on success/failure.
+     * Returns the first error encountered (if any) so the caller can report it.
+     */
+    EventQueue.prototype.sendBatches = function (batches, allData) {
+        return __awaiter(this, void 0, void 0, function () {
+            var firstError, _i, batches_1, batch, body, response, error, err_1;
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _i = 0, batches_1 = batches;
+                        _a.label = 1;
+                    case 1:
+                        if (!(_i < batches_1.length)) return [3 /*break*/, 6];
+                        batch = batches_1[_i];
+                        _a.label = 2;
+                    case 2:
+                        _a.trys.push([2, 4, , 5]);
+                        body = JSON.stringify(batch.data);
+                        return [4 /*yield*/, (0, fetch_1.default)("".concat(this.apiHost), {
+                                headers: (0, constants_1.EVENTS_API_REQUEST_HEADER)(this.writeKey),
+                                method: "POST",
+                                body: body,
+                                keepalive: batch.keepalive,
+                                retries: this.retryCount,
+                                retryDelay: function (attempt) { return Math.pow(2, attempt) * 1000; },
+                                retryOn: function (_, error, response) { return _this.isErrorRetryable(error, response); },
+                            })];
+                    case 3:
+                        response = _a.sent();
+                        if (!response.ok) {
+                            error = new Error(response.statusText || "HTTP ".concat(response.status));
+                            error.response = response;
+                            throw error;
+                        }
+                        batch.items.forEach(function (_a) {
+                            var message = _a.message, cb = _a.callback;
+                            return safeCall(cb, undefined, message, allData);
+                        });
+                        return [3 /*break*/, 5];
+                    case 4:
+                        err_1 = _a.sent();
+                        firstError = firstError || err_1;
+                        batch.items.forEach(function (_a) {
+                            var message = _a.message, cb = _a.callback;
+                            return safeCall(cb, err_1, message, allData);
+                        });
+                        return [3 /*break*/, 5];
+                    case 5:
+                        _i++;
+                        return [3 /*break*/, 1];
+                    case 6: return [2 /*return*/, firstError];
+                }
+            });
+        });
+    };
+    EventQueue.prototype.isErrorRetryable = function (error, response) {
+        var _a, _b;
         // Retry Network Errors.
-        if ((0, validators_1.isNetworkError)(error))
+        if (error && (0, validators_1.isNetworkError)(error))
             return true;
-        // Cannot determine if the request can be retried
-        if (!(error === null || error === void 0 ? void 0 : error.response))
+        // Check response status if available
+        var status = (_a = response === null || response === void 0 ? void 0 : response.status) !== null && _a !== void 0 ? _a : (_b = error === null || error === void 0 ? void 0 : error.response) === null || _b === void 0 ? void 0 : _b.status;
+        if (!status)
             return false;
         // Retry Server Errors (5xx).
-        if (((_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.status) >= 500 && ((_b = error === null || error === void 0 ? void 0 : error.response) === null || _b === void 0 ? void 0 : _b.status) <= 599)
+        if (status >= 500 && status <= 599)
             return true;
         // Retry if rate limited.
-        if (((_c = error === null || error === void 0 ? void 0 : error.response) === null || _c === void 0 ? void 0 : _c.status) === 429)
+        if (status === 429)
             return true;
         return false;
     };

package/dist/{esm/src/lib → cjs/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/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;
@@ -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/cjs/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/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.25.0";
+export declare const version = "1.27.0";
 //# sourceMappingURL=version.d.ts.map