@formo/analytics 1.35.2 → 1.37.0

package/dist/esm/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/esm/src/evm/batch.js

@@ -0,0 +1,123 @@
+import { TransactionStatus } from "../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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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"
+            ? TransactionStatus.REVERTED
+            : TransactionStatus.CONFIRMED;
+    }
+    if (code >= 600)
+        return undefined;
+    if (code >= 500)
+        return TransactionStatus.REVERTED;
+    if (code >= 400)
+        return TransactionStatus.REJECTED;
+    return 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).
+ */
+export 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/esm/src/queue/EventQueue.d.ts

@@ -28,6 +28,8 @@ export declare class EventQueue implements IEventQueue {
     private pendingFlush;
     private payloadHashes;
     private canSend?;
+    private closed;
+    private disposePageLeave;
     constructor(writeKey: string, options: Options);
     private generateMessageId;
     /**
@@ -35,6 +37,26 @@ export declare class EventQueue implements IEventQueue {
      * withdrawal / SDK teardown so nothing buffered can be sent later.
      */
     clear(): void;
+    /**
+     * Terminal shutdown. Unlike clear(), which only empties the buffer and can
+     * be followed by more events (consent is re-granted, say), close() makes
+     * this queue permanently inert: every later enqueue() is a no-op and the
+     * page-leave listeners are removed. flush() needs no guard of its own,
+     * because a closed queue starts empty and can never be filled again.
+     *
+     * This is the guarantee a torn-down SDK instance needs. Emission decisions
+     * and the emission itself are separated by an await in many call paths
+     * (event creation is async), so guarding the *caller* cannot work: the
+     * instance may be destroyed while the continuation is in flight. Enforcing
+     * it here means no holder of a stale reference can ever send.
+     *
+     * What close() deliberately does NOT stop is a flush already in flight.
+     * Those events were accepted while the instance was alive, so they are
+     * real data; abandoning them would turn every unmount into silent loss.
+     */
+    close(): void;
+    /** True once close() has run. Exposed for teardown assertions. */
+    get isClosed(): boolean;
     enqueue(event: IFormoEvent, callback?: (...args: any) => void): Promise<void>;
     flush(callback?: (...args: any) => void, drainAll?: boolean): Promise<void | IFormoEventFlushPayload[]>;
     /**
@@ -58,6 +80,12 @@ export declare class EventQueue implements IEventQueue {
     private sendBatches;
     private isErrorRetryable;
     private isDuplicate;
+    /**
+     * Installs the page-leave listeners and returns a disposer that removes
+     * every one of them. Without the disposer each SDK instance leaked five
+     * listeners (three on the global, two on the document) that kept the
+     * instance and its queue alive for the life of the page.
+     */
     private onPageLeave;
 }
 export {};

package/dist/esm/src/queue/EventQueue.js

@@ -83,11 +83,23 @@ var EventQueue = /** @class */ (function () {
         this.queue = [];
         this.queueByteSize = 0; // running total of queued items' byteSize
         this.payloadHashes = new Set();
+        // Terminal shutdown flag. Once set, enqueue() and flush() are no-ops for
+        // the rest of this instance's life. See close().
+        this.closed = false;
+        // Undoes the page-leave listeners installed in the constructor.
+        this.disposePageLeave = null;
+        /**
+         * Installs the page-leave listeners and returns a disposer that removes
+         * every one of them. Without the disposer each SDK instance leaked five
+         * listeners (three on the global, two on the document) that kept the
+         * instance and its queue alive for the life of the page.
+         */
         this.onPageLeave = function (callback) {
             // To ensure the callback is only called once even if more than one events
             // are fired at once.
             var pageLeft = false;
             var isAccessible = false;
+            var resetTimer = null;
             function handleOnLeave() {
                 if (pageLeft) {
                     return;
@@ -97,33 +109,27 @@ var EventQueue = /** @class */ (function () {
                 // Reset pageLeft on the next tick
                 // to ensure callback executes for other listeners
                 // when closing an inactive browser tab.
-                setTimeout(function () {
+                resetTimer = setTimeout(function () {
+                    resetTimer = null;
                     pageLeft = false;
                 }, 0);
             }
-            // Catches the unloading of the page (e.g., closing the tab or navigating away).
-            // Includes user actions like clicking a link, entering a new URL,
-            // refreshing the page, or closing the browser tab
-            // Note that 'pagehide' is not supported in IE.
-            // So, this is a fallback.
-            globalThis.addEventListener("beforeunload", function () {
+            var onBeforeUnload = function () {
                 isAccessible = false;
                 handleOnLeave();
-            });
-            globalThis.addEventListener("blur", function () {
+            };
+            var onBlur = function () {
                 isAccessible = true;
                 handleOnLeave();
-            });
-            globalThis.addEventListener("focus", function () {
+            };
+            var onFocus = function () {
                 pageLeft = false;
-            });
-            // Catches the page being hidden, including scenarios like closing the tab.
-            document.addEventListener("pagehide", function () {
+            };
+            var onPageHide = function () {
                 isAccessible = document.visibilityState !== "hidden";
                 handleOnLeave();
-            });
-            // Catches visibility changes, such as switching tabs or minimizing the browser.
-            document.addEventListener("visibilitychange", function () {
+            };
+            var onVisibilityChange = function () {
                 isAccessible = document.visibilityState !== "hidden";
                 if (document.visibilityState === "hidden") {
                     handleOnLeave();
@@ -131,7 +137,36 @@ var EventQueue = /** @class */ (function () {
                 else {
                     pageLeft = false;
                 }
-            });
+            };
+            // Captured at install time, not read again at removal time. Teardown can
+            // run after the host has swapped or removed these globals (a test harness
+            // replacing jsdom between specs, for one), and removing a listener from a
+            // different object than it was added to silently leaves it attached.
+            var globalTarget = globalThis;
+            var documentTarget = document;
+            // Catches the unloading of the page (e.g., closing the tab or navigating away).
+            // Includes user actions like clicking a link, entering a new URL,
+            // refreshing the page, or closing the browser tab
+            // Note that 'pagehide' is not supported in IE.
+            // So, this is a fallback.
+            globalTarget.addEventListener("beforeunload", onBeforeUnload);
+            globalTarget.addEventListener("blur", onBlur);
+            globalTarget.addEventListener("focus", onFocus);
+            // Catches the page being hidden, including scenarios like closing the tab.
+            documentTarget.addEventListener("pagehide", onPageHide);
+            // Catches visibility changes, such as switching tabs or minimizing the browser.
+            documentTarget.addEventListener("visibilitychange", onVisibilityChange);
+            return function () {
+                if (resetTimer) {
+                    clearTimeout(resetTimer);
+                    resetTimer = null;
+                }
+                globalTarget.removeEventListener("beforeunload", onBeforeUnload);
+                globalTarget.removeEventListener("blur", onBlur);
+                globalTarget.removeEventListener("focus", onFocus);
+                documentTarget.removeEventListener("pagehide", onPageHide);
+                documentTarget.removeEventListener("visibilitychange", onVisibilityChange);
+            };
         };
         options = options || {};
         this.queue = [];
@@ -151,7 +186,7 @@ var EventQueue = /** @class */ (function () {
         this.errorHandler = options.errorHandler;
         this.pendingFlush = null;
         this.timer = null;
-        this.onPageLeave(function (isAccessible) { return __awaiter(_this, void 0, void 0, function () {
+        this.disposePageLeave = this.onPageLeave(function (isAccessible) { return __awaiter(_this, void 0, void 0, function () {
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
@@ -189,6 +224,39 @@ var EventQueue = /** @class */ (function () {
         this.queueByteSize = 0;
         this.payloadHashes.clear();
     };
+    /**
+     * Terminal shutdown. Unlike clear(), which only empties the buffer and can
+     * be followed by more events (consent is re-granted, say), close() makes
+     * this queue permanently inert: every later enqueue() is a no-op and the
+     * page-leave listeners are removed. flush() needs no guard of its own,
+     * because a closed queue starts empty and can never be filled again.
+     *
+     * This is the guarantee a torn-down SDK instance needs. Emission decisions
+     * and the emission itself are separated by an await in many call paths
+     * (event creation is async), so guarding the *caller* cannot work: the
+     * instance may be destroyed while the continuation is in flight. Enforcing
+     * it here means no holder of a stale reference can ever send.
+     *
+     * What close() deliberately does NOT stop is a flush already in flight.
+     * Those events were accepted while the instance was alive, so they are
+     * real data; abandoning them would turn every unmount into silent loss.
+     */
+    EventQueue.prototype.close = function () {
+        this.closed = true;
+        this.clear();
+        if (this.disposePageLeave) {
+            safeCall(this.disposePageLeave);
+            this.disposePageLeave = null;
+        }
+    };
+    Object.defineProperty(EventQueue.prototype, "isClosed", {
+        /** True once close() has run. Exposed for teardown assertions. */
+        get: function () {
+            return this.closed;
+        },
+        enumerable: false,
+        configurable: true
+    });
     EventQueue.prototype.enqueue = function (event, callback) {
         return __awaiter(this, void 0, void 0, function () {
             var message_id, queueItem, hasReachedFlushAt, hasReachedQueueSize;
@@ -196,6 +264,10 @@ var EventQueue = /** @class */ (function () {
                 switch (_a.label) {
                     case 0:
                         callback = callback || noop;
+                        // A torn-down instance must never buffer, however late the caller
+                        // arrives. See close().
+                        if (this.closed)
+                            return [2 /*return*/];
                         // Refuse to buffer anything once consent is withdrawn.
                         if (this.canSend && !this.canSend()) {
                             this.clear();
@@ -204,6 +276,12 @@ var EventQueue = /** @class */ (function () {
                         return [4 /*yield*/, this.generateMessageId(event)];
                     case 1:
                         message_id = _a.sent();
+                        // Re-check after the await. A caller that entered before close() is
+                        // suspended here, and on a queue that has not flushed yet its event
+                        // would push and flush immediately - the exact shape of the bug close()
+                        // exists to stop.
+                        if (this.closed)
+                            return [2 /*return*/];
                         // check if the message already exists
                         if (this.isDuplicate(message_id)) {
                             logger.warn("Event already enqueued, try again after ".concat(millisecondsToSecond(this.flushIntervalMs), " seconds."));

package/dist/esm/src/queue/type.d.ts

@@ -3,5 +3,6 @@ export interface IEventQueue {
     enqueue(event: IFormoEvent, callback?: (...args: any) => void): Promise<void>;
     flush(callback?: (...args: any) => void): Promise<any>;
     clear(): void;
+    close(): void;
 }
 //# sourceMappingURL=type.d.ts.map

package/dist/esm/src/tracking/TrackingPolicy.d.ts

@@ -0,0 +1,146 @@
+import { ChainID, Options } from "../types";
+/** Wallet event kinds that `autocapture` can switch on or off individually. */
+export type AutocaptureEventType = "connect" | "disconnect" | "signature" | "transaction" | "chain";
+/**
+ * What the policy knows about the event being considered.
+ *
+ * An object rather than a bare chain id on purpose. The `excludeChains` fix
+ * had to thread an explicit chain through every gate because the policy had
+ * no identity of its own, and each further per-event input would widen those
+ * signatures again. New inputs extend this type instead.
+ */
+export interface TrackingContext {
+    /**
+     * The event's own chain, when it has one. It wins over the SDK's central
+     * chain, because the two differ whenever the event did not come from the
+     * active provider: a second wallet signing through its own transport, or a
+     * wagmi mutation naming an explicit chain.
+     */
+    chainId?: ChainID;
+}
+/** What the policy needs from the SDK it advises. */
+export interface TrackingPolicyDeps {
+    /**
+     * The CURRENT options.
+     *
+     * A getter, not a captured object: `FormoAnalytics.options` is public and
+     * mutable, so a consumer can replace it after init
+     * (`formo.options = { ...formo.options, tracking: false }`). The gates used
+     * to read `this.options` on every call, so that took effect immediately,
+     * and holding the constructor's object here would silently freeze
+     * configuration at init time.
+     */
+    options(): Options;
+    /** Consent state. Separate from options because the visitor can change it. */
+    hasOptedOut(): boolean;
+    /** The SDK's central chain, used when an event carries none of its own. */
+    currentChainId(): ChainID | undefined;
+}
+export interface ITrackingPolicy {
+    shouldTrack(context?: TrackingContext): boolean;
+    isTrackingSuppressed(): boolean;
+    isChainExcluded(context?: TrackingContext): boolean;
+    isPageExcluded(): boolean;
+    isPersistedIdentityPurgeRequired(): boolean;
+    isAutocaptureEnabled(eventType: AutocaptureEventType): boolean;
+}
+/**
+ * Every "may we track this?" decision, in one place.
+ *
+ * Split out of `FormoAnalytics` so the rules can be read and tested without
+ * an SDK instance, and so option parsing happens once rather than being
+ * re-derived at each gate.
+ */
+export declare class TrackingPolicy implements ITrackingPolicy {
+    private readonly deps;
+    constructor(deps: TrackingPolicyDeps);
+    /**
+     * `tracking` as an options object, or null when it is absent, a boolean, or
+     * anything else. Every exclusion rule lives on the object form, so a null
+     * here means "no exclusions configured", not "excluded".
+     */
+    private trackingOptions;
+    /**
+     * Visitor-level tracking suppression.
+     *
+     * True when the SDK must not persist any identity/session/chain state or
+     * send any events for this visitor: an explicit opt-out, or a
+     * jurisdiction/timezone/host/path exclusion. Public entry points that write
+     * state before reaching `shouldTrack()` (identify / connect / detect) check
+     * this first, so a suppressed visitor leaves no cookies or session state.
+     */
+    isTrackingSuppressed(): boolean;
+    /**
+     * Whether the environment is excluded: the visitor's timezone, the current
+     * hostname, or the current pathname.
+     *
+     * Timezone is visitor-level and stable for the session. Host and path are
+     * current-page-level and transient, so a SPA navigating back to an allowed
+     * path resumes tracking for later actions.
+     */
+    private isEnvironmentExcluded;
+    /** Exact match against `tracking.excludeHosts`. */
+    private isHostExcluded;
+    /** Exact match against `tracking.excludePaths`. */
+    private isPathExcluded;
+    /**
+     * Case-insensitive match of the browser-resolved timezone against
+     * `tracking.excludeTimezones`. Client-side and best-effort; see the option's
+     * own documentation.
+     */
+    private isTimezoneExcluded;
+    /**
+     * Whether the CURRENT PAGE is excluded, as opposed to the visitor.
+     *
+     * Host and path exclusions are transient: identity written on an allowed
+     * page must survive a visit to an excluded route, so callers that persist
+     * or restore identity skip the work here rather than purging.
+     */
+    isPageExcluded(): boolean;
+    /**
+     * Whether a persisted identity cookie should be actively purged, not merely
+     * left unwritten.
+     *
+     * Host and path exclusions are deliberately absent: they are transient
+     * current-page states, so a cookie legitimately written on an allowed page
+     * must survive a visit to an excluded route.
+     */
+    isPersistedIdentityPurgeRequired(): boolean;
+    /**
+     * Whether the chain in play is in `tracking.excludeChains`.
+     *
+     * Separate from `shouldTrack()` so `identify()` can ask *before* mutating
+     * identity state. `trackEvent()` drops an excluded event silently, but
+     * `identify()` marks the wallet as identified first, so without this an
+     * identify on an excluded chain is dedup-marked and then discarded, and the
+     * wallet never re-emits for the rest of the session even after switching to
+     * an allowed chain. On the Privy path that loses a whole cluster at once.
+     */
+    isChainExcluded(context?: TrackingContext): boolean;
+    /**
+     * The shared chain rule, so `shouldTrack()` and `isChainExcluded()` cannot
+     * drift apart. Callers have already established that `excludeChains` is
+     * non-empty.
+     *
+     * Fails CLOSED on an unknown chain. `resolveChainIdForProvider` reports 0
+     * when it has never heard a chain from the signing wallet, and 0 is in no
+     * exclusion list, so treating it as "not excluded" would let through exactly
+     * the events an operator excluded: the wallet on the excluded chain is often
+     * the one we know least about. An explicit exclusion is a directive, so an
+     * unresolvable chain is refused.
+     *
+     * Keyed on 0 and deliberately NOT on `undefined`. 0 is the explicit "we
+     * asked and could not tell" marker. `undefined` means no chain state yet,
+     * which is a legitimate transient (the Privy path reconciles a Solana wallet
+     * through exactly that state), and refusing it would drop real events.
+     * `backfillActiveWallet()` never persists 0, so an unresolvable chain cannot
+     * leak into the central value and reach the unscoped events (page / track /
+     * identify) that fall back to it.
+     */
+    private isChainRefused;
+    /** Whether an event may be tracked at all, given consent and configuration. */
+    shouldTrack(context?: TrackingContext): boolean;
+    /** Whether a wallet event kind is enabled for autocapture. Defaults to on. */
+    isAutocaptureEnabled(eventType: AutocaptureEventType): boolean;
+}
+//# sourceMappingURL=TrackingPolicy.d.ts.map