@formo/analytics 1.37.0 → 1.38.1

package/dist/esm/src/FormoAnalytics.d.ts

@@ -96,6 +96,8 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * Call this when destroying the analytics instance
      * @returns {void}
      */
+    /** Set by cleanup(); a torn-down instance refuses new registrations. */
+    private isCleanedUp;
     cleanup(): void;
     /**
      * Emits a connect wallet event.
@@ -373,6 +375,70 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      */
     get solana(): SolanaManager;
     private getCurrentChainId;
+    /**
+     * Track an EIP-1193 provider the page constructed itself.
+     *
+     * Discovery covers EIP-6963 announcements and `window.ethereum`, which is
+     * every injected wallet and nothing else. WalletConnect and Ledger
+     * providers are built by the app (`EthereumProvider.init(...)`) and
+     * announce nothing, so their sessions were invisible: connects,
+     * signatures, and transactions all silently missing. Hand the provider
+     * here once it exists and it takes the exact pipeline a discovered
+     * provider takes - detect event, lifecycle listeners, request wrapper -
+     * and a session that is already live is adopted from the provider's
+     * synchronous state.
+     *
+     * Metadata resolution order: the caller's `info` overrides win; then a
+     * WalletConnect session's peer metadata, which names the REAL wallet on
+     * the far side of the transport (for example "Ledger Live"); then flag
+     * sniffing; then a generic fallback. One deliberate exception: a caller
+     * name of exactly "WalletConnect" is the generic transport name, so the
+     * live peer still replaces it on events - name the provider anything
+     * else to pin it verbatim.
+     *
+     * No-op outside the EIP-1193 path: in wagmi mode the connector system
+     * already tracks these sessions, and wrapping the same provider twice
+     * would double-report every event.
+     *
+     * With several live SDK instances (multi write-key pages) registering
+     * the SAME provider, request-derived events (signatures, transactions)
+     * go to the most recently CREATED live instance, regardless of the
+     * order registrations happen to land in - the same single-observer
+     * semantics discovery has always had for the request wrapper. Lifecycle events (connect, chain, disconnect) reach every
+     * instance. Fanning request observations out to all instances is a
+     * separate feature.
+     *
+     * @returns true when the provider is (now) tracked, false when it was
+     * refused (wagmi mode, EVM disabled, or not a valid EIP-1193 provider).
+     *
+     * @example
+     * ```typescript
+     * const wcProvider = await EthereumProvider.init({ projectId, chains });
+     * formo.registerProvider(wcProvider);
+     * ```
+     */
+    /**
+     * INTERNAL. Install the request wrapper on a wagmi connector's provider.
+     *
+     * Wagmi mode watches the store and caches, which see hook-driven calls
+     * only; imperative viem calls (walletClient.sendTransaction,
+     * .signMessage, .writeContract, raw request) create no mutation and were
+     * silently lost. Every viem client in a wagmi app is built on the
+     * connector's EIP-1193 provider, so wrapping that provider closes the
+     * gap. Lifecycle (connect/chain/disconnect) stays store-driven: only the
+     * request wrapper installs here. Double counting is prevented in the
+     * wrapper via `shouldSkipRequestCapture`.
+     */
+    _wrapWagmiProvider(provider: EIP1193Provider, chainId?: number): boolean;
+    /** INTERNAL. Chain updates for the fallback-wrapped provider. */
+    _rememberWagmiProviderChain(provider: EIP1193Provider, chainId: number | undefined): void;
+    registerProvider(provider: EIP1193Provider, info?: {
+        name?: string;
+        rdns?: string;
+        icon?: `data:image/${string}`;
+    }): boolean;
+    /** Fallback uuid suffix for platforms without crypto.randomUUID. */
+    private static registeredProviderSeq;
     getTrackedProvidersCount(): number;
     /**
      * Get current provider state for debugging

package/dist/esm/src/FormoAnalytics.js

@@ -57,6 +57,7 @@ import { validateAddress, validateAndChecksumAddress } from "./utils/address";
 import { TrackingPolicy, } from "./tracking/TrackingPolicy";
 import { WalletStateStore } from "./wallet/WalletStateStore";
 import { EvmProviderRegistry } from "./evm/EvmProviderRegistry";
+import { detectInjectedProviderInfo, isValidProvider, readWalletConnectPeer, } from "./provider";
 import { EvmEventTracker } from "./evm/EvmEventTracker";
 import { EvmRequestTracker } from "./evm/EvmRequestTracker";
 import { parseChainId } from "./utils/chain";
@@ -90,6 +91,13 @@ var FormoAnalytics = /** @class */ (function () {
         this._currentUrl = "";
         this._pageHooksDisposed = false;
         this.currentUserId = "";
+        /**
+         * Clean up resources and event listeners
+         * Call this when destroying the analytics instance
+         * @returns {void}
+         */
+        /** Set by cleanup(); a torn-down instance refuses new registrations. */
+        this.isCleanedUp = false;
         this.config = {
             writeKey: writeKey,
         };
@@ -111,6 +119,7 @@ var FormoAnalytics = /** @class */ (function () {
         this.transaction = this.transaction.bind(this);
         this.detect = this.detect.bind(this);
         this.track = this.track.bind(this);
+        this.registerProvider = this.registerProvider.bind(this);
         this.page = this.page.bind(this);
         this.reset = this.reset.bind(this);
         this.cleanup = this.cleanup.bind(this);
@@ -168,6 +177,11 @@ var FormoAnalytics = /** @class */ (function () {
             isAutocaptureEnabled: function (t) { return _this.isAutocaptureEnabled(t); },
             signature: function (params, properties) { return _this.signature(params, properties); },
             transaction: function (params, properties) { return _this.transaction(params, properties); },
+            // Hybrid capture: in wagmi mode the wrapper skips a request that a
+            // PENDING wagmi mutation already covers - the mutation handler
+            // captures it with ABI enrichment - and captures everything else
+            // (imperative viem calls that create no mutation).
+            shouldSkipRequestCapture: function (method, params) { var _a, _b; return (_b = (_a = _this.wagmiHandler) === null || _a === void 0 ? void 0 : _a.hasMatchingPendingMutation(method, params)) !== null && _b !== void 0 ? _b : false; },
         });
         this.evmEvents = new EvmEventTracker(this.wallet, this.evm, {
             isAutocaptureEnabled: function (t) { return _this.isAutocaptureEnabled(t); },
@@ -373,12 +387,8 @@ var FormoAnalytics = /** @class */ (function () {
         // re-attached to the next session's events.
         session().remove(SESSION_TRAFFIC_SOURCE_KEY);
     };
-    /**
-     * Clean up resources and event listeners
-     * Call this when destroying the analytics instance
-     * @returns {void}
-     */
     FormoAnalytics.prototype.cleanup = function () {
+        this.isCleanedUp = true;
         logger.debug("FormoAnalytics: Cleaning up resources");
         // Close the queue, don't just empty it. clear() only drops what is
         // buffered at this instant; asynchronous work already in flight (event
@@ -1014,7 +1024,21 @@ var FormoAnalytics = /** @class */ (function () {
      * @returns {void}
      */
     FormoAnalytics.prototype.optInTracking = function () {
+        var _this = this;
         var _a;
+        // A provider registered while the visitor was opted out had its
+        // session adoption refused; nothing else retries it. Guarded: a
+        // cleanup() racing this timer must not drive the torn-down tracker.
+        setTimeout(function () {
+            if (_this.isCleanedUp)
+                return;
+            try {
+                _this.evmEvents.retryExternalAdoptions();
+            }
+            catch (_a) {
+                /* adoption retry must never break opt-in */
+            }
+        }, 0);
         logger.info("Opting back into tracking");
         // Remove opt-out flag
         removeConsentFlag(this.writeKey, CONSENT_OPT_OUT_KEY);
@@ -1105,6 +1129,17 @@ var FormoAnalytics = /** @class */ (function () {
         return __awaiter(this, void 0, void 0, function () {
             var _this = this;
             return __generator(this, function (_a) {
+                // A route change can end path-based suppression; a provider registered
+                // while suppressed gets its refused session adoption retried here.
+                // Idempotent and cheap when nothing is pending.
+                if (!this.isCleanedUp) {
+                    try {
+                        this.evmEvents.retryExternalAdoptions();
+                    }
+                    catch (_b) {
+                        /* never let the retry break a page hit */
+                    }
+                }
                 if (!this.shouldTrack()) {
                     logger.info("Track page hit: Skipping event due to tracking configuration");
                     return [2 /*return*/];
@@ -1272,6 +1307,140 @@ var FormoAnalytics = /** @class */ (function () {
     };
     // Explicitly untrack a provider: remove listeners, clear wrapper flag
     // and tracking
+    /**
+     * Track an EIP-1193 provider the page constructed itself.
+     *
+     * Discovery covers EIP-6963 announcements and `window.ethereum`, which is
+     * every injected wallet and nothing else. WalletConnect and Ledger
+     * providers are built by the app (`EthereumProvider.init(...)`) and
+     * announce nothing, so their sessions were invisible: connects,
+     * signatures, and transactions all silently missing. Hand the provider
+     * here once it exists and it takes the exact pipeline a discovered
+     * provider takes - detect event, lifecycle listeners, request wrapper -
+     * and a session that is already live is adopted from the provider's
+     * synchronous state.
+     *
+     * Metadata resolution order: the caller's `info` overrides win; then a
+     * WalletConnect session's peer metadata, which names the REAL wallet on
+     * the far side of the transport (for example "Ledger Live"); then flag
+     * sniffing; then a generic fallback. One deliberate exception: a caller
+     * name of exactly "WalletConnect" is the generic transport name, so the
+     * live peer still replaces it on events - name the provider anything
+     * else to pin it verbatim.
+     *
+     * No-op outside the EIP-1193 path: in wagmi mode the connector system
+     * already tracks these sessions, and wrapping the same provider twice
+     * would double-report every event.
+     *
+     * With several live SDK instances (multi write-key pages) registering
+     * the SAME provider, request-derived events (signatures, transactions)
+     * go to the most recently CREATED live instance, regardless of the
+     * order registrations happen to land in - the same single-observer
+     * semantics discovery has always had for the request wrapper. Lifecycle events (connect, chain, disconnect) reach every
+     * instance. Fanning request observations out to all instances is a
+     * separate feature.
+     *
+     * @returns true when the provider is (now) tracked, false when it was
+     * refused (wagmi mode, EVM disabled, or not a valid EIP-1193 provider).
+     *
+     * @example
+     * ```typescript
+     * const wcProvider = await EthereumProvider.init({ projectId, chains });
+     * formo.registerProvider(wcProvider);
+     * ```
+     */
+    /**
+     * INTERNAL. Install the request wrapper on a wagmi connector's provider.
+     *
+     * Wagmi mode watches the store and caches, which see hook-driven calls
+     * only; imperative viem calls (walletClient.sendTransaction,
+     * .signMessage, .writeContract, raw request) create no mutation and were
+     * silently lost. Every viem client in a wagmi app is built on the
+     * connector's EIP-1193 provider, so wrapping that provider closes the
+     * gap. Lifecycle (connect/chain/disconnect) stays store-driven: only the
+     * request wrapper installs here. Double counting is prevented in the
+     * wrapper via `shouldSkipRequestCapture`.
+     */
+    FormoAnalytics.prototype._wrapWagmiProvider = function (provider, chainId) {
+        if (this.isCleanedUp || !isValidProvider(provider))
+            return false;
+        try {
+            // The tracker reports refusals (frozen provider, unrebindable
+            // wrapper) by returning false rather than throwing; treat those as
+            // failures too so the caller can retry later.
+            if (!this.evmRequests.registerRequestListeners(provider)) {
+                return false;
+            }
+            if (chainId !== undefined) {
+                this.evm.rememberChain(provider, chainId);
+            }
+            return true;
+        }
+        catch (e) {
+            logger.warn("Failed to wrap wagmi provider for hybrid capture", e);
+            return false;
+        }
+    };
+    /** INTERNAL. Chain updates for the fallback-wrapped provider. */
+    FormoAnalytics.prototype._rememberWagmiProviderChain = function (provider, chainId) {
+        if (this.isCleanedUp)
+            return;
+        try {
+            this.evm.rememberChain(provider, chainId);
+        }
+        catch (_a) {
+            /* bookkeeping only */
+        }
+    };
+    FormoAnalytics.prototype.registerProvider = function (provider, info) {
+        var _a, _b, _c;
+        if (this.isCleanedUp) {
+            // Cleanup terminally closed the event queue; listeners attached now
+            // would hold this instance forever and deliver nothing.
+            logger.warn("registerProvider: instance is cleaned up; refusing");
+            return false;
+        }
+        if (this.isEvmDisabled) {
+            logger.warn("registerProvider: EVM tracking is disabled; refusing");
+            return false;
+        }
+        if (this.isWagmiMode) {
+            logger.warn("registerProvider: wagmi mode tracks connectors already; registering the provider here would double-report its events. Refusing.");
+            return false;
+        }
+        if (!isValidProvider(provider)) {
+            logger.warn("registerProvider: not a valid EIP-1193 provider; refusing");
+            return false;
+        }
+        var detected = detectInjectedProviderInfo(provider);
+        var peer = readWalletConnectPeer(provider);
+        // A live peer identifies the session as WalletConnect even when the
+        // provider carries no isWalletConnect flag (v2 providers often do not).
+        var rdns = (_a = info === null || info === void 0 ? void 0 : info.rdns) !== null && _a !== void 0 ? _a : (peer && detected.rdns === "io.injected.provider"
+            ? "com.walletconnect"
+            : detected.rdns);
+        // The peer name is deliberately NOT stored: sessions change wallets,
+        // and metadata frozen at registration would misname every later one.
+        // `infoFor` resolves the peer live on each read, over the generic
+        // transport name; a caller's explicit name still wins everywhere.
+        var name = (_b = info === null || info === void 0 ? void 0 : info.name) !== null && _b !== void 0 ? _b : (peer ? "WalletConnect" : detected.name);
+        // Per-instance uuid: EIP-6963 consumers (mipd included) deduplicate on
+        // it, so two registered instances sharing an rdns-derived uuid would
+        // collapse into one. Random when the platform provides it; a
+        // monotonic suffix otherwise.
+        var uuid = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+            ? crypto.randomUUID()
+            : "registered-".concat(rdns.replace(/[^a-zA-Z0-9]/g, "-"), "-").concat((FormoAnalytics.registeredProviderSeq += 1));
+        return this.evmEvents.adoptExternalProvider({
+            info: {
+                name: name,
+                rdns: rdns,
+                uuid: uuid,
+                icon: (_c = info === null || info === void 0 ? void 0 : info.icon) !== null && _c !== void 0 ? _c : detected.icon,
+            },
+            provider: provider,
+        });
+    };
     // Debug/monitoring helpers
     FormoAnalytics.prototype.getTrackedProvidersCount = function () {
         return this.evm.counts.trackedProviders;
@@ -1283,6 +1452,8 @@ var FormoAnalytics = /** @class */ (function () {
     FormoAnalytics.prototype.getProviderState = function () {
         return __assign(__assign({}, this.evm.counts), { activeProvider: !!this._provider });
     };
+    /** Fallback uuid suffix for platforms without crypto.randomUUID. */
+    FormoAnalytics.registeredProviderSeq = 0;
     return FormoAnalytics;
 }());
 export { FormoAnalytics };

package/dist/esm/src/FormoAnalyticsProvider.d.ts

@@ -7,6 +7,14 @@ export interface FormoAnalyticsProviderProps {
     children: ReactNode;
 }
 export declare const FormoAnalyticsContext: import("react").Context<IFormoAnalytics>;
+/**
+ * A stable key over the serializable parts of Options. The provider effect
+ * re-initialises the SDK when this key changes; anything that alters SDK
+ * behaviour must be represented here, or a runtime change to it is silently
+ * ignored. Complex objects are tracked by presence, plus the flags that
+ * change what the SDK does with them.
+ */
+export declare const computeOptionsKey: (options?: Options) => string;
 export declare const FormoAnalyticsProvider: FC<FormoAnalyticsProviderProps>;
 export declare const useFormo: () => IFormoAnalytics;
 //# sourceMappingURL=FormoAnalyticsProvider.d.ts.map

package/dist/esm/src/FormoAnalyticsProvider.js

@@ -55,6 +55,7 @@ var defaultContext = {
     page: function () { return Promise.resolve(); },
     reset: function () { },
     cleanup: function () { },
+    registerProvider: function () { return false; },
     detect: function () { return Promise.resolve(); },
     connect: function () { return Promise.resolve(); },
     disconnect: function () { return Promise.resolve(); },
@@ -68,6 +69,44 @@ var defaultContext = {
     hasOptedOutTracking: function () { return false; },
 };
 export var FormoAnalyticsContext = createContext(defaultContext);
+/**
+ * A stable key over the serializable parts of Options. The provider effect
+ * re-initialises the SDK when this key changes; anything that alters SDK
+ * behaviour must be represented here, or a runtime change to it is silently
+ * ignored. Complex objects are tracked by presence, plus the flags that
+ * change what the SDK does with them.
+ */
+export var computeOptionsKey = function (options) {
+    var _a;
+    if (!options)
+        return 'undefined';
+    var serializableOptions = {
+        tracking: options.tracking,
+        autocapture: options.autocapture,
+        crossSubdomainCookies: options.crossSubdomainCookies,
+        apiHost: options.apiHost,
+        flushAt: options.flushAt,
+        flushInterval: options.flushInterval,
+        retryCount: options.retryCount,
+        maxQueueSize: options.maxQueueSize,
+        logger: options.logger,
+        referral: options.referral,
+        evm: options.evm,
+        // For complex objects, just track their presence, not their content
+        hasProvider: !!options.provider,
+        hasWagmi: !!options.wagmi,
+        wagmiEip1193Fallback: !!((_a = options.wagmi) === null || _a === void 0 ? void 0 : _a.eip1193Fallback),
+        hasReady: !!options.ready,
+    };
+    try {
+        return JSON.stringify(serializableOptions);
+    }
+    catch (error) {
+        // Fallback to timestamp if serialization fails
+        logger.warn('Failed to serialize options, using timestamp', error);
+        return Date.now().toString();
+    }
+};
 export var FormoAnalyticsProvider = function (props) {
     var writeKey = props.writeKey, _a = props.disabled, disabled = _a === void 0 ? false : _a, children = props.children;
     // Keep the app running without analytics if no Write Key is provided or disabled
@@ -86,37 +125,7 @@ var InitializedAnalytics = function (_a) {
     var _b = useState(defaultContext), sdk = _b[0], setSdk = _b[1];
     var sdkRef = useRef(defaultContext);
     initStorageManager(writeKey);
-    // Create a stable key from options that ignores complex objects and functions
-    // We only care about serializable config values that would affect SDK behavior
-    var optionsKey = useMemo(function () {
-        if (!options)
-            return 'undefined';
-        // Extract only the serializable parts of options
-        var serializableOptions = {
-            tracking: options.tracking,
-            autocapture: options.autocapture,
-            crossSubdomainCookies: options.crossSubdomainCookies,
-            apiHost: options.apiHost,
-            flushAt: options.flushAt,
-            flushInterval: options.flushInterval,
-            retryCount: options.retryCount,
-            maxQueueSize: options.maxQueueSize,
-            logger: options.logger,
-            referral: options.referral,
-            // For complex objects, just track their presence, not their content
-            hasProvider: !!options.provider,
-            hasWagmi: !!options.wagmi,
-            hasReady: !!options.ready,
-        };
-        try {
-            return JSON.stringify(serializableOptions);
-        }
-        catch (error) {
-            // Fallback to timestamp if serialization fails
-            logger.warn('Failed to serialize options, using timestamp', error);
-            return Date.now().toString();
-        }
-    }, [options]);
+    var optionsKey = useMemo(function () { return computeOptionsKey(options); }, [options]);
     useEffect(function () {
         var isCleanedUp = false;
         var initialize = function () { return __awaiter(void 0, void 0, void 0, function () {

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

@@ -43,20 +43,19 @@ export interface EvmEventTrackerDeps {
      */
     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;
+    /**
+     * Providers adopted through `registerProvider` rather than discovered.
+     * Announcement-driven cleanup must not touch them: they are never in an
+     * announcement list, so "missing from the announcement" is their normal
+     * state, not evidence of removal. A Set rather than a WeakSet because
+     * suppressed adoptions retry from it; the registry holds these providers
+     * strongly anyway, and untrack removes them.
+     */
+    private externallyRegistered;
     /**
      * The connect this SDK has already reported for a provider.
      *
@@ -91,6 +90,35 @@ export declare class EvmEventTracker {
      */
     trackEIP1193Provider(provider: EIP1193Provider): void;
     trackProviders(providers: readonly EIP6963ProviderDetail[]): void;
+    /**
+     * Adopt a provider the page constructed rather than announced.
+     *
+     * Discovery only ever sees EIP-6963 announcements and `window.ethereum`.
+     * A WalletConnect or Ledger provider is a constructed object that does
+     * neither, so without this entry point its whole session is invisible -
+     * the P-2403 gap. The pipeline from here on is the same one every
+     * discovered provider takes: registry, detect event, listeners, request
+     * wrapper.
+     *
+     * A session that already exists at registration is seeded from the
+     * provider's SYNCHRONOUS `accounts` state (WalletConnect exposes it), via
+     * the same accounts-arrival path a live `accountsChanged` takes. No RPC:
+     * nothing analytics-only may go on a wallet's transport, and
+     * WalletConnect's serialised relay socket is the very case that rule
+     * exists for.
+     */
+    adoptExternalProvider(detail: EIP6963ProviderDetail): boolean;
+    /**
+     * Re-run session adoption for every registered external provider.
+     *
+     * Registration while tracking was suppressed (opt-out, excluded route)
+     * reached the adoption path and was refused - and a provider whose
+     * session already exists may never emit another accountsChanged, so
+     * nothing would ever retry. Called when suppression can have ended
+     * (opt-in, page navigation). Idempotent: an already-adopted wallet is
+     * deduplicated by the same state and markers as any repeated signal.
+     */
+    retryExternalAdoptions(): void;
     private registerAccountsChangedListener;
     private onAccountsChanged;
     /**