@formo/analytics 1.28.5 → 1.29.0

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

@@ -45,8 +45,15 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * When true, EIP-1193 provider wrapping is skipped
      */
     private isWagmiMode;
+    /**
+     * Flag indicating if EVM provider tracking is disabled.
+     * When true, all EIP-1193/EIP-6963 detection and wrapping is skipped.
+     */
+    private isEvmDisabled;
     /** Instance-level flag so multiple SDK instances don't interfere. */
     private crossSubdomainCookies;
+    /** In-memory URL used to deduplicate SPA pageview events. */
+    private _currentUrl;
     config: Config;
     currentChainId?: ChainID;
     currentAddress?: Address;
@@ -294,10 +301,9 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      *
      * @example
      * ```tsx
-     * formo.solana.setWallet(wallet);
-     * formo.solana.setConnection(connection);
+     * formo.solana.setStore(client.store);
      * formo.solana.setCluster("devnet");
-     * formo.solana.syncWalletState();
+     * // For signatures, use formo.signature() directly
      * ```
      */
     get solana(): SolanaManager;

package/dist/cjs/src/FormoAnalytics.js

@@ -117,6 +117,13 @@ var FormoAnalytics = /** @class */ (function () {
          * When true, EIP-1193 provider wrapping is skipped
          */
         this.isWagmiMode = false;
+        /**
+         * Flag indicating if EVM provider tracking is disabled.
+         * When true, all EIP-1193/EIP-6963 detection and wrapping is skipped.
+         */
+        this.isEvmDisabled = false;
+        /** In-memory URL used to deduplicate SPA pageview events. */
+        this._currentUrl = "";
         this.currentUserId = "";
         this.config = {
             writeKey: writeKey,
@@ -124,6 +131,7 @@ var FormoAnalytics = /** @class */ (function () {
         this.options = options;
         // Check if Wagmi mode is enabled
         this.isWagmiMode = !!options.wagmi;
+        this.isEvmDisabled = options.evm === false;
         this.crossSubdomainCookies = (_a = options.crossSubdomainCookies) !== null && _a !== void 0 ? _a : true;
         // Normalize so downstream consumers (EventFactory) read the resolved value.
         options.crossSubdomainCookies = this.crossSubdomainCookies;
@@ -156,8 +164,11 @@ var FormoAnalytics = /** @class */ (function () {
         if (this.hasOptedOutTracking()) {
             logger_1.logger.info("User has previously opted out of tracking");
         }
-        // Initialize Wagmi handler if Wagmi mode is enabled
-        if (this.isWagmiMode && options.wagmi) {
+        // Initialize EVM provider tracking (unless explicitly disabled)
+        if (this.isEvmDisabled) {
+            logger_1.logger.info("FormoAnalytics: EVM provider tracking disabled");
+        }
+        else if (this.isWagmiMode && options.wagmi) {
             logger_1.logger.info("FormoAnalytics: Initializing in Wagmi mode");
             this.wagmiHandler = new wagmi_1.WagmiEventHandler(this, options.wagmi.config, options.wagmi.queryClient);
         }
@@ -179,6 +190,7 @@ var FormoAnalytics = /** @class */ (function () {
         if (options.solana) {
             this.solanaManager = new SolanaManager_1.SolanaManager(this, options.solana);
         }
+        this._currentUrl = window.location.href;
         this.trackPageHit();
         this.trackPageHits();
     }
@@ -226,22 +238,26 @@ var FormoAnalytics = /** @class */ (function () {
                     case 0:
                         (0, storage_1.initStorageManager)(writeKey);
                         analytics = new FormoAnalytics(writeKey, options);
-                        if (!!analytics.isWagmiMode) return [3 /*break*/, 3];
+                        if (!analytics.isEvmDisabled) return [3 /*break*/, 1];
+                        logger_1.logger.info("FormoAnalytics: Skipping provider detection (EVM disabled)");
+                        return [3 /*break*/, 5];
+                    case 1:
+                        if (!!analytics.isWagmiMode) return [3 /*break*/, 4];
                         // Auto-detect wallet provider
                         _a = analytics;
                         return [4 /*yield*/, analytics.getProviders()];
-                    case 1:
+                    case 2:
                         // Auto-detect wallet provider
                         _a._providers = _b.sent();
                         return [4 /*yield*/, analytics.detectWallets(analytics._providers)];
-                    case 2:
+                    case 3:
                         _b.sent();
                         analytics.trackProviders(analytics._providers);
-                        return [3 /*break*/, 4];
-                    case 3:
+                        return [3 /*break*/, 5];
+                    case 4:
                         logger_1.logger.info("FormoAnalytics: Skipping provider detection (Wagmi mode)");
-                        _b.label = 4;
-                    case 4: return [2 /*return*/, analytics];
+                        _b.label = 5;
+                    case 5: return [2 /*return*/, analytics];
                 }
             });
         });
@@ -1427,11 +1443,9 @@ var FormoAnalytics = /** @class */ (function () {
     };
     FormoAnalytics.prototype.onLocationChange = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var currentUrl;
             return __generator(this, function (_a) {
-                currentUrl = (0, storage_1.cookie)().get(constants_1.SESSION_CURRENT_URL_KEY);
-                if (currentUrl !== window.location.href) {
-                    (0, storage_1.cookie)().set(constants_1.SESSION_CURRENT_URL_KEY, window.location.href);
+                if (this._currentUrl !== window.location.href) {
+                    this._currentUrl = window.location.href;
                     this.trackPageHit();
                 }
                 return [2 /*return*/];
@@ -1770,10 +1784,9 @@ var FormoAnalytics = /** @class */ (function () {
          *
          * @example
          * ```tsx
-         * formo.solana.setWallet(wallet);
-         * formo.solana.setConnection(connection);
+         * formo.solana.setStore(client.store);
          * formo.solana.setCluster("devnet");
-         * formo.solana.syncWalletState();
+         * // For signatures, use formo.signature() directly
          * ```
          */
         get: function () {

package/dist/cjs/src/constants/base.d.ts

@@ -1,5 +1,4 @@
 export declare const SESSION_TRAFFIC_SOURCE_KEY = "traffic-source";
-export declare const SESSION_CURRENT_URL_KEY = "analytics-current-url";
 export declare const SESSION_USER_ID_KEY = "user-id";
 export declare const LOCAL_ANONYMOUS_ID_KEY = "anonymous-id";
 export declare const CONSENT_OPT_OUT_KEY = "opt-out-tracking";

package/dist/cjs/src/constants/base.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BLOCKED_ADDRESSES = exports.DEAD_ADDRESS = exports.ZERO_ADDRESS = exports.DEFAULT_PROVIDER_ICON = exports.CONSENT_OPT_OUT_KEY = exports.LOCAL_ANONYMOUS_ID_KEY = exports.SESSION_USER_ID_KEY = exports.SESSION_CURRENT_URL_KEY = exports.SESSION_TRAFFIC_SOURCE_KEY = void 0;
+exports.BLOCKED_ADDRESSES = exports.DEAD_ADDRESS = exports.ZERO_ADDRESS = exports.DEFAULT_PROVIDER_ICON = exports.CONSENT_OPT_OUT_KEY = exports.LOCAL_ANONYMOUS_ID_KEY = exports.SESSION_USER_ID_KEY = exports.SESSION_TRAFFIC_SOURCE_KEY = void 0;
 exports.SESSION_TRAFFIC_SOURCE_KEY = "traffic-source";
 // SESSION_WALLET_DETECTED_KEY and SESSION_WALLET_IDENTIFIED_KEY
 // are now defined in src/session/index.ts
-exports.SESSION_CURRENT_URL_KEY = "analytics-current-url";
 exports.SESSION_USER_ID_KEY = "user-id";
 exports.LOCAL_ANONYMOUS_ID_KEY = "anonymous-id";
 // Consent management keys

package/dist/cjs/src/event/EventFactory.d.ts

@@ -17,6 +17,7 @@ declare class EventFactory implements IEventFactory {
     private getLanguage;
     private getLibraryVersion;
     private extractUTMParameters;
+    private extractClickIdParameters;
     private extractReferralParameter;
     private getTrafficSources;
     private getScreen;

package/dist/cjs/src/event/EventFactory.js

@@ -87,6 +87,15 @@ var EventFactory = /** @class */ (function () {
             catch (_a) { }
             return result;
         };
+        this.extractClickIdParameters = function (urlObj) {
+            var result = {};
+            for (var _i = 0, CLICK_ID_PARAMS_1 = constants_2.CLICK_ID_PARAMS; _i < CLICK_ID_PARAMS_1.length; _i++) {
+                var param = CLICK_ID_PARAMS_1[_i];
+                var value = urlObj.searchParams.get(param);
+                result[param] = value ? value.trim() : "";
+            }
+            return result;
+        };
         this.extractReferralParameter = function (urlObj) {
             var _a, _b, _c;
             // Strategy: Check query params first, then check path pattern if configured
@@ -119,25 +128,23 @@ var EventFactory = /** @class */ (function () {
         };
         this.getTrafficSources = function (url) {
             var urlObj = new URL(url);
-            var contextTrafficSources = __assign(__assign({}, _this.extractUTMParameters(url)), { ref: _this.extractReferralParameter(urlObj), referrer: document.referrer });
+            var contextTrafficSources = __assign(__assign(__assign({}, _this.extractUTMParameters(url)), _this.extractClickIdParameters(urlObj)), { ref: _this.extractReferralParameter(urlObj), referrer: document.referrer });
             var storedTrafficSources = (0, storage_1.session)().get(constants_1.SESSION_TRAFFIC_SOURCE_KEY) || {};
-            var finalTrafficSources = {
-                ref: contextTrafficSources.ref || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.ref) || "",
-                referrer: contextTrafficSources.referrer || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.referrer) || "",
-                utm_campaign: contextTrafficSources.utm_campaign ||
+            var mergedClickIds = {};
+            for (var _i = 0, CLICK_ID_PARAMS_2 = constants_2.CLICK_ID_PARAMS; _i < CLICK_ID_PARAMS_2.length; _i++) {
+                var p = CLICK_ID_PARAMS_2[_i];
+                mergedClickIds[p] =
+                    contextTrafficSources[p] || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources[p]) || "";
+            }
+            var finalTrafficSources = __assign({ ref: contextTrafficSources.ref || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.ref) || "", referrer: contextTrafficSources.referrer || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.referrer) || "", utm_campaign: contextTrafficSources.utm_campaign ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_campaign) ||
-                    "",
-                utm_content: contextTrafficSources.utm_content ||
+                    "", utm_content: contextTrafficSources.utm_content ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_content) ||
-                    "",
-                utm_medium: contextTrafficSources.utm_medium ||
+                    "", utm_medium: contextTrafficSources.utm_medium ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_medium) ||
-                    "",
-                utm_source: contextTrafficSources.utm_source ||
+                    "", utm_source: contextTrafficSources.utm_source ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_source) ||
-                    "",
-                utm_term: contextTrafficSources.utm_term || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_term) || "",
-            };
+                    "", utm_term: contextTrafficSources.utm_term || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_term) || "" }, mergedClickIds);
             // Store to session
             var sessionStoredTrafficSources = Object.keys(finalTrafficSources).reduce(function (res, key) {
                 var value = finalTrafficSources[key];

package/dist/cjs/src/event/constants.d.ts

@@ -1,11 +1,17 @@
 declare const CHANNEL = "web";
 declare const VERSION = "0";
+/**
+ * Paid-attribution click IDs captured from the landing-page URL and persisted
+ * across the session alongside UTM parameters. Keep the ClickIdParameters type
+ * in src/types/events.ts derived from this array.
+ */
+declare const CLICK_ID_PARAMS: readonly ["gclid", "gad_source", "fbclid", "msclkid", "twclid", "li_fat_id", "rdt_cid", "ttclid"];
 /**
  * Fields that should be excluded from page event properties parsing
  * These are either:
- * - Already captured in event context (UTM params, referral params)
+ * - Already captured in event context (UTM params, referral params, click IDs)
  * - Semantic event properties that should not be overridden by URL params
  */
 declare const PAGE_PROPERTIES_EXCLUDED_FIELDS: Set<string>;
-export { CHANNEL, VERSION, PAGE_PROPERTIES_EXCLUDED_FIELDS };
+export { CHANNEL, VERSION, CLICK_ID_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS };
 //# sourceMappingURL=constants.d.ts.map

package/dist/cjs/src/event/constants.js

@@ -1,17 +1,42 @@
 "use strict";
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PAGE_PROPERTIES_EXCLUDED_FIELDS = exports.VERSION = exports.CHANNEL = void 0;
+exports.PAGE_PROPERTIES_EXCLUDED_FIELDS = exports.CLICK_ID_PARAMS = exports.VERSION = exports.CHANNEL = void 0;
 var CHANNEL = "web";
 exports.CHANNEL = CHANNEL;
 var VERSION = "0";
 exports.VERSION = VERSION;
+/**
+ * Paid-attribution click IDs captured from the landing-page URL and persisted
+ * across the session alongside UTM parameters. Keep the ClickIdParameters type
+ * in src/types/events.ts derived from this array.
+ */
+var CLICK_ID_PARAMS = [
+    "gclid", // Google Ads
+    "gad_source", // Google Ads (newer)
+    "fbclid", // Meta (Facebook/Instagram)
+    "msclkid", // Microsoft Ads (Bing)
+    "twclid", // Twitter/X Ads
+    "li_fat_id", // LinkedIn Ads
+    "rdt_cid", // Reddit Ads
+    "ttclid", // TikTok Ads
+];
+exports.CLICK_ID_PARAMS = CLICK_ID_PARAMS;
 /**
  * Fields that should be excluded from page event properties parsing
  * These are either:
- * - Already captured in event context (UTM params, referral params)
+ * - Already captured in event context (UTM params, referral params, click IDs)
  * - Semantic event properties that should not be overridden by URL params
  */
-var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set([
+var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set(__spreadArray(__spreadArray([
     // Context fields (already captured in event context)
     'utm_source',
     'utm_medium',
@@ -21,7 +46,8 @@ var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set([
     'ref',
     'referral',
     'refcode',
-    'referrer',
+    'referrer'
+], CLICK_ID_PARAMS, true), [
     // Semantic event properties (should not be overridden by URL params)
     'category',
     'name',
@@ -29,6 +55,6 @@ var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set([
     'path',
     'hash',
     'query',
-]);
+], false));
 exports.PAGE_PROPERTIES_EXCLUDED_FIELDS = PAGE_PROPERTIES_EXCLUDED_FIELDS;
 //# sourceMappingURL=constants.js.map

package/dist/cjs/src/index.d.ts

@@ -4,5 +4,7 @@ export * from "./types";
 export { parsePrivyProperties } from "./privy";
 export type { PrivyUser, PrivyLinkedAccount, PrivyAccountType, PrivyProfileProperties, PrivyWalletInfo } from "./privy";
 export { SolanaManager } from "./solana";
-export type { SolanaOptions, SolanaCluster, ISolanaAdapter, SolanaWalletContext, SolanaPublicKey, SolanaConnection, } from "./solana";
+export { SOLANA_CHAIN_IDS, DEFAULT_SOLANA_CHAIN_ID, isSolanaChainId } from "./solana";
+export type { SolanaOptions, SolanaCluster, } from "./solana";
+export type { SolanaClientStore, SolanaClientState, } from "./solana";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/src/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SolanaManager = exports.parsePrivyProperties = void 0;
+exports.isSolanaChainId = exports.DEFAULT_SOLANA_CHAIN_ID = exports.SOLANA_CHAIN_IDS = exports.SolanaManager = exports.parsePrivyProperties = void 0;
 var initialization_1 = require("./initialization");
 __exportStar(require("./FormoAnalyticsProvider"), exports);
 __exportStar(require("./FormoAnalytics"), exports);
@@ -24,6 +24,10 @@ Object.defineProperty(exports, "parsePrivyProperties", { enumerable: true, get:
 // Solana integration exports
 var solana_1 = require("./solana");
 Object.defineProperty(exports, "SolanaManager", { enumerable: true, get: function () { return solana_1.SolanaManager; } });
+var solana_2 = require("./solana");
+Object.defineProperty(exports, "SOLANA_CHAIN_IDS", { enumerable: true, get: function () { return solana_2.SOLANA_CHAIN_IDS; } });
+Object.defineProperty(exports, "DEFAULT_SOLANA_CHAIN_ID", { enumerable: true, get: function () { return solana_2.DEFAULT_SOLANA_CHAIN_ID; } });
+Object.defineProperty(exports, "isSolanaChainId", { enumerable: true, get: function () { return solana_2.isSolanaChainId; } });
 if (typeof window !== "undefined")
     window.formofy = initialization_1.formofy;
 //# sourceMappingURL=index.js.map

package/dist/cjs/src/solana/SolanaManager.d.ts

@@ -1,24 +1,49 @@
 /**
  * SolanaManager
  *
- * Manages the lifecycle of the SolanaAdapter, handling lazy initialization
- * and pending configuration. This keeps Solana-specific lifecycle logic out of
- * the main FormoAnalytics class.
+ * 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.
+ *
+ * For signMessage/signTransaction tracking (not captured by the store),
+ * use formo.signature() directly with the address and chainId.
+ *
+ * For manual event tracking without the store, use the core API directly:
+ * formo.transaction(), formo.signature(), formo.connect(), formo.disconnect().
  */
 import { FormoAnalytics } from "../FormoAnalytics";
-import { SolanaAdapter } from "./SolanaAdapter";
-import { ISolanaAdapter, SolanaWalletContext, SolanaConnection, SolanaCluster, SolanaOptions } from "./types";
+import { SolanaCluster, SolanaOptions } from "./types";
+import { SolanaClientStore } from "./storeTypes";
 export declare class SolanaManager {
     private formo;
-    private handler?;
-    private pendingConnection?;
+    private storeHandler?;
     private pendingCluster?;
     constructor(formo: FormoAnalytics, options?: SolanaOptions);
-    get adapter(): SolanaAdapter | undefined;
-    setWallet(wallet: ISolanaAdapter | SolanaWalletContext | null): void;
-    setConnection(connection: SolanaConnection | null): void;
+    /**
+     * Set the framework-kit zustand store for automatic event tracking.
+     * This enables autocapture mode — connect/disconnect and transaction events
+     * are tracked automatically by subscribing to store state changes.
+     *
+     * @param store - The framework-kit client store (client.store)
+     * @param options - Optional configuration
+     *
+     * @example
+     * ```tsx
+     * import { createClient } from '@solana-foundation/framework-kit';
+     *
+     * const client = createClient({ endpoint: '...', walletConnectors: autoDiscover() });
+     * formo.solana.setStore(client.store);
+     * ```
+     */
+    setStore(store: SolanaClientStore, options?: {
+        cluster?: SolanaCluster;
+    }): void;
+    /**
+     * 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.
+     */
     setCluster(cluster: SolanaCluster): void;
-    syncWalletState(): void;
     cleanup(): void;
 }
 //# sourceMappingURL=SolanaManager.d.ts.map

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

@@ -2,77 +2,75 @@
 /**
  * SolanaManager
  *
- * Manages the lifecycle of the SolanaAdapter, handling lazy initialization
- * and pending configuration. This keeps Solana-specific lifecycle logic out of
- * the main FormoAnalytics class.
+ * 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.
+ *
+ * For signMessage/signTransaction tracking (not captured by the store),
+ * use formo.signature() directly with the address and chainId.
+ *
+ * For manual event tracking without the store, use the core API directly:
+ * formo.transaction(), formo.signature(), formo.connect(), formo.disconnect().
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SolanaManager = void 0;
 var logger_1 = require("../logger");
-var SolanaAdapter_1 = require("./SolanaAdapter");
+var SolanaStoreHandler_1 = require("./SolanaStoreHandler");
 var SolanaManager = /** @class */ (function () {
     function SolanaManager(formo, options) {
         this.formo = formo;
-        if (options === null || options === void 0 ? void 0 : options.wallet) {
-            logger_1.logger.info("SolanaManager: Initializing Solana wallet tracking");
-            this.handler = new SolanaAdapter_1.SolanaAdapter(formo, {
-                wallet: options.wallet,
-                connection: options.connection,
+        if (options === null || options === void 0 ? void 0 : options.store) {
+            logger_1.logger.info("SolanaManager: Initializing store-based Solana tracking");
+            this.storeHandler = new SolanaStoreHandler_1.SolanaStoreHandler(formo, options.store, {
                 cluster: options.cluster,
             });
         }
-        else if (options) {
-            // Store pending values for when wallet is set later
-            this.pendingConnection = options.connection;
+        else if (options === null || options === void 0 ? void 0 : options.cluster) {
+            // Store pending cluster for when setStore is called later
             this.pendingCluster = options.cluster;
         }
     }
-    Object.defineProperty(SolanaManager.prototype, "adapter", {
-        get: function () {
-            return this.handler;
-        },
-        enumerable: false,
-        configurable: true
-    });
-    SolanaManager.prototype.setWallet = function (wallet) {
-        if (this.handler) {
-            this.handler.setWallet(wallet);
-        }
-        else if (wallet) {
-            logger_1.logger.info("SolanaManager: Initializing Solana wallet tracking (lazy)");
-            this.handler = new SolanaAdapter_1.SolanaAdapter(this.formo, {
-                wallet: wallet,
-                connection: this.pendingConnection,
-                cluster: this.pendingCluster,
-            });
-            this.pendingConnection = undefined;
-            this.pendingCluster = undefined;
-        }
-    };
-    SolanaManager.prototype.setConnection = function (connection) {
-        if (this.handler) {
-            this.handler.setConnection(connection);
-        }
-        else {
-            this.pendingConnection = connection !== null && connection !== void 0 ? connection : undefined;
-        }
+    /**
+     * Set the framework-kit zustand store for automatic event tracking.
+     * This enables autocapture mode — connect/disconnect and transaction events
+     * are tracked automatically by subscribing to store state changes.
+     *
+     * @param store - The framework-kit client store (client.store)
+     * @param options - Optional configuration
+     *
+     * @example
+     * ```tsx
+     * import { createClient } from '@solana-foundation/framework-kit';
+     *
+     * const client = createClient({ endpoint: '...', walletConnectors: autoDiscover() });
+     * formo.solana.setStore(client.store);
+     * ```
+     */
+    SolanaManager.prototype.setStore = function (store, options) {
+        var _a;
+        (_a = this.storeHandler) === null || _a === void 0 ? void 0 : _a.cleanup();
+        this.storeHandler = new SolanaStoreHandler_1.SolanaStoreHandler(this.formo, store, {
+            cluster: (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.
+     */
     SolanaManager.prototype.setCluster = function (cluster) {
-        if (this.handler) {
-            this.handler.setCluster(cluster);
+        if (this.storeHandler) {
+            this.storeHandler.setCluster(cluster);
         }
         else {
             this.pendingCluster = cluster;
         }
     };
-    SolanaManager.prototype.syncWalletState = function () {
-        var _a;
-        (_a = this.handler) === null || _a === void 0 ? void 0 : _a.syncWalletState();
-    };
     SolanaManager.prototype.cleanup = function () {
         var _a;
-        (_a = this.handler) === null || _a === void 0 ? void 0 : _a.cleanup();
-        this.handler = undefined;
+        (_a = this.storeHandler) === null || _a === void 0 ? void 0 : _a.cleanup();
+        this.storeHandler = undefined;
     };
     return SolanaManager;
 }());

package/dist/cjs/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