@formo/analytics 1.26.0 → 1.28.0

package/README.md

@@ -17,12 +17,14 @@
 
 ## Installation
 
-The Formo Web SDK is a Javascript library that allows you to track user event data from your website and app. 
+The Formo Web SDK is a Javascript library that allows you to track user event data from your website and app.
 
 You can install Formo on:
-- [Websites](https://docs.formo.so/install#website)
-- [React apps](https://docs.formo.so/install#react)
-- [Next.js apps](https://docs.formo.so/install#next-js-app-router)
+- [Wagmi](https://docs.formo.so/install#wagmi) (recommended)
+- [HTML Snippet](https://docs.formo.so/install#html-snippet)
+- [React](https://docs.formo.so/install#react)
+- [Next.js app router](https://docs.formo.so/install#next-js-app-router)
+- [Next.js pages router](https://docs.formo.so/install#next-js-pages-router)
 
 ## Configuration
 

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

@@ -1,9 +1,15 @@
 import { EIP6963ProviderDetail } from "mipd";
 import { Address, ChainID, Config, EIP1193Provider, IFormoAnalytics, IFormoEventContext, IFormoEventProperties, Options, SignatureStatus, TransactionStatus } from "./types";
+import { SolanaManager } from "./solana/SolanaManager";
 export declare class FormoAnalytics implements IFormoAnalytics {
     readonly writeKey: string;
     options: Options;
-    private _provider?;
+    private _chainState;
+    private _activeNamespace?;
+    private get _provider();
+    private set _provider(value);
+    private get _evmAddress();
+    private get _evmChainId();
     private _providerListenersMap;
     private session;
     private eventManager;
@@ -29,6 +35,11 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * Only initialized when options.wagmi is provided
      */
     private wagmiHandler?;
+    /**
+     * Solana integration manager for tracking Solana wallet events.
+     * Only initialized when options.solana is provided or via formo.solana.
+     */
+    private solanaManager?;
     /**
      * Flag indicating if Wagmi mode is enabled
      * When true, EIP-1193 provider wrapping is skipped
@@ -139,7 +150,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @param {(...args: unknown[]) => void} callback
      * @returns {Promise<void>}
      */
-    transaction({ status, chainId, address, data, to, value, transactionHash, }: {
+    transaction({ status, chainId, address, data, to, value, transactionHash, function_name, function_args, builder_codes, }: {
         status: TransactionStatus;
         chainId: ChainID;
         address: Address;
@@ -147,20 +158,40 @@ export declare class FormoAnalytics implements IFormoAnalytics {
         to?: string;
         value?: string;
         transactionHash?: string;
+        function_name?: string;
+        function_args?: Record<string, unknown>;
+        builder_codes?: string;
     }, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
     /**
      * Emits an identify event with current wallet address and provider info.
-     * @param {string} params.address
-     * @param {string} params.userId
-     * @param {string} params.rdns
-     * @param {string} params.providerName
-     * @param {IFormoEventProperties} properties
+     *
+     * @param {string} params.address - Wallet address
+     * @param {string} params.userId - External user ID
+     * @param {string} params.rdns - Provider reverse domain name
+     * @param {string} params.providerName - Provider display name
+     * @param {IFormoEventProperties} properties - Additional properties to include with the identify event
      * @param {IFormoEventContext} context
      * @param {(...args: unknown[]) => void} callback
      * @returns {Promise<void>}
+     *
+     * @example
+     * ```ts
+     * // Basic identify
+     * formo.identify({ address: '0x...', userId: 'user123' });
+     *
+     * // With Privy user
+     * import { parsePrivyProperties } from '@formo/analytics';
+     * const { user } = usePrivy();
+     * if (user) {
+     *   const { properties, wallets } = parsePrivyProperties(user);
+     *   for (const wallet of wallets) {
+     *     formo.identify({ address: wallet.address, userId: user.id }, properties);
+     *   }
+     * }
+     * ```
      */
     identify(params?: {
-        address?: Address;
+        address: Address;
         providerName?: string;
         userId?: string;
         rdns?: string;
@@ -256,6 +287,19 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     get providers(): readonly EIP6963ProviderDetail[];
     private detectWallets;
     get provider(): EIP1193Provider | undefined;
+    /**
+     * Access the Solana integration manager.
+     * Lazily creates one if not already initialized.
+     *
+     * @example
+     * ```tsx
+     * formo.solana.setWallet(wallet);
+     * formo.solana.setConnection(connection);
+     * formo.solana.setCluster("devnet");
+     * formo.solana.syncWalletState();
+     * ```
+     */
+    get solana(): SolanaManager;
     private getAddress;
     private getAccounts;
     private getCurrentChainId;
@@ -296,11 +340,26 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      */
     private handleProviderMismatch;
     /**
-     * Helper method to validate and checksum an address
-     * @param address The address to validate and checksum
-     * @returns The checksummed address or undefined if invalid
+     * Determine which namespace a chainId belongs to.
+     */
+    private getNamespace;
+    /**
+     * Update per-chain state and sync the derived currentAddress/currentChainId.
+     * Accepts either a namespace string ('evm'/'solana') or a chainId number
+     * to resolve the namespace automatically. When a chainId number is passed,
+     * it is also stored as the namespace's chainId (unless explicitly overridden
+     * in the update object).
+     */
+    private setChainState;
+    /**
+     * Clear per-chain state for a given namespace (or chainId) and sync derived state.
+     */
+    private clearChainState;
+    /**
+     * Synchronize currentAddress/currentChainId from the active namespace.
+     * Last-connected-chain-wins: _activeNamespace takes precedence.
      */
-    private validateAndChecksumAddress;
+    private syncDerivedState;
     /**
      * Helper method to clear the active provider state
      * Centralizes provider clearing logic for consistency