@formo/analytics 1.36.0 → 1.37.0

package/dist/cjs/src/evm/EvmRequestTracker.d.ts

@@ -68,42 +68,20 @@ export declare class EvmRequestTracker {
     /**
      * One `transaction` event per call in an EIP-5792 batch.
      *
-     * A batch is not a transaction. It maps to several on-chain transactions,
-     * so reporting it as one event would understate volume and make revenue and
-     * per-contract attribution wrong for every app that adopts smart accounts.
-     * Each call is reported on its own, carrying the batch id so the calls can
-     * be reassembled downstream.
+     * The CALL is the unit of attribution: each has its own target, calldata,
+     * and value, and folding a batch into one event would misattribute revenue
+     * and per-contract activity for every app that adopts smart accounts. How
+     * many on-chain transactions a batch becomes depends on execution - an
+     * atomic batch lands as ONE transaction, a non-atomic fallback as several -
+     * so on-chain volume is `count(distinct transaction_hash)`, wallet actions
+     * `count(distinct batch_id)`, never the event count. Each call is reported
+     * on its own, carrying the batch id so the calls reassemble downstream.
      *
      * Status is per BATCH, because that is what `wallet_getCallsStatus` reports.
      * When it resolves, every call in the batch moves together, except where
      * per-call receipts say otherwise on a non-atomic batch.
      */
     private trackBatchedCalls;
-    /**
-     * How one call in a settled batch ended.
-     *
-     * A per-call receipt is authoritative where it exists: that is what makes a
-     * partially reverted non-atomic batch report honestly rather than tarring
-     * every call with the batch's worst outcome. A receipt whose own status is
-     * unreadable falls back to the batch verdict rather than being assumed good.
-     *
-     * The codes are EIP-5792's: 200 confirmed, 400 failed BEFORE landing on
-     * chain, 500 reverted, 600 partially reverted. 400 is a rejection, not a
-     * revert - nothing was mined, so calling it reverted would misreport gas
-     * spent and on-chain activity that never happened.
-     *
-     * Returns undefined when the call cannot be decided, which happens on 600
-     * for a call the wallet gave no receipt for.
-     */
-    private batchCallOutcome;
-    /**
-     * The batch identifier from a `wallet_sendCalls` result.
-     *
-     * EIP-5792 settled on `{ id }`, but wallets shipped against the earlier
-     * draft return a bare string. Both are accepted so a wallet on either
-     * version is still grouped.
-     */
-    private readBatchId;
     /**
      * Resolve a batch through `wallet_getCallsStatus`.
      *

package/dist/cjs/src/evm/EvmRequestTracker.js

@@ -63,6 +63,7 @@ var logger_1 = require("../logger");
 var chain_1 = require("../utils/chain");
 var address_1 = require("../utils/address");
 var types_1 = require("../types");
+var batch_1 = require("./batch");
 /**
  * Decode a hex-encoded `personal_sign` message.
  *
@@ -514,11 +515,14 @@ var EvmRequestTracker = /** @class */ (function () {
     /**
      * One `transaction` event per call in an EIP-5792 batch.
      *
-     * A batch is not a transaction. It maps to several on-chain transactions,
-     * so reporting it as one event would understate volume and make revenue and
-     * per-contract attribution wrong for every app that adopts smart accounts.
-     * Each call is reported on its own, carrying the batch id so the calls can
-     * be reassembled downstream.
+     * The CALL is the unit of attribution: each has its own target, calldata,
+     * and value, and folding a batch into one event would misattribute revenue
+     * and per-contract activity for every app that adopts smart accounts. How
+     * many on-chain transactions a batch becomes depends on execution - an
+     * atomic batch lands as ONE transaction, a non-atomic fallback as several -
+     * so on-chain volume is `count(distinct transaction_hash)`, wallet actions
+     * `count(distinct batch_id)`, never the event count. Each call is reported
+     * on its own, carrying the batch id so the calls reassemble downstream.
      *
      * Status is per BATCH, because that is what `wallet_getCallsStatus` reports.
      * When it resolves, every call in the batch moves together, except where
@@ -589,7 +593,7 @@ var EvmRequestTracker = /** @class */ (function () {
                         return [4 /*yield*/, sendPromise];
                     case 2:
                         result = _d.sent();
-                        batchId = this.readBatchId(result);
+                        batchId = (0, batch_1.readBatchId)(result);
                         for (_a = 0, payloads_2 = payloads; _a < payloads_2.length; _a++) {
                             p = payloads_2[_a];
                             properties = p.properties, rest = __rest(p, ["properties"]);
@@ -624,54 +628,6 @@ var EvmRequestTracker = /** @class */ (function () {
             });
         });
     };
-    /**
-     * How one call in a settled batch ended.
-     *
-     * A per-call receipt is authoritative where it exists: that is what makes a
-     * partially reverted non-atomic batch report honestly rather than tarring
-     * every call with the batch's worst outcome. A receipt whose own status is
-     * unreadable falls back to the batch verdict rather than being assumed good.
-     *
-     * The codes are EIP-5792's: 200 confirmed, 400 failed BEFORE landing on
-     * chain, 500 reverted, 600 partially reverted. 400 is a rejection, not a
-     * revert - nothing was mined, so calling it reverted would misreport gas
-     * spent and on-chain activity that never happened.
-     *
-     * Returns undefined when the call cannot be decided, which happens on 600
-     * for a call the wallet gave no receipt for.
-     */
-    EvmRequestTracker.prototype.batchCallOutcome = function (code, receipt) {
-        var receiptStatus = receipt === null || receipt === void 0 ? void 0 : receipt.status;
-        if (receiptStatus !== undefined) {
-            return receiptStatus === "0x0" || receiptStatus === 0
-                ? types_1.TransactionStatus.REVERTED
-                : types_1.TransactionStatus.CONFIRMED;
-        }
-        if (code >= 600)
-            return undefined;
-        if (code >= 500)
-            return types_1.TransactionStatus.REVERTED;
-        if (code >= 400)
-            return types_1.TransactionStatus.REJECTED;
-        return types_1.TransactionStatus.CONFIRMED;
-    };
-    /**
-     * The batch identifier from a `wallet_sendCalls` result.
-     *
-     * EIP-5792 settled on `{ id }`, but wallets shipped against the earlier
-     * draft return a bare string. Both are accepted so a wallet on either
-     * version is still grouped.
-     */
-    EvmRequestTracker.prototype.readBatchId = function (result) {
-        if (typeof result === "string" && result.length > 0)
-            return result;
-        if (result && typeof result === "object") {
-            var id = result.id;
-            if (typeof id === "string" && id.length > 0)
-                return id;
-        }
-        return undefined;
-    };
     /**
      * Resolve a batch through `wallet_getCallsStatus`.
      *
@@ -694,7 +650,7 @@ var EvmRequestTracker = /** @class */ (function () {
                     return [2 /*return*/];
                 attempts = 0;
                 poll = function () { return __awaiter(_this, void 0, void 0, function () {
-                    var res, code_1, receipts_1, e_8;
+                    var res_1, code_1, e_8;
                     var _this = this;
                     return __generator(this, function (_a) {
                         switch (_a.label) {
@@ -709,13 +665,14 @@ var EvmRequestTracker = /** @class */ (function () {
                                         params: [batchId],
                                     })];
                             case 2:
-                                res = (_a.sent());
-                                code_1 = typeof (res === null || res === void 0 ? void 0 : res.status) === "number" ? res.status : undefined;
+                                res_1 = (_a.sent());
+                                code_1 = (0, batch_1.readBatchStatusCode)(res_1);
                                 if (code_1 !== undefined && code_1 >= 200) {
-                                    receipts_1 = Array.isArray(res === null || res === void 0 ? void 0 : res.receipts) ? res.receipts : [];
                                     payloads.forEach(function (p, index) {
-                                        var receipt = receipts_1[index];
-                                        var outcome = _this.batchCallOutcome(code_1, receipt);
+                                        // Atomic-aware: one receipt covering the whole batch reaches
+                                        // every call, hash included, not just call 0.
+                                        var receipt = (0, batch_1.batchReceiptForCall)(res_1, index, payloads.length);
+                                        var outcome = (0, batch_1.batchCallOutcome)(code_1, receipt);
                                         // 600 means SOME calls reverted, so a call with no receipt of its
                                         // own has not been decided. Reporting it either way would invent
                                         // a result; leaving it unsettled is the honest answer.

package/dist/cjs/src/evm/batch.d.ts

@@ -0,0 +1,94 @@
+import { TransactionStatus } from "../types/events";
+/**
+ * EIP-5792 batch settlement, shared by both capture paths.
+ *
+ * The EIP-1193 request wrapper (`EvmRequestTracker`) and the wagmi cache
+ * observer (`WagmiEventHandler`) each see a batch through a different
+ * transport, but a settled batch means the same thing in both. Keeping the
+ * outcome rules in one place is what stops the two paths from drifting into
+ * reporting the same batch differently depending on how the app happened to
+ * integrate the SDK.
+ */
+/** A settled batch as `wallet_getCallsStatus` (or viem's wrapper) reports it. */
+export type BatchStatusResult = {
+    status?: number | string;
+    statusCode?: number;
+    atomic?: boolean;
+    chainId?: number | string;
+    receipts?: BatchReceipt[];
+} | null | undefined;
+export type BatchReceipt = {
+    status?: string | number;
+    transactionHash?: string;
+};
+/**
+ * The batch identifier from a `wallet_sendCalls` result.
+ *
+ * EIP-5792 settled on `{ id }`, but wallets shipped against the earlier
+ * draft return a bare string. Both are accepted so a wallet on either
+ * version is still grouped.
+ */
+export declare function readBatchId(result: unknown): string | undefined;
+/**
+ * The numeric EIP-5792 status code from a settlement result.
+ *
+ * A wallet answers `wallet_getCallsStatus` with a numeric `status`; viem's
+ * `getCallsStatus` renames that to `statusCode` and puts a summary string in
+ * `status` instead. Both shapes arrive here depending on the capture path,
+ * so read the number wherever it is and never trust the string.
+ */
+export declare function readBatchStatusCode(res: BatchStatusResult): number | undefined;
+/**
+ * The chain a settled batch reports itself on.
+ *
+ * EIP-5792 v2 puts `chainId` in the `wallet_getCallsStatus` response as hex;
+ * viem returns it as a number. Either way it names the chain the batch
+ * actually settled on, which outranks a chain merely inferred from the
+ * connection at broadcast time - the wallet can move chains while the
+ * prompt is up.
+ */
+export declare function readBatchChainId(res: BatchStatusResult): number | undefined;
+/**
+ * How one call in a settled batch ended.
+ *
+ * A per-call receipt is authoritative where it exists: that is what makes a
+ * partially reverted non-atomic batch report honestly rather than tarring
+ * every call with the batch's worst outcome. A receipt whose own status is
+ * unreadable falls back to the batch verdict rather than being assumed good.
+ *
+ * Receipt statuses come in two spellings: raw RPC (`"0x0"`/`"0x1"`, or the
+ * numbers) and viem-formatted (`"reverted"`/`"success"`), because the wagmi
+ * path sees receipts after viem has normalised them.
+ *
+ * The codes are EIP-5792's: 200 confirmed, 400 failed BEFORE landing on
+ * chain, 500 reverted, 600 partially reverted. 400 is a rejection, not a
+ * revert - nothing was mined, so calling it reverted would misreport gas
+ * spent and on-chain activity that never happened.
+ *
+ * Returns undefined when the call cannot be decided, which happens on 600
+ * for a call the wallet gave no receipt for.
+ */
+export declare function batchCallOutcome(code: number, receipt?: BatchReceipt): TransactionStatus | undefined;
+/**
+ * The receipt that decides call `index`, honouring atomic execution.
+ *
+ * An atomic batch lands as ONE on-chain transaction, so the wallet returns a
+ * single receipt covering every call. Indexing receipts positionally there
+ * would hand the shared hash to call 0 and leave its siblings hashless and
+ * decided only by the batch verdict. Every call in an atomic batch shares
+ * the one receipt - same hash, same fate - which is also what makes
+ * `count(distinct transaction_hash)` count on-chain transactions correctly.
+ *
+ * The wallet's own `atomic` flag is authoritative in BOTH directions. An
+ * explicit `atomic: false` with a single receipt is a real shape - a
+ * non-atomic batch whose execution stopped after one call mined - and
+ * sharing that receipt would hand calls that never reached the chain a
+ * transaction hash they do not have. Only when the field is ABSENT (a
+ * wallet predating it, reached over raw EIP-1193; viem fills the field in,
+ * so the wagmi path never lands here) does the conservative inference
+ * apply: one receipt for several calls on a batch that is NOT partially
+ * reverted can only be atomic execution (600 explicitly means some calls
+ * reverted and others did not, which one shared transaction cannot do).
+ */
+export declare function batchReceiptForCall(res: BatchStatusResult, index: number, callCount: number): BatchReceipt | undefined;
+//# sourceMappingURL=batch.d.ts.map

package/dist/cjs/src/evm/batch.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readBatchId = readBatchId;
+exports.readBatchStatusCode = readBatchStatusCode;
+exports.readBatchChainId = readBatchChainId;
+exports.batchCallOutcome = batchCallOutcome;
+exports.batchReceiptForCall = batchReceiptForCall;
+var events_1 = require("../types/events");
+/**
+ * The batch identifier from a `wallet_sendCalls` result.
+ *
+ * EIP-5792 settled on `{ id }`, but wallets shipped against the earlier
+ * draft return a bare string. Both are accepted so a wallet on either
+ * version is still grouped.
+ */
+function readBatchId(result) {
+    if (typeof result === "string" && result.length > 0)
+        return result;
+    if (result && typeof result === "object") {
+        var id = result.id;
+        if (typeof id === "string" && id.length > 0)
+            return id;
+    }
+    return undefined;
+}
+/**
+ * The numeric EIP-5792 status code from a settlement result.
+ *
+ * A wallet answers `wallet_getCallsStatus` with a numeric `status`; viem's
+ * `getCallsStatus` renames that to `statusCode` and puts a summary string in
+ * `status` instead. Both shapes arrive here depending on the capture path,
+ * so read the number wherever it is and never trust the string.
+ */
+function readBatchStatusCode(res) {
+    if (typeof (res === null || res === void 0 ? void 0 : res.statusCode) === "number")
+        return res.statusCode;
+    if (typeof (res === null || res === void 0 ? void 0 : res.status) === "number")
+        return res.status;
+    return undefined;
+}
+/**
+ * The chain a settled batch reports itself on.
+ *
+ * EIP-5792 v2 puts `chainId` in the `wallet_getCallsStatus` response as hex;
+ * viem returns it as a number. Either way it names the chain the batch
+ * actually settled on, which outranks a chain merely inferred from the
+ * connection at broadcast time - the wallet can move chains while the
+ * prompt is up.
+ */
+function readBatchChainId(res) {
+    var raw = res === null || res === void 0 ? void 0 : res.chainId;
+    if (typeof raw === "number" && Number.isFinite(raw) && raw > 0)
+        return raw;
+    if (typeof raw === "string") {
+        var parsed = parseInt(raw, 16);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * How one call in a settled batch ended.
+ *
+ * A per-call receipt is authoritative where it exists: that is what makes a
+ * partially reverted non-atomic batch report honestly rather than tarring
+ * every call with the batch's worst outcome. A receipt whose own status is
+ * unreadable falls back to the batch verdict rather than being assumed good.
+ *
+ * Receipt statuses come in two spellings: raw RPC (`"0x0"`/`"0x1"`, or the
+ * numbers) and viem-formatted (`"reverted"`/`"success"`), because the wagmi
+ * path sees receipts after viem has normalised them.
+ *
+ * The codes are EIP-5792's: 200 confirmed, 400 failed BEFORE landing on
+ * chain, 500 reverted, 600 partially reverted. 400 is a rejection, not a
+ * revert - nothing was mined, so calling it reverted would misreport gas
+ * spent and on-chain activity that never happened.
+ *
+ * Returns undefined when the call cannot be decided, which happens on 600
+ * for a call the wallet gave no receipt for.
+ */
+function batchCallOutcome(code, receipt) {
+    var receiptStatus = receipt === null || receipt === void 0 ? void 0 : receipt.status;
+    if (receiptStatus !== undefined) {
+        return receiptStatus === "0x0" ||
+            receiptStatus === 0 ||
+            receiptStatus === "reverted"
+            ? events_1.TransactionStatus.REVERTED
+            : events_1.TransactionStatus.CONFIRMED;
+    }
+    if (code >= 600)
+        return undefined;
+    if (code >= 500)
+        return events_1.TransactionStatus.REVERTED;
+    if (code >= 400)
+        return events_1.TransactionStatus.REJECTED;
+    return events_1.TransactionStatus.CONFIRMED;
+}
+/**
+ * The receipt that decides call `index`, honouring atomic execution.
+ *
+ * An atomic batch lands as ONE on-chain transaction, so the wallet returns a
+ * single receipt covering every call. Indexing receipts positionally there
+ * would hand the shared hash to call 0 and leave its siblings hashless and
+ * decided only by the batch verdict. Every call in an atomic batch shares
+ * the one receipt - same hash, same fate - which is also what makes
+ * `count(distinct transaction_hash)` count on-chain transactions correctly.
+ *
+ * The wallet's own `atomic` flag is authoritative in BOTH directions. An
+ * explicit `atomic: false` with a single receipt is a real shape - a
+ * non-atomic batch whose execution stopped after one call mined - and
+ * sharing that receipt would hand calls that never reached the chain a
+ * transaction hash they do not have. Only when the field is ABSENT (a
+ * wallet predating it, reached over raw EIP-1193; viem fills the field in,
+ * so the wagmi path never lands here) does the conservative inference
+ * apply: one receipt for several calls on a batch that is NOT partially
+ * reverted can only be atomic execution (600 explicitly means some calls
+ * reverted and others did not, which one shared transaction cannot do).
+ */
+function batchReceiptForCall(res, index, callCount) {
+    var _a;
+    var receipts = Array.isArray(res === null || res === void 0 ? void 0 : res.receipts) ? res.receipts : [];
+    var code = (_a = readBatchStatusCode(res)) !== null && _a !== void 0 ? _a : 0;
+    var atomic = (res === null || res === void 0 ? void 0 : res.atomic) === true ||
+        ((res === null || res === void 0 ? void 0 : res.atomic) === undefined &&
+            receipts.length === 1 &&
+            callCount > 1 &&
+            code < 600);
+    return atomic ? receipts[0] : receipts[index];
+}
+//# sourceMappingURL=batch.js.map

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

@@ -1,2 +1,2 @@
-export declare const version = "1.36.0";
+export declare const version = "1.37.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.36.0';
+exports.version = '1.37.0';
 //# sourceMappingURL=version.js.map

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

@@ -96,6 +96,8 @@ export declare class WagmiEventHandler {
      * broadcast to match the receipt against.
      */
     private get pendingTransactions();
+    /** Broadcast batches awaiting `callsStatus`, shared like the map above. */
+    private get pendingBatches();
     constructor(formoAnalytics: FormoAnalytics, wagmiConfig: WagmiConfig, queryClient?: QueryClient);
     /**
      * Set up listeners for wallet connection, disconnection, and chain changes
@@ -228,6 +230,30 @@ export declare class WagmiEventHandler {
      * Handle query cache events (transaction confirmations)
      */
     private handleQueryEvent;
+    /**
+     * Settle a just-registered batch from a status query that already ran.
+     *
+     * Best-effort by design: the minimal QueryClient interface the SDK
+     * accepts is not guaranteed to expose cache lookup, and a missing
+     * `getAll` just means settlement waits for the next query event, which
+     * is where it normally comes from anyway.
+     */
+    private settleFromCachedCallsStatus;
+    /**
+     * Settle an EIP-5792 batch from a `callsStatus` query.
+     *
+     * Only batches whose broadcast this SDK observed are settled: the batch id
+     * must be in `pendingBatches`, for the same reason receipt queries are
+     * gated on an observed hash - queries are visible to any code sharing the
+     * QueryClient, and emitting for an id we never saw broadcast would let a
+     * forged query invent transactions.
+     *
+     * Outcome semantics are shared with the EIP-1193 path (`src/evm/batch.ts`):
+     * per-call receipts outrank the batch verdict, an atomic batch's single
+     * receipt reaches every call, and a 600 leaves receipt-less calls
+     * unsettled rather than guessed.
+     */
+    private handleCallsStatusQuery;
     /**
      * Handle waitForTransactionReceipt query completion
      * Emits CONFIRMED or REVERTED transaction status
@@ -245,6 +271,23 @@ export declare class WagmiEventHandler {
      * Handle transaction mutations (sendTransaction, writeContract)
      */
     private handleTransactionMutation;
+    /**
+     * One `transaction` event per call in an EIP-5792 batch, wagmi path.
+     *
+     * Mirrors `EvmRequestTracker.trackBatchedCalls` exactly: the CALL is the
+     * unit of attribution, so each call gets its own STARTED at pending and
+     * BROADCASTED (with `batch_id`) when the wallet returns an id. The batch's
+     * on-chain outcome arrives through the `callsStatus` query, handled in
+     * `handleCallsStatusQuery`.
+     *
+     * Rejection matches the 1193 path's rule: only a user rejection (4001
+     * anywhere in the error chain) marks the calls rejected - one dismissal
+     * dismisses the whole prompt, so every call in it is rejected, and
+     * reporting only the first would undercount. Any other error (a wallet
+     * without EIP-5792 support, a transport failure) emits nothing further:
+     * inventing a rejection the user never made would be worse.
+     */
+    private handleSendCallsMutation;
     /**
      * Get the current Wagmi state
      * Supports both getState() method and direct state property access