@formo/analytics 1.38.1 → 1.39.0

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

@@ -1,17 +1,22 @@
 /**
  * Solana integration module
  *
- * 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.
+ * Wallets are discovered through the Wallet Standard and their connect /
+ * disconnect events captured automatically for wallets registered with the
+ * page through Wallet Standard.
+ * Framework-kit apps can additionally pass their zustand store for
+ * transaction lifecycle events. Signature events (signMessage /
+ * signTransaction) require explicit tracking via formo.signature(), since
+ * neither source reports them.
  *
+ * @see https://github.com/wallet-standard/wallet-standard
  * @see https://github.com/solana-foundation/framework-kit
  */
 export { SolanaStoreHandler } from "./SolanaStoreHandler";
+export { SolanaWalletStandardRegistry } from "./SolanaWalletStandardRegistry";
 export { SolanaManager } from "./SolanaManager";
 export * from "./types";
 export * from "./storeTypes";
+export * from "./walletStandardTypes";
 export * from "./address";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,17 +1,22 @@
 /**
  * Solana integration module
  *
- * 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.
+ * Wallets are discovered through the Wallet Standard and their connect /
+ * disconnect events captured automatically for wallets registered with the
+ * page through Wallet Standard.
+ * Framework-kit apps can additionally pass their zustand store for
+ * transaction lifecycle events. Signature events (signMessage /
+ * signTransaction) require explicit tracking via formo.signature(), since
+ * neither source reports them.
  *
+ * @see https://github.com/wallet-standard/wallet-standard
  * @see https://github.com/solana-foundation/framework-kit
  */
 export { SolanaStoreHandler } from "./SolanaStoreHandler";
+export { SolanaWalletStandardRegistry } from "./SolanaWalletStandardRegistry";
 export { SolanaManager } from "./SolanaManager";
 export * from "./types";
 export * from "./storeTypes";
+export * from "./walletStandardTypes";
 export * from "./address";
 //# sourceMappingURL=index.js.map

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

@@ -72,13 +72,32 @@ export interface SolanaWalletConnectorMetadata {
     readonly name: string;
     readonly icon?: string;
 }
+/** Cluster health as exposed by framework-kit. */
+export type SolanaClusterStatus = Readonly<{
+    status: "idle";
+}> | Readonly<{
+    status: "connecting";
+}> | Readonly<{
+    status: "ready";
+    latencyMs?: number;
+}> | Readonly<{
+    status: "error";
+    error: unknown;
+}>;
+/** @deprecated framework-kit emits {@link SolanaClusterStatus} objects. */
+export type LegacySolanaClusterStatus = SolanaClusterStatus["status"];
 /**
  * Cluster state from the store.
  */
 export interface SolanaClusterState {
     readonly endpoint: string;
     readonly commitment?: string;
-    readonly status: "idle" | "connecting" | "ready" | "error";
+    /**
+     * framework-kit's `ClusterStatus` is a discriminated union such as
+     * `{ status: 'ready', latencyMs?: number }`. The pre-1.39 string form is
+     * retained so custom stores and test doubles remain source-compatible.
+     */
+    readonly status: SolanaClusterStatus | LegacySolanaClusterStatus;
 }
 /**
  * The zustand vanilla store API that framework-kit exposes via `client.store`.

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

@@ -46,15 +46,32 @@ export interface SolanaPublicKey {
  */
 export type UnsubscribeFn = () => void;
 /**
- * Solana options for FormoAnalytics
+ * The rdns reported for a Solana wallet.
+ *
+ * The Wallet Standard has no reverse-domain identifier, so one is derived
+ * from the wallet's normalized name. Lowercasing and removing whitespace
+ * preserves the values historically reported by the framework-kit store;
+ * encoding keeps delimiters and other special characters safe for storage.
+ * Both Solana paths (Wallet Standard discovery and the framework-kit store)
+ * derive it the same way, so a wallet's `detect` and its `connect` share one
+ * rdns whichever path reported each.
+ */
+export declare function solanaWalletRdns(walletName: string): string;
+/**
+ * Solana options for FormoAnalytics.
+ *
+ * Wallet discovery through the Wallet Standard is on by default and needs
+ * none of these. They add framework-kit's store, or name the cluster.
  */
 export interface SolanaOptions {
     /**
-     * The framework-kit client store (client.store) for automatic event tracking.
-     * When provided, wallet connect/disconnect and transaction events are tracked
-     * automatically by subscribing to zustand store state changes.
+     * The framework-kit client store (client.store).
+     * When provided, transaction lifecycle events and cluster switches are
+     * tracked from the store, and connect/disconnect come from the store
+     * rather than from Wallet Standard discovery.
      *
-     * This is the recommended approach for apps using framework-kit.
+     * Only for apps using framework-kit (`@solana/client`). Other integrations
+     * do not need a store when their wallets register through Wallet Standard.
      *
      * @example
      * ```tsx
@@ -65,10 +82,16 @@ export interface SolanaOptions {
      */
     store?: import("./storeTypes").SolanaClientStore;
     /**
-     * The Solana cluster/network.
-     * Usually auto-detected from the store's endpoint URL.
-     * Only needed for custom RPC URLs that don't contain a recognizable cluster name.
-     * @default auto-detected, or "mainnet-beta" if detection fails
+     * The Solana cluster/network the app is on.
+     *
+     * With a store, usually auto-detected from its endpoint URL; only needed
+     * for custom RPC URLs that don't contain a recognizable cluster name.
+     * Without a store, the Wallet Standard cannot say which cluster the app
+     * uses, so a devnet or testnet app should set this (or call
+     * `formo.solana.setCluster()`); otherwise connections are reported on
+     * mainnet-beta.
+     * @default auto-detected from the store; otherwise mainnet-beta when the
+     * wallet supports it, or its first supported Solana cluster
      */
     cluster?: SolanaCluster;
 }

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

@@ -40,4 +40,18 @@ export function isSolanaChainId(chainId) {
         return false;
     return Object.values(SOLANA_CHAIN_IDS).includes(chainId);
 }
+/**
+ * The rdns reported for a Solana wallet.
+ *
+ * The Wallet Standard has no reverse-domain identifier, so one is derived
+ * from the wallet's normalized name. Lowercasing and removing whitespace
+ * preserves the values historically reported by the framework-kit store;
+ * encoding keeps delimiters and other special characters safe for storage.
+ * Both Solana paths (Wallet Standard discovery and the framework-kit store)
+ * derive it the same way, so a wallet's `detect` and its `connect` share one
+ * rdns whichever path reported each.
+ */
+export function solanaWalletRdns(walletName) {
+    return "sol.wallet.".concat(encodeURIComponent(walletName.toLowerCase().replace(/\s+/g, "")));
+}
 //# sourceMappingURL=types.js.map

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

@@ -0,0 +1,54 @@
+/**
+ * The subset of the Wallet Standard this SDK reads.
+ *
+ * Duck-typed on purpose: the SDK must not depend on `@wallet-standard/*`
+ * packages (see the dependency policy), and a wallet is discovered through
+ * window events, so nothing here is ever imported from a wallet library.
+ * Every field is what a conforming wallet exposes; the shapes are looser
+ * than the reference types so a slightly off wallet is skipped, not thrown
+ * on.
+ *
+ * @see https://github.com/wallet-standard/wallet-standard
+ */
+/** `namespace:reference`, e.g. `solana:mainnet` or `solana:devnet`. */
+export type WalletStandardChain = string;
+export interface WalletStandardAccount {
+    readonly address: string;
+    readonly publicKey?: unknown;
+    /** Chains this account can sign for. Absent on a non-conforming wallet. */
+    readonly chains?: readonly WalletStandardChain[];
+    readonly features?: readonly string[];
+    readonly label?: string;
+    readonly icon?: string;
+}
+export interface WalletStandardWallet {
+    readonly version?: string;
+    readonly name: string;
+    readonly icon?: string;
+    /** Every chain the wallet supports, NOT the one currently selected. */
+    readonly chains: readonly WalletStandardChain[];
+    readonly features: Readonly<Record<string, unknown>>;
+    /** Accounts the app is currently authorized for; empty until connected. */
+    readonly accounts: readonly WalletStandardAccount[];
+}
+/** What a `standard:events` `change` event carries: only what changed. */
+export interface WalletStandardChangeProperties {
+    readonly chains?: readonly WalletStandardChain[];
+    readonly features?: Readonly<Record<string, unknown>>;
+    readonly accounts?: readonly WalletStandardAccount[];
+}
+/** The `standard:events` feature. */
+export interface WalletStandardEventsFeature {
+    readonly version?: string;
+    on(event: "change", listener: (properties: WalletStandardChangeProperties) => void): () => void;
+}
+/** The API an app hands to wallets so they can announce themselves. */
+export interface WalletStandardRegisterApi {
+    register(...wallets: WalletStandardWallet[]): () => void;
+}
+/** Dispatched by the app on `window`; `detail` is the register API. */
+export declare const WALLET_STANDARD_APP_READY_EVENT = "wallet-standard:app-ready";
+/** Dispatched by a wallet on `window`; `detail` is a callback taking the API. */
+export declare const WALLET_STANDARD_REGISTER_WALLET_EVENT = "wallet-standard:register-wallet";
+export declare const WALLET_STANDARD_EVENTS_FEATURE = "standard:events";
+//# sourceMappingURL=walletStandardTypes.d.ts.map

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

@@ -0,0 +1,18 @@
+/**
+ * The subset of the Wallet Standard this SDK reads.
+ *
+ * Duck-typed on purpose: the SDK must not depend on `@wallet-standard/*`
+ * packages (see the dependency policy), and a wallet is discovered through
+ * window events, so nothing here is ever imported from a wallet library.
+ * Every field is what a conforming wallet exposes; the shapes are looser
+ * than the reference types so a slightly off wallet is skipped, not thrown
+ * on.
+ *
+ * @see https://github.com/wallet-standard/wallet-standard
+ */
+/** Dispatched by the app on `window`; `detail` is the register API. */
+export var WALLET_STANDARD_APP_READY_EVENT = "wallet-standard:app-ready";
+/** Dispatched by a wallet on `window`; `detail` is a callback taking the API. */
+export var WALLET_STANDARD_REGISTER_WALLET_EVENT = "wallet-standard:register-wallet";
+export var WALLET_STANDARD_EVENTS_FEATURE = "standard:events";
+//# sourceMappingURL=walletStandardTypes.js.map

package/dist/esm/src/types/base.d.ts

@@ -246,16 +246,26 @@ export interface Options {
      */
     wagmi?: WagmiOptions;
     /**
-     * Solana integration configuration.
-     * Pass `store: client.store` from framework-kit for automatic tracking of
-     * wallet connect/disconnect and transaction events.
+     * Solana wallet tracking.
+     *
+     * On by default: wallets are discovered through the Wallet Standard, the
+     * Solana analogue of EIP-6963, so connect and disconnect are autocaptured
+     * for compatible wallets registered with the page, including wallets used
+     * through Solana Kit, wallet-adapter, and framework-kit.
+     *
+     * - `false`: disable Solana wallet discovery and tracking entirely.
+     * - `SolanaOptions`: additionally pass `store: client.store` from
+     *   framework-kit for transaction lifecycle events and cluster switches,
+     *   or `cluster` to name the network a non-mainnet app is on.
      *
      * For signMessage/signTransaction, use formo.signature() directly
-     * (framework-kit doesn't track these in the store).
+     * (neither the Wallet Standard nor framework-kit's store reports these).
      *
+     * @see https://github.com/wallet-standard/wallet-standard
      * @see https://github.com/solana-foundation/framework-kit
+     * @default true
      */
-    solana?: SolanaOptions;
+    solana?: boolean | SolanaOptions;
     /**
      * Custom API host for sending events through your own domain to bypass ad blockers
      * - If not provided, events are sent directly to events.formo.so

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

@@ -1,2 +1,2 @@
-export declare const version = "1.38.1";
+export declare const version = "1.39.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/esm/src/version.js

@@ -1,4 +1,4 @@
 // This file is auto-generated by scripts/update-version.js during npm version
 // Do not edit manually - it will be overwritten
-export var version = '1.38.1';
+export var version = '1.39.0';
 //# sourceMappingURL=version.js.map

package/dist/esm/src/wagmi/WagmiEventHandler.d.ts

@@ -6,7 +6,7 @@
  * wrapping approach when Wagmi mode is enabled.
  */
 import { FormoAnalytics } from "../FormoAnalytics";
-import { WagmiConfig, QueryClient } from "./types";
+import { QueryClient, WagmiConfig } from "./types";
 /**
  * How long the markers stay trustworthy after the last handler goes away.
  *
@@ -337,6 +337,35 @@ export declare class WagmiEventHandler {
      * (still connected through its own connector).
      */
     private isAddressConnected;
+    /**
+     * A specific connector's name and rdns, for the fallback-wrapped
+     * provider's request-derived events.
+     *
+     * The NAME is exactly what the hook path emits for that connector
+     * (`getConnectorName`: the live WalletConnect peer for a WalletConnect
+     * connector, the connector's own name otherwise), so a branded connector
+     * keeps its name on both paths and a session that changes wallets
+     * renames on both. The rdns is the connector's when wagmi knows it as
+     * ONE value (EIP-6963 discovered connectors carry theirs, some as a
+     * one-element list); a connector that matches several rdns values does
+     * not say which one this provider is, so nothing is passed and the
+     * registry keeps the sniffed one.
+     */
+    private attributionForConnector;
+    /**
+     * Resolver handed to the registry at wrap time, read at each request
+     * start. BOUND to the connector whose `getProvider` resolved to the
+     * wrapped provider, not to whichever connector is current: an app can
+     * keep a wallet client over a previous connector's provider and issue a
+     * request through it after switching, and that request belongs to the
+     * wallet that handles it. The peer name is still read live. A provider
+     * SHARED by two connectors is re-bound when the new connector's
+     * resolution lands (one microtask for an injected connector); a request
+     * issued inside that gap keeps the previous label.
+     */
+    private boundConnectorAttribution;
+    /** `getConnectorName` for a SPECIFIC connector, current or not. */
+    private nameForConnector;
     /**
      * Get the connector name from Wagmi state
      */

package/dist/esm/src/wagmi/WagmiEventHandler.js

@@ -71,6 +71,16 @@ var RESERVED_FIELDS = new Set([
     "transactionHash",
     "function_name",
     "function_args",
+    // Wallet attribution. Function args are spread AFTER the attribution
+    // properties, so an ABI input named `providerName` would silently
+    // relabel the wallet on every broadcast and receipt event. `rdns` is
+    // reserved with it even though THIS path (wagmi mutation attribution)
+    // emits only the name: elsewhere in the SDK - the EIP-1193 request path
+    // and connect events - `rdns` is the wallet-identity key, so an ABI
+    // input by that name would land in the same warehouse column as real
+    // wallet identities.
+    "providerName",
+    "rdns",
 ]);
 /**
  * Connections already announced to a destination during this page load.
@@ -2333,6 +2343,75 @@ var WagmiEventHandler = /** @class */ (function () {
         });
         return found;
     };
+    /**
+     * A specific connector's name and rdns, for the fallback-wrapped
+     * provider's request-derived events.
+     *
+     * The NAME is exactly what the hook path emits for that connector
+     * (`getConnectorName`: the live WalletConnect peer for a WalletConnect
+     * connector, the connector's own name otherwise), so a branded connector
+     * keeps its name on both paths and a session that changes wallets
+     * renames on both. The rdns is the connector's when wagmi knows it as
+     * ONE value (EIP-6963 discovered connectors carry theirs, some as a
+     * one-element list); a connector that matches several rdns values does
+     * not say which one this provider is, so nothing is passed and the
+     * registry keeps the sniffed one.
+     */
+    WagmiEventHandler.prototype.attributionForConnector = function (connector, state) {
+        var name = this.nameForConnector(connector, state);
+        if (!name) {
+            return undefined;
+        }
+        var raw = connector.rdns;
+        var rdns = typeof raw === "string" && raw.length > 0
+            ? raw
+            : Array.isArray(raw) && raw.length === 1 && typeof raw[0] === "string" && raw[0].length > 0
+                ? raw[0]
+                : undefined;
+        return __assign({ name: name }, (rdns && { rdns: rdns }));
+    };
+    /**
+     * Resolver handed to the registry at wrap time, read at each request
+     * start. BOUND to the connector whose `getProvider` resolved to the
+     * wrapped provider, not to whichever connector is current: an app can
+     * keep a wallet client over a previous connector's provider and issue a
+     * request through it after switching, and that request belongs to the
+     * wallet that handles it. The peer name is still read live. A provider
+     * SHARED by two connectors is re-bound when the new connector's
+     * resolution lands (one microtask for an injected connector); a request
+     * issued inside that gap keeps the previous label.
+     */
+    WagmiEventHandler.prototype.boundConnectorAttribution = function (connector) {
+        var _this = this;
+        return function () {
+            if (_this.disposed)
+                return undefined;
+            try {
+                return _this.attributionForConnector(connector, _this.getState());
+            }
+            catch (_a) {
+                return undefined;
+            }
+        };
+    };
+    /** `getConnectorName` for a SPECIFIC connector, current or not. */
+    WagmiEventHandler.prototype.nameForConnector = function (connector, state) {
+        var _a;
+        var cached = walletConnectPeerNames.get(connector);
+        if (cached) {
+            return cached;
+        }
+        var current = state.current
+            ? (_a = state.connections.get(state.current)) === null || _a === void 0 ? void 0 : _a.connector
+            : undefined;
+        if (current === connector) {
+            // Backstop kick, as in getConnectorName; only the current connection
+            // has a session to look up.
+            this.kickWalletConnectPeerLookup(state);
+        }
+        var name = connector.name;
+        return typeof name === "string" && name.length > 0 ? name : undefined;
+    };
     /**
      * Get the connector name from Wagmi state
      */
@@ -2470,7 +2549,7 @@ var WagmiEventHandler = /** @class */ (function () {
                 return;
             }
             var chainId = (_b = _this.getActiveConnectionChainId(live)) !== null && _b !== void 0 ? _b : live.chainId;
-            var wrapped = (_d = (_c = _this.formo)._wrapWagmiProvider) === null || _d === void 0 ? void 0 : _d.call(_c, provider, typeof chainId === "number" ? chainId : undefined);
+            var wrapped = (_d = (_c = _this.formo)._wrapWagmiProvider) === null || _d === void 0 ? void 0 : _d.call(_c, provider, typeof chainId === "number" ? chainId : undefined, _this.boundConnectorAttribution(connector));
             if (wrapped !== true) {
                 // The provider was refused (invalid shape, frozen provider,
                 // torn-down SDK).

package/dist/esm/src/wagmi/types.d.ts

@@ -31,6 +31,12 @@ export interface WagmiConnector {
     name: string;
     type: string;
     uid: string;
+    /**
+     * Any connector implementation may expose an rdns; EIP-6963 discovered
+     * connectors are one source. A connector matching several rdns values
+     * lists them all.
+     */
+    rdns?: string | readonly string[];
 }
 /**
  * Wagmi config interface

package/dist/esm/src/wagmi/utils.js

@@ -185,7 +185,15 @@ export function buildSafeFunctionArgs(functionArgs, reservedFields) {
     var result = {};
     for (var _i = 0, _a = Object.entries(functionArgs); _i < _a.length; _i++) {
         var _b = _a[_i], key = _b[0], val = _b[1];
-        var safeKey = reservedFields.has(key) ? "arg_".concat(key) : key;
+        // A prefixed key must not land on another argument's own name: an ABI
+        // with both `to` and `arg_to` would otherwise keep only one of them,
+        // whichever came later. Keep prefixing until the name is free.
+        var safeKey = key;
+        if (reservedFields.has(key)) {
+            do {
+                safeKey = "arg_".concat(safeKey);
+            } while (safeKey in functionArgs);
+        }
         result[safeKey] = val;
         // If the value is a nested object (struct), flatten it
         // Skip flattened keys that would overwrite existing top-level args