@formo/analytics 1.38.2 → 1.40.0

package/dist/esm/src/solana/SolanaManager.js

@@ -1,32 +1,124 @@
 /**
  * SolanaManager
  *
- * Manages the lifecycle of the Solana store integration.
- * Subscribes to framework-kit's zustand store for automatic event capture
- * of wallet connect/disconnect and transaction lifecycle events.
+ * Owns the two ways the SDK learns about Solana wallets:
  *
- * For signMessage/signTransaction tracking (not captured by the store),
+ *  1. `SolanaWalletStandardRegistry`: discovers wallets through the Wallet
+ *     Standard and reports detect / connect / disconnect. On by default, so
+ *     compatible wallets registered by Solana Kit, wallet-adapter,
+ *     framework-kit, or another host are covered with no configuration,
+ *     exactly like EVM wallets through EIP-6963. `solana: false` turns it off.
+ *  2. `SolanaStoreHandler`: subscribes to framework-kit's zustand store for
+ *     connect / disconnect / cluster changes AND the transaction lifecycle.
+ *     Opt-in through `solana: { store }` or `formo.solana.setStore()`.
+ *
+ * Both observe the same Wallet Standard connection when a framework-kit app
+ * connects. A store supplied at initialization owns wallet events; a store
+ * attached later takes ownership when it observes its first connection and
+ * adopts any connect the registry already reported. One connect per
+ * connection, whichever path an app is on.
+ *
+ * For signMessage/signTransaction tracking (not captured by either path),
  * use formo.signature() directly with the address and chainId.
  *
- * For manual event tracking without the store, use the core API directly:
+ * For manual event tracking, use the core API directly:
  * formo.transaction(), formo.signature(), formo.connect(), formo.disconnect().
  */
 import { logger } from "../logger";
 import { SolanaStoreHandler } from "./SolanaStoreHandler";
+import { SolanaWalletStandardRegistry } from "./SolanaWalletStandardRegistry";
+import { SOLANA_CLUSTERS_BY_ID, } from "./types";
 var SolanaManager = /** @class */ (function () {
-    function SolanaManager(formo, options) {
+    /**
+     * @param formo - The SDK instance events are reported to.
+     * @param options - `options.solana` as passed to the SDK, if an object.
+     * @param enabled - Whether Solana tracking is enabled. False only when the
+     *   host app passed `solana: false`; both discovery and stores then stay off.
+     */
+    function SolanaManager(formo, options, enabled) {
+        if (enabled === void 0) { enabled = true; }
+        var _this = this;
         this.formo = formo;
-        if (options === null || options === void 0 ? void 0 : options.store) {
-            logger.info("SolanaManager: Initializing store-based Solana tracking");
-            this.storeHandler = new SolanaStoreHandler(formo, options.store, {
-                cluster: options.cluster,
-            });
-        }
-        else if (options === null || options === void 0 ? void 0 : options.cluster) {
+        this.enabled = enabled;
+        this.storeOwnsWalletEvents = false;
+        if (!enabled)
+            return;
+        if (options === null || options === void 0 ? void 0 : options.cluster) {
             // Store pending cluster for when setStore is called later
             this.pendingCluster = options.cluster;
         }
+        // A store supplied at initialization owns wallet events from the outset:
+        // unlike a store attached later, it has not missed any prior registry
+        // state and it knows the cluster more precisely.
+        this.storeOwnsWalletEvents = !!(options === null || options === void 0 ? void 0 : options.store);
+        this.registry = new SolanaWalletStandardRegistry({
+            isAutocaptureEnabled: function (t) { return _this.formo.isAutocaptureEnabled(t); },
+            willTrackEvent: function (chainId) { return _this.formo.willTrackEvent(chainId); },
+            detect: function (params) { return _this.formo.detect(params); },
+            connect: function (params, properties) {
+                return _this.formo.connect(params, properties);
+            },
+            disconnect: function (params) { return _this.formo.disconnect(params); },
+            chain: function (params) { return _this.formo.chain(params); },
+            syncWalletState: function (params) { return _this.formo.syncWalletState(params); },
+            currentAddress: function () { return _this.formo.currentAddress; },
+            ownsWalletEvents: function () { return !_this.storeOwnsWalletEvents; },
+        }, { cluster: options === null || options === void 0 ? void 0 : options.cluster });
+        if (options === null || options === void 0 ? void 0 : options.store) {
+            logger.info("SolanaManager: Initializing store-based Solana tracking");
+            this.attachStore(options.store, options.cluster);
+        }
     }
+    SolanaManager.prototype.attachStore = function (store, cluster) {
+        var _this = this;
+        var _a;
+        this.storeHandler = new SolanaStoreHandler(this.formo, store, {
+            cluster: cluster,
+            beforeWalletConnect: function (connection) {
+                var _a, _b;
+                // The store's cluster is authoritative even when chain autocapture is
+                // disabled. Keep central attribution correct without manufacturing a
+                // chain event in that mode.
+                _this.formo.syncWalletState({
+                    address: connection.address,
+                    chainId: connection.chainId,
+                });
+                if (_this.storeOwnsWalletEvents)
+                    return true;
+                var reported = (_a = _this.registry) === null || _a === void 0 ? void 0 : _a.takeReportedConnection(connection.address, connection.rdns);
+                _this.storeOwnsWalletEvents = true;
+                // If Wallet Standard got there first, the store adopts that live
+                // connection instead of emitting it again. Correct its cluster if
+                // the store has more precise information.
+                if (!reported) {
+                    // Nothing to adopt. Either the registry never reported this
+                    // connection, or it reported it under another identity, in which
+                    // case the store is about to emit a second connect for the same
+                    // live connection. Both paths derive the rdns from the wallet's
+                    // own name, so a mismatch means the store's connector is labelled
+                    // differently from the registered wallet.
+                    var held = (_b = _this.registry) === null || _b === void 0 ? void 0 : _b.reportedConnectionRdns(connection.address);
+                    if (held) {
+                        logger.warn("SolanaManager: Store connector does not match the discovered wallet; the connection is reported twice", { storeRdns: connection.rdns, walletRdns: held });
+                    }
+                    return true;
+                }
+                if (reported.chainId !== connection.chainId &&
+                    _this.formo.isAutocaptureEnabled("chain")) {
+                    _this.formo.chain(connection).catch(function (error) {
+                        logger.error("SolanaManager: Error correcting cluster during store handoff", error);
+                    });
+                }
+                return false;
+            },
+        });
+        // Keep the registry's snapshot on the store's detected cluster. This is
+        // silent once the store owns events; during a late handoff it corrects a
+        // registry-reported connection before the store adopts it.
+        var detectedCluster = SOLANA_CLUSTERS_BY_ID[this.storeHandler.getChainId()];
+        if (detectedCluster)
+            (_a = this.registry) === null || _a === void 0 ? void 0 : _a.setCluster(detectedCluster);
+    };
     /**
      * Set the framework-kit zustand store for automatic event tracking.
      * This enables autocapture mode — connect/disconnect and transaction events
@@ -45,29 +137,52 @@ var SolanaManager = /** @class */ (function () {
      */
     SolanaManager.prototype.setStore = function (store, options) {
         var _a;
+        if (!this.enabled) {
+            logger.warn("SolanaManager: Ignoring setStore. Solana tracking is off for this instance (solana: false, or the SDK was cleaned up)");
+            return;
+        }
         (_a = this.storeHandler) === null || _a === void 0 ? void 0 : _a.cleanup();
-        this.storeHandler = new SolanaStoreHandler(this.formo, store, {
-            cluster: (options === null || options === void 0 ? void 0 : options.cluster) || this.pendingCluster,
-        });
+        this.storeHandler = undefined;
+        this.storeOwnsWalletEvents = false;
+        this.attachStore(store, (options === null || options === void 0 ? void 0 : options.cluster) || this.pendingCluster);
         this.pendingCluster = undefined;
     };
     /**
-     * Update the cluster/network. Only needed if the store endpoint doesn't
-     * contain a recognizable cluster name (e.g. custom RPC URLs).
-     * In most cases, the cluster is auto-detected from the store's endpoint.
+     * Update the cluster/network.
+     *
+     * With a framework-kit store, only needed if the store endpoint doesn't
+     * contain a recognizable cluster name (e.g. custom RPC URLs). Without one,
+     * this is how a non-mainnet app tells the SDK which cluster its Wallet
+     * Standard connections are on, since the standard itself cannot say.
      */
     SolanaManager.prototype.setCluster = function (cluster) {
+        var _a;
+        if (!this.enabled)
+            return;
         if (this.storeHandler) {
             this.storeHandler.setCluster(cluster);
         }
         else {
             this.pendingCluster = cluster;
         }
+        (_a = this.registry) === null || _a === void 0 ? void 0 : _a.setCluster(cluster);
     };
+    Object.defineProperty(SolanaManager.prototype, "discoveredWallets", {
+        /** Names of the Wallet Standard wallets discovered so far. */
+        get: function () {
+            var _a, _b;
+            return (_b = (_a = this.registry) === null || _a === void 0 ? void 0 : _a.walletNames) !== null && _b !== void 0 ? _b : [];
+        },
+        enumerable: false,
+        configurable: true
+    });
     SolanaManager.prototype.cleanup = function () {
-        var _a;
+        var _a, _b;
         (_a = this.storeHandler) === null || _a === void 0 ? void 0 : _a.cleanup();
         this.storeHandler = undefined;
+        this.storeOwnsWalletEvents = false;
+        (_b = this.registry) === null || _b === void 0 ? void 0 : _b.cleanup();
+        this.registry = undefined;
     };
     return SolanaManager;
 }());

package/dist/esm/src/solana/SolanaStoreHandler.d.ts

@@ -48,8 +48,14 @@ export declare class SolanaStoreHandler {
      * When true, auto-detection from the store endpoint is disabled.
      */
     private explicitCluster;
+    private beforeWalletConnect?;
     constructor(formoAnalytics: FormoAnalytics, store: SolanaClientStore, options?: {
         cluster?: SolanaCluster;
+        beforeWalletConnect?: (connection: {
+            address: string;
+            chainId: number;
+            rdns: string;
+        }) => boolean;
     });
     /**
      * Update the cluster/network.

package/dist/esm/src/solana/SolanaStoreHandler.js

@@ -25,7 +25,7 @@ var __assign = (this && this.__assign) || function () {
 };
 import { TransactionStatus } from "../types/events";
 import { logger } from "../logger";
-import { SOLANA_CHAIN_IDS } from "./types";
+import { SOLANA_CHAIN_IDS, solanaWalletRdns, } from "./types";
 import { isBlockedSolanaAddress } from "./address";
 /**
  * Clean up old entries from a Set to prevent memory leaks.
@@ -66,6 +66,7 @@ var SolanaStoreHandler = /** @class */ (function () {
         this.formo = formoAnalytics;
         this.store = store;
         this.explicitCluster = !!(options === null || options === void 0 ? void 0 : options.cluster);
+        this.beforeWalletConnect = options === null || options === void 0 ? void 0 : options.beforeWalletConnect;
         this.cluster = (options === null || options === void 0 ? void 0 : options.cluster) || this.detectClusterFromStore(store) || "mainnet-beta";
         this.chainId = SOLANA_CHAIN_IDS[this.cluster];
         logger.info("SolanaStoreHandler: Initializing framework-kit store integration", {
@@ -138,7 +139,7 @@ var SolanaStoreHandler = /** @class */ (function () {
         logger.info("SolanaStoreHandler: Wallet subscription set up");
     };
     SolanaStoreHandler.prototype.checkInitialWalletState = function () {
-        var _a;
+        var _a, _b, _c;
         var state = this.store.getState();
         var wallet = state.wallet;
         if (wallet.status === "connected") {
@@ -151,11 +152,17 @@ var SolanaStoreHandler = /** @class */ (function () {
                     address: address,
                     chainId: this.chainId,
                 });
-                if (this.formo.isAutocaptureEnabled("connect")) {
-                    var connectorName = ((_a = wallet.session.connector) === null || _a === void 0 ? void 0 : _a.name) || wallet.connectorId;
+                var connectorName = ((_a = wallet.session.connector) === null || _a === void 0 ? void 0 : _a.name) || wallet.connectorId;
+                var rdns = solanaWalletRdns(connectorName);
+                var shouldEmit = (_c = (_b = this.beforeWalletConnect) === null || _b === void 0 ? void 0 : _b.call(this, {
+                    address: address,
+                    chainId: this.chainId,
+                    rdns: rdns,
+                })) !== null && _c !== void 0 ? _c : true;
+                if (shouldEmit && this.formo.isAutocaptureEnabled("connect")) {
                     this.formo.connect({ chainId: this.chainId, address: address }, {
                         providerName: connectorName,
-                        rdns: "sol.wallet.".concat(connectorName.toLowerCase().replace(/\s+/g, "")),
+                        rdns: rdns,
                     }).catch(function (error) {
                         logger.error("SolanaStoreHandler: Error emitting initial connect", error);
                     });
@@ -187,7 +194,7 @@ var SolanaStoreHandler = /** @class */ (function () {
         this.lastWalletStatus = wallet.status;
     };
     SolanaStoreHandler.prototype.handleConnect = function (wallet) {
-        var _a;
+        var _a, _b, _c;
         var address = wallet.session.account.address;
         if (!address || isBlockedSolanaAddress(address)) {
             return;
@@ -203,11 +210,13 @@ var SolanaStoreHandler = /** @class */ (function () {
             chainId: chainId,
             connector: wallet.connectorId,
         });
-        if (this.formo.isAutocaptureEnabled("connect")) {
-            var connectorName = ((_a = wallet.session.connector) === null || _a === void 0 ? void 0 : _a.name) || wallet.connectorId;
+        var connectorName = ((_a = wallet.session.connector) === null || _a === void 0 ? void 0 : _a.name) || wallet.connectorId;
+        var rdns = solanaWalletRdns(connectorName);
+        var shouldEmit = (_c = (_b = this.beforeWalletConnect) === null || _b === void 0 ? void 0 : _b.call(this, { address: address, chainId: chainId, rdns: rdns })) !== null && _c !== void 0 ? _c : true;
+        if (shouldEmit && this.formo.isAutocaptureEnabled("connect")) {
             this.formo.connect({ chainId: chainId, address: address }, {
                 providerName: connectorName,
-                rdns: "sol.wallet.".concat(connectorName.toLowerCase().replace(/\s+/g, "")),
+                rdns: rdns,
             }).catch(function (error) {
                 logger.error("SolanaStoreHandler: Error emitting connect", error);
             });

package/dist/esm/src/solana/SolanaWalletStandardRegistry.d.ts

@@ -0,0 +1,163 @@
+/**
+ * SolanaWalletStandardRegistry
+ *
+ * Which Solana wallets exist, and whether each is connected. The Solana
+ * analogue of `EvmProviderRegistry` + EIP-6963.
+ *
+ * Compatible wallets (Phantom, Solflare, Backpack, ...) announce themselves
+ * through the Wallet Standard's window-event handshake. Solana Kit,
+ * wallet-adapter, and framework-kit use these registered wallets. Observing
+ * the handshake covers those wallets without coupling Formo to the host
+ * library: the registry announces `wallet-standard:app-ready`, listens for
+ * `wallet-standard:register-wallet`, and subscribes to each wallet's
+ * `standard:events` `change` event.
+ *
+ * What it reports:
+ *  - `detect` when a wallet registers (session-deduped by the SDK on rdns).
+ *  - `connect` when a wallet's Solana accounts go from none to some, or the
+ *    first account changes; `disconnect` when they go from some to none.
+ *  - `chain` when the configured cluster changes while a wallet is connected.
+ *
+ * What it does not do: wrap any wallet method, issue any request to a
+ * wallet, or depend on `@wallet-standard/*` (the handshake is a few lines,
+ * and the SDK's dependency policy is two runtime dependencies, forever).
+ *
+ * Cluster: the Wallet Standard lists every cluster a wallet SUPPORTS, not
+ * the one the app is using, so the cluster is `options.solana.cluster` when
+ * given, else mainnet-beta when the wallet supports it, else the first
+ * Solana cluster it lists. A framework-kit app gets the cluster from its
+ * store instead, through `SolanaStoreHandler`.
+ *
+ * @see https://github.com/wallet-standard/wallet-standard
+ */
+import type { AutocaptureEventType } from "../tracking/TrackingPolicy";
+import { SolanaCluster, UnsubscribeFn } from "./types";
+/** What the registry needs from the SDK that owns it. */
+export interface SolanaWalletStandardRegistryDeps {
+    isAutocaptureEnabled(eventType: AutocaptureEventType): boolean;
+    willTrackEvent(chainId: number): boolean;
+    detect(params: {
+        providerName: string;
+        rdns: string;
+    }): Promise<void>;
+    connect(params: {
+        chainId: number;
+        address: string;
+    }, properties: {
+        providerName: string;
+        rdns: string;
+    }): Promise<void>;
+    disconnect(params: {
+        chainId: number;
+        address: string;
+    }): Promise<void>;
+    chain(params: {
+        chainId: number;
+        address: string;
+    }): Promise<void>;
+    /**
+     * Record wallet and chain state centrally WITHOUT emitting an event.
+     *
+     * Observing a chain is not the same as reporting one: the exclusion gate
+     * keys off the central chain, so a cluster switch has to land there even
+     * when `autocapture.chain` is off. The EVM tracker separates the two the
+     * same way.
+     * @see FormoAnalytics.syncWalletState
+     */
+    syncWalletState(params: {
+        chainId: number;
+        address: string;
+    }): void;
+    /** The wallet the SDK currently treats as active, across namespaces. */
+    currentAddress(): string | undefined;
+    /**
+     * Whether THIS registry reports connections.
+     *
+     * A framework-kit app connects through the very same Wallet Standard
+     * wallet, so its store and this registry both see every connection. The
+     * store is the better witness there (it knows the cluster and connector),
+     * so once it has observed or adopted a connection the registry keeps
+     * discovering wallets and emitting `detect`, but leaves connect and
+     * disconnect to the store. Exactly one connect per connection, either way.
+     */
+    ownsWalletEvents(): boolean;
+}
+export interface SolanaWalletStandardRegistryOptions {
+    /** The cluster the app uses. Overrides what is derived from the wallet. */
+    cluster?: SolanaCluster;
+}
+export declare class SolanaWalletStandardRegistry {
+    private readonly deps;
+    private wallets;
+    private cluster?;
+    private removeWindowListener?;
+    /** Set by cleanup(); a torn-down registry refuses late registrations. */
+    private isCleanedUp;
+    /**
+     * Handed to every wallet. Wallets keep it and may call `register` long
+     * after the handshake, which is why `register` checks `isCleanedUp`.
+     */
+    private readonly api;
+    constructor(deps: SolanaWalletStandardRegistryDeps, options?: SolanaWalletStandardRegistryOptions);
+    /**
+     * The Wallet Standard handshake, both directions.
+     *
+     * A wallet injected before us hears `app-ready` and registers at once; a
+     * wallet injected after us dispatches `register-wallet`, which we answer.
+     * Neither is optional: an extension's content script and the app's bundle
+     * race, and which one wins differs per page load.
+     */
+    private listen;
+    /**
+     * Add wallets once. Returns an unregister function, as the standard asks.
+     *
+     * Public so an integration that already holds a wallet object (its own
+     * `getWallets()` call, say) can hand it over without the window handshake.
+     */
+    register(...wallets: unknown[]): UnsubscribeFn;
+    private track;
+    private untrack;
+    private onChange;
+    /**
+     * Compare what the wallet now authorizes with what was last reported.
+     *
+     * none → some is a connect, some → none a disconnect, and a different
+     * first account is a disconnect followed by a connect, matching what the
+     * framework-kit store handler reports for the same transitions.
+     */
+    private reconcile;
+    private reportConnect;
+    private reportDisconnect;
+    /**
+     * The chain id to report for a wallet.
+     *
+     * The Wallet Standard cannot say which cluster the app is on, only which
+     * ones the wallet supports, so an explicit cluster wins, then mainnet-beta
+     * if supported (nearly every wallet lists every cluster, and production
+     * traffic is mainnet), then the first cluster listed.
+     */
+    private chainIdFor;
+    /**
+     * Set the cluster the app uses. A connected wallet's chain id follows,
+     * with a `chain` event, the same as the store handler on a cluster switch.
+     */
+    setCluster(cluster: SolanaCluster): void;
+    /** Names of every wallet discovered so far, for the debug helpers. */
+    get walletNames(): string[];
+    /**
+     * The rdns this registry reported a still-live connect for `address`
+     * under, if any. Lets a failed store adoption name both identities.
+     */
+    reportedConnectionRdns(address: string): string | undefined;
+    /**
+     * Transfer a connect already emitted by this registry to a store handler.
+     * The state remains connected, but the same transition must not be emitted
+     * a second time when framework-kit's store catches up.
+     */
+    takeReportedConnection(address: string, rdns: string): {
+        address: string;
+        chainId: number;
+    } | undefined;
+    cleanup(): void;
+}
+//# sourceMappingURL=SolanaWalletStandardRegistry.d.ts.map