@formo/analytics 1.28.4 → 1.28.6

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

@@ -0,0 +1,88 @@
+/**
+ * SolanaStoreHandler
+ *
+ * Handles wallet event tracking by subscribing to framework-kit's zustand store.
+ * This provides automatic event capture (autocapture) for Solana wallets without
+ * wrapping any wallet methods — similar to how WagmiEventHandler subscribes to
+ * TanStack Query's mutation/query caches.
+ *
+ * Subscribes to:
+ * - `state.wallet` — connect/disconnect events
+ * - `state.transactions` — transaction lifecycle events (sending → confirmed/failed)
+ *
+ * @see https://github.com/solana-foundation/framework-kit
+ */
+import { FormoAnalytics } from "../FormoAnalytics";
+import { SolanaClientStore } from "./storeTypes";
+import { SolanaCluster } from "./types";
+export declare class SolanaStoreHandler {
+    private formo;
+    private store;
+    private unsubscribers;
+    private cluster;
+    private chainId;
+    /**
+     * Track last known wallet status to detect transitions.
+     */
+    private lastWalletStatus;
+    private lastAddress?;
+    private lastChainId?;
+    /**
+     * Track processed transaction state changes to prevent duplicate events.
+     * Key format: `${signature}:${status}`
+     */
+    private processedTransactions;
+    /**
+     * Track transactions we've emitted STARTED for (status was "sending").
+     * Ensures we only emit STARTED once per transaction key.
+     */
+    private startedTransactions;
+    /**
+     * Per-transaction sender address captured at STARTED time.
+     * Ensures terminal events (confirmed/failed) are attributed correctly
+     * even if the wallet disconnects before the transaction settles.
+     */
+    private transactionSenders;
+    /**
+     * Whether the cluster was explicitly set (via options or setCluster).
+     * When true, auto-detection from the store endpoint is disabled.
+     */
+    private explicitCluster;
+    constructor(formoAnalytics: FormoAnalytics, store: SolanaClientStore, options?: {
+        cluster?: SolanaCluster;
+    });
+    /**
+     * Update the cluster/network.
+     */
+    setCluster(cluster: SolanaCluster): void;
+    /**
+     * Get the current chain ID.
+     */
+    getChainId(): number;
+    /**
+     * Resolve the current chainId from the live store state.
+     * This ensures correctness when wallet and cluster change in the same tick
+     * (the cluster subscription may not have fired yet).
+     */
+    private resolveCurrentChainId;
+    private setupWalletSubscription;
+    private checkInitialWalletState;
+    private handleWalletChange;
+    private handleConnect;
+    private handleDisconnect;
+    private setupClusterSubscription;
+    private handleClusterChange;
+    private setupTransactionSubscription;
+    private handleTransactionChanges;
+    private handleTransactionStatusChange;
+    /**
+     * Attempt to detect the Solana cluster from the store's endpoint URL.
+     */
+    private detectClusterFromStore;
+    /**
+     * Detect cluster from an RPC endpoint URL.
+     */
+    private detectClusterFromEndpoint;
+    cleanup(): void;
+}
+//# sourceMappingURL=SolanaStoreHandler.d.ts.map

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

@@ -0,0 +1,468 @@
+/**
+ * SolanaStoreHandler
+ *
+ * Handles wallet event tracking by subscribing to framework-kit's zustand store.
+ * This provides automatic event capture (autocapture) for Solana wallets without
+ * wrapping any wallet methods — similar to how WagmiEventHandler subscribes to
+ * TanStack Query's mutation/query caches.
+ *
+ * Subscribes to:
+ * - `state.wallet` — connect/disconnect events
+ * - `state.transactions` — transaction lifecycle events (sending → confirmed/failed)
+ *
+ * @see https://github.com/solana-foundation/framework-kit
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+import { TransactionStatus } from "../types/events";
+import { logger } from "../logger";
+import { SOLANA_CHAIN_IDS } from "./types";
+import { isBlockedSolanaAddress } from "./address";
+/**
+ * Clean up old entries from a Set to prevent memory leaks.
+ */
+function cleanupOldEntries(set, maxSize, removeCount) {
+    if (maxSize === void 0) { maxSize = 1000; }
+    if (removeCount === void 0) { removeCount = 500; }
+    if (set.size > maxSize) {
+        var entries = Array.from(set);
+        for (var i = 0; i < removeCount && i < entries.length; i++) {
+            set.delete(entries[i]);
+        }
+    }
+}
+var SolanaStoreHandler = /** @class */ (function () {
+    function SolanaStoreHandler(formoAnalytics, store, options) {
+        this.unsubscribers = [];
+        /**
+         * Track last known wallet status to detect transitions.
+         */
+        this.lastWalletStatus = "disconnected";
+        /**
+         * Track processed transaction state changes to prevent duplicate events.
+         * Key format: `${signature}:${status}`
+         */
+        this.processedTransactions = new Set();
+        /**
+         * Track transactions we've emitted STARTED for (status was "sending").
+         * Ensures we only emit STARTED once per transaction key.
+         */
+        this.startedTransactions = new Set();
+        /**
+         * Per-transaction sender address captured at STARTED time.
+         * Ensures terminal events (confirmed/failed) are attributed correctly
+         * even if the wallet disconnects before the transaction settles.
+         */
+        this.transactionSenders = new Map();
+        this.formo = formoAnalytics;
+        this.store = store;
+        this.explicitCluster = !!(options === null || options === void 0 ? void 0 : options.cluster);
+        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", {
+            cluster: this.cluster,
+            chainId: this.chainId,
+        });
+        this.setupWalletSubscription();
+        this.setupTransactionSubscription();
+        this.setupClusterSubscription();
+        // Check initial wallet state
+        this.checkInitialWalletState();
+    }
+    /**
+     * Update the cluster/network.
+     */
+    SolanaStoreHandler.prototype.setCluster = function (cluster) {
+        this.explicitCluster = true;
+        var previousCluster = this.cluster;
+        this.cluster = cluster;
+        this.chainId = SOLANA_CHAIN_IDS[cluster];
+        if (previousCluster !== cluster && this.lastAddress) {
+            this.lastChainId = this.chainId;
+            if (this.formo.isAutocaptureEnabled("chain")) {
+                this.formo.chain({
+                    chainId: this.chainId,
+                    address: this.lastAddress,
+                }).catch(function (error) {
+                    logger.error("SolanaStoreHandler: Error emitting chain event", error);
+                });
+            }
+        }
+    };
+    /**
+     * Get the current chain ID.
+     */
+    SolanaStoreHandler.prototype.getChainId = function () {
+        return this.chainId;
+    };
+    /**
+     * Resolve the current chainId from the live store state.
+     * This ensures correctness when wallet and cluster change in the same tick
+     * (the cluster subscription may not have fired yet).
+     */
+    SolanaStoreHandler.prototype.resolveCurrentChainId = function () {
+        // Don't auto-detect if the cluster was explicitly set
+        if (!this.explicitCluster) {
+            var detected = this.detectClusterFromStore(this.store);
+            if (detected) {
+                this.cluster = detected;
+                this.chainId = SOLANA_CHAIN_IDS[detected];
+            }
+        }
+        return this.chainId;
+    };
+    // ============================================================
+    // Wallet Subscription
+    // ============================================================
+    SolanaStoreHandler.prototype.setupWalletSubscription = function () {
+        var _this = this;
+        var prevWallet = this.store.getState().wallet;
+        var unsubscribe = this.store.subscribe(function (state) {
+            var wallet = state.wallet;
+            if (wallet !== prevWallet) {
+                var prev = prevWallet;
+                prevWallet = wallet;
+                _this.handleWalletChange(wallet, prev);
+            }
+        });
+        this.unsubscribers.push(unsubscribe);
+        logger.info("SolanaStoreHandler: Wallet subscription set up");
+    };
+    SolanaStoreHandler.prototype.checkInitialWalletState = function () {
+        var _a;
+        var state = this.store.getState();
+        var wallet = state.wallet;
+        if (wallet.status === "connected") {
+            var address = wallet.session.account.address;
+            if (address && !isBlockedSolanaAddress(address)) {
+                this.lastWalletStatus = "connected";
+                this.lastAddress = address;
+                this.lastChainId = this.chainId;
+                logger.info("SolanaStoreHandler: Already connected on initialization", {
+                    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;
+                    this.formo.connect({ chainId: this.chainId, address: address }, {
+                        providerName: connectorName,
+                        rdns: "sol.wallet.".concat(connectorName.toLowerCase().replace(/\s+/g, "")),
+                    }).catch(function (error) {
+                        logger.error("SolanaStoreHandler: Error emitting initial connect", error);
+                    });
+                }
+            }
+        }
+        this.lastWalletStatus = wallet.status;
+    };
+    SolanaStoreHandler.prototype.handleWalletChange = function (wallet, prevWallet) {
+        // connected → any other state (disconnected, error, connecting)
+        if (prevWallet.status === "connected" &&
+            wallet.status !== "connected") {
+            this.handleDisconnect();
+        }
+        // * → connected (new connection)
+        if (wallet.status === "connected" && prevWallet.status !== "connected") {
+            this.handleConnect(wallet);
+        }
+        else if (wallet.status === "connected" &&
+            prevWallet.status === "connected") {
+            // connected → connected: check for account switch OR connector change
+            var addressChanged = wallet.session.account.address !== prevWallet.session.account.address;
+            var connectorChanged = wallet.connectorId !== prevWallet.connectorId;
+            if (addressChanged || connectorChanged) {
+                this.handleDisconnect();
+                this.handleConnect(wallet);
+            }
+        }
+        this.lastWalletStatus = wallet.status;
+    };
+    SolanaStoreHandler.prototype.handleConnect = function (wallet) {
+        var _a;
+        var address = wallet.session.account.address;
+        if (!address || isBlockedSolanaAddress(address)) {
+            return;
+        }
+        // Resolve chainId from live store state so batched wallet+cluster
+        // updates use the correct network even if the cluster subscription
+        // hasn't fired yet.
+        var chainId = this.resolveCurrentChainId();
+        this.lastAddress = address;
+        this.lastChainId = chainId;
+        logger.info("SolanaStoreHandler: Wallet connected", {
+            address: address,
+            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;
+            this.formo.connect({ chainId: chainId, address: address }, {
+                providerName: connectorName,
+                rdns: "sol.wallet.".concat(connectorName.toLowerCase().replace(/\s+/g, "")),
+            }).catch(function (error) {
+                logger.error("SolanaStoreHandler: Error emitting connect", error);
+            });
+        }
+    };
+    SolanaStoreHandler.prototype.handleDisconnect = function () {
+        if (!this.lastAddress) {
+            return;
+        }
+        logger.info("SolanaStoreHandler: Wallet disconnected", {
+            address: this.lastAddress,
+            chainId: this.lastChainId,
+        });
+        if (this.formo.isAutocaptureEnabled("disconnect")) {
+            this.formo.disconnect({
+                chainId: this.lastChainId,
+                address: this.lastAddress,
+            }).catch(function (error) {
+                logger.error("SolanaStoreHandler: Error emitting disconnect", error);
+            });
+        }
+        this.lastAddress = undefined;
+        this.lastChainId = undefined;
+    };
+    // ============================================================
+    // Cluster Subscription
+    // ============================================================
+    SolanaStoreHandler.prototype.setupClusterSubscription = function () {
+        var _this = this;
+        var prevEndpoint = this.store.getState().cluster.endpoint;
+        var unsubscribe = this.store.subscribe(function (state) {
+            var endpoint = state.cluster.endpoint;
+            if (endpoint !== prevEndpoint) {
+                prevEndpoint = endpoint;
+                _this.handleClusterChange(endpoint);
+            }
+        });
+        this.unsubscribers.push(unsubscribe);
+        logger.info("SolanaStoreHandler: Cluster subscription set up");
+    };
+    SolanaStoreHandler.prototype.handleClusterChange = function (endpoint) {
+        // Don't auto-detect if the cluster was explicitly set
+        if (this.explicitCluster) {
+            return;
+        }
+        var detected = this.detectClusterFromEndpoint(endpoint);
+        if (!detected) {
+            return;
+        }
+        var previousCluster = this.cluster;
+        if (detected === previousCluster) {
+            return;
+        }
+        this.cluster = detected;
+        this.chainId = SOLANA_CHAIN_IDS[detected];
+        logger.info("SolanaStoreHandler: Cluster changed", {
+            from: previousCluster,
+            to: detected,
+            chainId: this.chainId,
+        });
+        if (this.lastAddress) {
+            this.lastChainId = this.chainId;
+            if (this.formo.isAutocaptureEnabled("chain")) {
+                this.formo.chain({
+                    chainId: this.chainId,
+                    address: this.lastAddress,
+                }).catch(function (error) {
+                    logger.error("SolanaStoreHandler: Error emitting chain event", error);
+                });
+            }
+        }
+    };
+    // ============================================================
+    // Transaction Subscription
+    // ============================================================
+    SolanaStoreHandler.prototype.setupTransactionSubscription = function () {
+        var _this = this;
+        var prevTransactions = this.store.getState().transactions;
+        var unsubscribe = this.store.subscribe(function (state) {
+            var transactions = state.transactions;
+            if (transactions !== prevTransactions) {
+                var prev = prevTransactions;
+                prevTransactions = transactions;
+                _this.handleTransactionChanges(transactions, prev);
+            }
+        });
+        this.unsubscribers.push(unsubscribe);
+        logger.info("SolanaStoreHandler: Transaction subscription set up");
+    };
+    SolanaStoreHandler.prototype.handleTransactionChanges = function (transactions, prevTransactions) {
+        var _a;
+        // Check each transaction for status changes
+        for (var _i = 0, _b = Object.entries(transactions); _i < _b.length; _i++) {
+            var _c = _b[_i], key = _c[0], tx = _c[1];
+            var prevTx = prevTransactions[key];
+            // Skip if status hasn't changed
+            if (prevTx && prevTx.status === tx.status) {
+                continue;
+            }
+            // For new transactions (sending), use current address.
+            // For terminal states, fall back to the address captured at STARTED time.
+            var address = this.lastAddress || ((_a = this.transactionSenders.get(key)) === null || _a === void 0 ? void 0 : _a.address);
+            if (!address) {
+                continue;
+            }
+            this.handleTransactionStatusChange(key, tx, prevTx, address);
+        }
+    };
+    SolanaStoreHandler.prototype.handleTransactionStatusChange = function (key, tx, prevTx, address) {
+        var chainId = this.chainId;
+        var dedupeKey = "".concat(key, ":").concat(tx.status);
+        // Deduplicate
+        if (this.processedTransactions.has(dedupeKey)) {
+            return;
+        }
+        this.processedTransactions.add(dedupeKey);
+        cleanupOldEntries(this.processedTransactions);
+        if (!this.formo.isAutocaptureEnabled("transaction")) {
+            return;
+        }
+        switch (tx.status) {
+            case "sending": {
+                // Emit STARTED when transaction enters "sending" state
+                if (!this.startedTransactions.has(key)) {
+                    this.startedTransactions.add(key);
+                    cleanupOldEntries(this.startedTransactions);
+                    // Capture sender for this transaction so terminal events are attributed
+                    // correctly even if the wallet disconnects before the tx settles.
+                    this.transactionSenders.set(key, { address: address, chainId: chainId });
+                    this.formo.transaction({
+                        status: TransactionStatus.STARTED,
+                        chainId: chainId,
+                        address: address,
+                    }).catch(function (error) {
+                        logger.error("SolanaStoreHandler: Error emitting transaction STARTED", error);
+                    });
+                }
+                break;
+            }
+            case "waiting": {
+                // "waiting" means the tx was sent and we have a signature — emit BROADCASTED
+                var signature = tx.signature;
+                if (signature) {
+                    // Ensure sender is captured (in case we missed "sending")
+                    if (!this.transactionSenders.has(key)) {
+                        this.transactionSenders.set(key, { address: address, chainId: chainId });
+                    }
+                    var sender = this.transactionSenders.get(key);
+                    this.formo.transaction({
+                        status: TransactionStatus.BROADCASTED,
+                        chainId: sender.chainId,
+                        address: sender.address,
+                        transactionHash: signature,
+                    }).catch(function (error) {
+                        logger.error("SolanaStoreHandler: Error emitting transaction BROADCASTED", error);
+                    });
+                }
+                break;
+            }
+            case "confirmed": {
+                var sender = this.transactionSenders.get(key);
+                var txAddress = (sender === null || sender === void 0 ? void 0 : sender.address) || address;
+                var txChainId = (sender === null || sender === void 0 ? void 0 : sender.chainId) || chainId;
+                var signature = tx.signature;
+                logger.info("SolanaStoreHandler: Transaction confirmed", {
+                    key: key,
+                    signature: signature,
+                });
+                this.formo.transaction(__assign({ status: TransactionStatus.CONFIRMED, chainId: txChainId, address: txAddress }, (signature && { transactionHash: signature }))).catch(function (error) {
+                    logger.error("SolanaStoreHandler: Error emitting transaction CONFIRMED", error);
+                });
+                this.transactionSenders.delete(key);
+                break;
+            }
+            case "failed": {
+                var sender = this.transactionSenders.get(key);
+                var txAddress = (sender === null || sender === void 0 ? void 0 : sender.address) || address;
+                var txChainId = (sender === null || sender === void 0 ? void 0 : sender.chainId) || chainId;
+                var signature = tx.signature;
+                var prevStatus = prevTx === null || prevTx === void 0 ? void 0 : prevTx.status;
+                // If it failed after being sent and confirmed as failed on-chain, emit REVERTED.
+                // Otherwise (rejected by user, build error, RPC rejection), emit REJECTED.
+                var status_1 = prevStatus === "waiting"
+                    ? TransactionStatus.REVERTED
+                    : TransactionStatus.REJECTED;
+                logger.info("SolanaStoreHandler: Transaction failed", {
+                    key: key,
+                    signature: signature,
+                    status: status_1,
+                    prevStatus: prevStatus,
+                });
+                this.formo.transaction(__assign({ status: status_1, chainId: txChainId, address: txAddress }, (signature && { transactionHash: signature }))).catch(function (error) {
+                    logger.error("SolanaStoreHandler: Error emitting transaction event", error);
+                });
+                this.transactionSenders.delete(key);
+                break;
+            }
+            // "idle" — no event needed
+        }
+    };
+    // ============================================================
+    // Cluster Detection
+    // ============================================================
+    /**
+     * Attempt to detect the Solana cluster from the store's endpoint URL.
+     */
+    SolanaStoreHandler.prototype.detectClusterFromStore = function (store) {
+        try {
+            var endpoint = store.getState().cluster.endpoint;
+            return this.detectClusterFromEndpoint(endpoint);
+        }
+        catch (_a) {
+            return null;
+        }
+    };
+    /**
+     * Detect cluster from an RPC endpoint URL.
+     */
+    SolanaStoreHandler.prototype.detectClusterFromEndpoint = function (endpoint) {
+        if (!endpoint)
+            return null;
+        var lower = endpoint.toLowerCase();
+        if (lower.includes("devnet"))
+            return "devnet";
+        if (lower.includes("testnet"))
+            return "testnet";
+        if (lower.includes("localhost") || lower.includes("127.0.0.1"))
+            return "localnet";
+        if (lower.includes("mainnet"))
+            return "mainnet-beta";
+        return null;
+    };
+    // ============================================================
+    // Cleanup
+    // ============================================================
+    SolanaStoreHandler.prototype.cleanup = function () {
+        logger.debug("SolanaStoreHandler: Cleaning up");
+        for (var _i = 0, _a = this.unsubscribers; _i < _a.length; _i++) {
+            var unsubscribe = _a[_i];
+            try {
+                unsubscribe();
+            }
+            catch (error) {
+                logger.error("SolanaStoreHandler: Error during cleanup", error);
+            }
+        }
+        this.unsubscribers = [];
+        this.processedTransactions.clear();
+        this.startedTransactions.clear();
+        this.transactionSenders.clear();
+        this.lastAddress = undefined;
+        this.lastChainId = undefined;
+        logger.debug("SolanaStoreHandler: Cleanup complete");
+    };
+    return SolanaStoreHandler;
+}());
+export { SolanaStoreHandler };
+//# sourceMappingURL=SolanaStoreHandler.js.map

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

@@ -1,13 +1,17 @@
 /**
  * Solana integration module
  *
- * Provides integration with Solana Wallet Adapter for wallet event tracking.
- * This module exports the SolanaAdapter and related types.
+ * Provides automatic event capture for Solana wallets via framework-kit's
+ * zustand store. Connect/disconnect and transaction events are tracked
+ * automatically. Signature events (signMessage/signTransaction) require
+ * explicit tracking via formo.signature() since framework-kit
+ * doesn't track these in store state.
  *
- * @see https://github.com/anza-xyz/wallet-adapter
+ * @see https://github.com/solana-foundation/framework-kit
  */
-export { SolanaAdapter } from "./SolanaAdapter";
+export { SolanaStoreHandler } from "./SolanaStoreHandler";
 export { SolanaManager } from "./SolanaManager";
 export * from "./types";
+export * from "./storeTypes";
 export * from "./address";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,13 +1,17 @@
 /**
  * Solana integration module
  *
- * Provides integration with Solana Wallet Adapter for wallet event tracking.
- * This module exports the SolanaAdapter and related types.
+ * Provides automatic event capture for Solana wallets via framework-kit's
+ * zustand store. Connect/disconnect and transaction events are tracked
+ * automatically. Signature events (signMessage/signTransaction) require
+ * explicit tracking via formo.signature() since framework-kit
+ * doesn't track these in store state.
  *
- * @see https://github.com/anza-xyz/wallet-adapter
+ * @see https://github.com/solana-foundation/framework-kit
  */
-export { SolanaAdapter } from "./SolanaAdapter";
+export { SolanaStoreHandler } from "./SolanaStoreHandler";
 export { SolanaManager } from "./SolanaManager";
 export * from "./types";
+export * from "./storeTypes";
 export * from "./address";
 //# sourceMappingURL=index.js.map