@formo/analytics 1.35.2 → 1.37.0

package/dist/esm/src/event/EventManager.d.ts

@@ -18,8 +18,10 @@ declare class EventManager implements IEventManager {
      * @param event Incoming event data
      */
     addEvent(event: APIEvent, address?: Address, userId?: string): Promise<void>;
-    /** Drop any buffered events (consent withdrawal / teardown). */
+    /** Drop any buffered events (consent withdrawal). Recoverable. */
     clear(): void;
+    /** Terminal shutdown on teardown: nothing can be sent after this. */
+    close(): void;
 }
 export { EventManager };
 //# sourceMappingURL=EventManager.d.ts.map

package/dist/esm/src/event/EventManager.js

@@ -93,10 +93,14 @@ var EventManager = /** @class */ (function () {
             });
         });
     };
-    /** Drop any buffered events (consent withdrawal / teardown). */
+    /** Drop any buffered events (consent withdrawal). Recoverable. */
     EventManager.prototype.clear = function () {
         this.eventQueue.clear();
     };
+    /** Terminal shutdown on teardown: nothing can be sent after this. */
+    EventManager.prototype.close = function () {
+        this.eventQueue.close();
+    };
     return EventManager;
 }());
 export { EventManager };

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

@@ -2,6 +2,7 @@ import { Address, APIEvent, IFormoEvent } from "../types";
 export interface IEventManager {
     addEvent(event: APIEvent, address?: Address, userId?: string): Promise<void>;
     clear(): void;
+    close(): void;
 }
 export interface IEventFactory {
     create(event: APIEvent, address?: Address, userId?: string): Promise<IFormoEvent>;

package/dist/esm/src/evm/EvmEventTracker.d.ts

@@ -0,0 +1,175 @@
+import { EIP6963ProviderDetail } from "mipd";
+import { Address, ChainID, EIP1193Provider, IFormoEventProperties } from "../types";
+import { WalletStateStore } from "../wallet/WalletStateStore";
+import { EvmProviderRegistry } from "./EvmProviderRegistry";
+import { AutocaptureEventType } from "../tracking/TrackingPolicy";
+/** What the tracker needs from the SDK that owns it. */
+export interface EvmEventTrackerDeps {
+    /** Whether this wallet event kind is enabled for autocapture. */
+    isAutocaptureEnabled(eventType: AutocaptureEventType): boolean;
+    /** Visitor-level or page-level suppression: never LEARN a wallet. */
+    isTrackingSuppressed(): boolean;
+    /** Whether an event on this chain would actually be sent. */
+    willTrackEvent(chainId?: ChainID): boolean;
+    /** In wagmi mode the SDK does not wrap providers itself. */
+    isWagmiMode(): boolean;
+    /** Emission. The tracker decides WHEN; the SDK owns the event API. */
+    connect(params: {
+        chainId: ChainID;
+        address: Address;
+    }, properties?: IFormoEventProperties): Promise<void>;
+    disconnect(params?: {
+        chainId?: ChainID;
+        address?: Address;
+    }): Promise<void>;
+    chain(params: {
+        chainId: ChainID;
+        address?: Address;
+    }, properties?: IFormoEventProperties): Promise<void>;
+    /**
+     * `rdns` is the session dedup key for detect, so it must reach `detect()`
+     * exactly as the wallet announced it. Required here rather than optional
+     * so no caller can quietly substitute a placeholder for a missing value.
+     */
+    detect(params: {
+        providerName: string;
+        rdns: string;
+    }): Promise<void>;
+    /**
+     * Install the request wrapper that captures signatures and transactions.
+     *
+     * Still owned by the SDK: it is the next thing to move, and keeping it out
+     * of this change keeps the diff reviewable.
+     */
+    registerRequestListeners(provider: EIP1193Provider): boolean;
+}
+/**
+ * The EIP-1193 side of wallet tracking: which providers to watch, and what
+ * their events mean.
+ *
+ * Split out of `FormoAnalytics` (#336). It holds no wallet state and no
+ * provider registry of its own - those have owners already - so what is left
+ * here is the part that is genuinely about interpreting wallet events:
+ * deciding when a connect has to be reported, when a switch is stale, and
+ * when a provider has stopped being the one we follow.
+ */
+export declare class EvmEventTracker {
+    private readonly wallet;
+    private readonly registry;
+    private readonly deps;
+    /**
+     * The connect this SDK has already reported for a provider.
+     *
+     * Connection REPORTING, which is why it lives with the handlers rather than
+     * with wallet state. The store tells us when a provider stops being active,
+     * which is when a record must lapse.
+     */
+    private _announcedConnect;
+    /**
+     * The EIP-6963 discovery subscription, so teardown can release it. Left
+     * live, a disposed SDK kept reacting to every later wallet announcement:
+     * wrapping providers and emitting detect events from an instance the host
+     * had already replaced.
+     */
+    private unsubscribeDiscovery?;
+    constructor(wallet: WalletStateStore, registry: EvmProviderRegistry, deps: EvmEventTrackerDeps);
+    /** Stop listening for wallet announcements. Called from SDK teardown. */
+    cleanup(): void;
+    /** Drop a provider's reported connect. Called when it stops being active. */
+    forgetAnnouncedConnect(provider: EIP1193Provider): void;
+    /**
+     * Helper method to check if a provider is different from the currently active one
+     * @param provider The provider to check
+     * @returns true if there's a provider mismatch, false otherwise
+     */
+    private isProviderMismatch;
+    /**
+     * Track an EIP-1193 provider by wrapping its request method and adding event listeners
+     * Note: This is only used in non-Wagmi mode. When Wagmi is enabled, all tracking
+     * happens through Wagmi's connector system instead of EIP-1193/EIP-6963.
+     * @param provider The EIP-1193 provider to track
+     */
+    trackEIP1193Provider(provider: EIP1193Provider): void;
+    trackProviders(providers: readonly EIP6963ProviderDetail[]): void;
+    private registerAccountsChangedListener;
+    private onAccountsChanged;
+    /**
+     * Handles changes to the accounts of a given EIP-1193 provider.
+     *
+     * @param provider - The EIP-1193 provider whose accounts have changed.
+     * @param accounts - The new array of account addresses. An empty array indicates a disconnect.
+     * @returns A promise that resolves when the account change has been processed.
+     *
+     * If the accounts array is empty and the provider is the active provider, this method triggers
+     * a disconnect flow. Otherwise, it updates the state to reflect the new accounts as needed.
+     */
+    private _handleAccountsChanged;
+    private registerChainChangedListener;
+    private onChainChanged;
+    /**
+     * Record a provider's chain from its `connect` event, and nothing else.
+     *
+     * Used when connect autocapture is off. `connect` carries `chainId` in its
+     * payload, so this needs no RPC - unlike the full handler, which resolves
+     * the account.
+     */
+    private registerConnectChainObserver;
+    /**
+     * Whether a connect for this wallet still needs reporting.
+     *
+     * True when nothing has been reported for this provider, or when the account
+     * changed. A wallet already reported is not reported again.
+     *
+     * Deliberately does NOT re-report to correct a chain. When `accountsChanged`
+     * wins the race on a provider that exposes no synchronous `chainId`, the
+     * connect carries 0 - honestly, since the chain is unknown at that instant -
+     * and the `connect` payload that follows knows the real one. Emitting again
+     * to relabel would mean two connects for one connection, which is the bug
+     * this whole path exists to prevent. That payload still corrects
+     * `currentChainId`, so everything after it is attributed properly.
+     */
+    private shouldReportConnect;
+    /**
+     * Record a connect as reported - but only if it will actually be sent.
+     *
+     * `connect()` passes through `shouldTrack()`, which refuses an unresolvable
+     * chain when `tracking.excludeChains` is configured. Marking a refused event
+     * as reported would suppress the authoritative one that follows.
+     */
+    private markConnectReported;
+    private registerConnectListener;
+    private registerDisconnectListener;
+    private onConnected;
+    getProviders(): Promise<readonly EIP6963ProviderDetail[]>;
+    detectWallets(providers: readonly EIP6963ProviderDetail[]): Promise<void>;
+    /**
+     * Seed a provider's chain from whatever it already exposes synchronously.
+     *
+     * Most EIP-1193 implementations carry a `chainId` property (MetaMask,
+     * WalletConnect, Coinbase). Reading it costs nothing and cannot block.
+     *
+     * There is deliberately no RPC fallback. An earlier version probed with
+     * `eth_chainId` when a provider was first tracked, on the theory that
+     * tracking time is off the user's critical path. It is not: a serialized
+     * transport has ONE queue, so a stalled probe sits in front of every later
+     * signature and transaction the dapp makes. It could also land out of order
+     * - a slow probe response overwriting a newer `chainChanged` - and relabel
+     * events onto a chain the wallet had already left.
+     *
+     * A provider that exposes nothing stays unknown until it emits
+     * `chainChanged` or `connect`, and unknown is reported honestly as 0.
+     */
+    private seedProviderChainFromState;
+    untrackProvider(provider: EIP1193Provider): void;
+    /**
+     * Clean up providers that are no longer available
+     * This helps maintain consistent state and prevents memory leaks
+     */
+    private cleanupUnavailableProviders;
+    /**
+     * Handle provider mismatch by switching to the new provider and invalidating old tokens
+     * @param provider The new provider to switch to
+     */
+    private handleProviderMismatch;
+}
+//# sourceMappingURL=EvmEventTracker.d.ts.map