@formo/analytics 1.13.0-alpha.1 → 1.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formo/analytics",
-  "version": "1.13.0-alpha.1",
+  "version": "1.13.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/getformo/sdk.git"

package/src/FormoAnalytics.ts

@@ -1,45 +1,66 @@
 import axios from "axios";
 import {
   COUNTRY_LIST,
+  CURRENT_URL_KEY,
   EVENTS_API_URL,
   Event,
 } from "./constants";
 import { H } from "highlight.run";
-import { ChainID, Address, EIP1193Provider, Options, Config } from "./types";
+import {
+  ChainID,
+  Address,
+  EIP1193Provider,
+  Options,
+  Config,
+  RequestArguments,
+  RPCError,
+  SignatureStatus,
+  TransactionStatus,
+} from "./types";
 
 interface IFormoAnalytics {
-  /**
-   * Tracks page visit events.
-   */
   page(): void;
-
-  /**
-   * Connects to a wallet with the specified chain ID and address.
-   */
-  connect(params: { chainId: ChainID; address: string }): Promise<void>;
-
-  /**
-   * Disconnects the current wallet.
-   */
-  disconnect(params?: { chainId?: ChainID; address?: string }): Promise<void>;
-
-  /**
-   * Switches the blockchain chain context and optionally logs additional params.
-   */
-  chain(params: { chainId: ChainID; address?: string }): Promise<void>;
-
-  /**
-   * Tracks a specific event with a name and associated data.
-   */
-  track(eventName: string, eventData: Record<string, any>): Promise<void>;
+  // trackPagesChange(): void;
+  connect(params: { chainId: ChainID; address: Address }): Promise<void>;
+  disconnect(params?: { chainId?: ChainID; address?: Address }): Promise<void>;
+  chain(params: { chainId: ChainID; address?: Address }): Promise<void>;
+  signature({
+    status,
+    chainId,
+    address,
+    message,
+    signatureHash,
+  }: {
+    status: SignatureStatus;
+    chainId?: ChainID;
+    address: Address;
+    message: string;
+    signatureHash?: string;
+  }): Promise<void>;
+  transaction({
+    status,
+    chainId,
+    address,
+    data,
+    to,
+    value,
+    transactionHash,
+  }: {
+    status: TransactionStatus;
+    chainId: ChainID;
+    address: Address;
+    data?: string;
+    to?: string;
+    value?: string;
+    transactionHash?: string;
+  }): Promise<void>;
+  identify(params: { address: Address }): Promise<void>;
+  track(action: string, payload: Record<string, any>): Promise<void>;
 }
 
 export class FormoAnalytics implements IFormoAnalytics {
   private _provider?: EIP1193Provider;
-  private _providerListeners: Record<
-    string,
-    (...args: unknown[]) => void
-  > = {};
+  private _providerListeners: Record<string, (...args: unknown[]) => void> = {};
 
   config: Config;
   currentChainId?: ChainID;
@@ -53,11 +74,15 @@ export class FormoAnalytics implements IFormoAnalytics {
       apiKey: apiKey,
     };
 
+    // TODO: replace with eip6963
     const provider =
       window?.ethereum || window.web3?.currentProvider || options?.provider;
     if (provider) {
       this.trackProvider(provider);
     }
+
+    this.trackFirstPageVisit();
+    this.trackPagesChange();
   }
 
   static async init(
@@ -66,14 +91,40 @@ export class FormoAnalytics implements IFormoAnalytics {
   ): Promise<FormoAnalytics> {
     // May be needed for delayed loading
     // https://github.com/segmentio/analytics-next/tree/master/packages/browser#lazy--delayed-loading
-    return new FormoAnalytics(apiKey, options);
+    const analytics = new FormoAnalytics(apiKey, options);
+
+    // Identify current user on init (TODO: make this toggleable)
+    analytics.identify();
+
+    return analytics;
   }
 
   /*
     Public SDK functions
   */
 
-  async connect({ chainId, address }: { chainId: ChainID; address: Address }): Promise<void> {
+  /**
+   * Emits a page visit event with the current URL information, fire on page change.
+   * @returns {Promise<void>}
+   */
+  async page(): Promise<void> {
+    await this.trackPageHit();
+  }
+
+  /**
+   * Emits a wallet connect event.
+   * @param {ChainID} params.chainId
+   * @param {Address} params.address
+   * @throws {Error} If chainId or address is empty
+   * @returns {Promise<void>}
+   */
+  async connect({
+    chainId,
+    address,
+  }: {
+    chainId: ChainID;
+    address: Address;
+  }): Promise<void> {
     if (!chainId) {
       throw new Error("FormoAnalytics::connect: chain ID cannot be empty");
     }
@@ -90,24 +141,48 @@ export class FormoAnalytics implements IFormoAnalytics {
     });
   }
 
-  async disconnect(params?: { chainId?: ChainID; address?: Address }): Promise<void> {
+  /**
+   * Emits a wallet disconnect event.
+   * @param {ChainID} params.chainId
+   * @param {Address} params.address
+   * @returns {Promise<void>}
+   */
+  async disconnect(params?: {
+    chainId?: ChainID;
+    address?: Address;
+  }): Promise<void> {
     const address = params?.address || this.currentConnectedAddress;
     const chainId = params?.chainId || this.currentChainId;
+
     await this.handleDisconnect(chainId, address);
   }
 
-  async chain({ chainId, address }: { chainId: ChainID; address?: Address }): Promise<void> {
+  /**
+   * Emits a chain network change event.
+   * @param {ChainID} params.chainId
+   * @param {Address} params.address
+   * @throws {Error} If chainId is empty, zero, or not a valid number
+   * @throws {Error} If no address is provided and no previous address is recorded
+   * @returns {Promise<void>}
+   */
+  async chain({
+    chainId,
+    address,
+  }: {
+    chainId: ChainID;
+    address?: Address;
+  }): Promise<void> {
     if (!chainId || Number(chainId) === 0) {
       throw new Error("FormoAnalytics::chain: chainId cannot be empty or 0");
     }
-    if (!address && !this.currentConnectedAddress) {
+    if (isNaN(Number(chainId))) {
       throw new Error(
-        "FormoAnalytics::chain: address was empty and no previous address has been recorded. You can either pass an address or call connect() first"
+        "FormoAnalytics::chain: chainId must be a valid decimal number"
       );
     }
-    if (isNaN(Number(chainId))) {
+    if (!address && !this.currentConnectedAddress) {
       throw new Error(
-        "FormoAnalytics::chain: chainId must be a valid decimal number"
+        "FormoAnalytics::chain: address was empty and no previous address has been recorded"
       );
     }
 
@@ -119,13 +194,77 @@ export class FormoAnalytics implements IFormoAnalytics {
     });
   }
 
-  // TODO: allow custom url as input
-  async page(): Promise<void> {
-    await this.trackPageHit();
+  async signature({
+    status,
+    chainId,
+    address,
+    message,
+    signatureHash,
+  }: {
+    status: SignatureStatus;
+    chainId?: ChainID;
+    address: Address;
+    message: string;
+    signatureHash?: string;
+  }): Promise<void> {
+    await this.trackEvent(Event.SIGNATURE, {
+      status,
+      chainId,
+      address,
+      message,
+      ...(signatureHash && { signatureHash }),
+    });
   }
 
-  async track(eventName: string, eventData: Record<string, any>): Promise<void> {
-    await this.trackEvent(eventName, eventData);
+  async transaction({
+    status,
+    chainId,
+    address,
+    data,
+    to,
+    value,
+    transactionHash,
+  }: {
+    status: TransactionStatus;
+    chainId: ChainID;
+    address: Address;
+    data?: string;
+    to?: string;
+    value?: string;
+    transactionHash?: string;
+  }): Promise<void> {
+    await this.trackEvent(Event.TRANSACTION, {
+      status,
+      chainId,
+      address,
+      data,
+      to,
+      value,
+      ...(transactionHash && { transactionHash }),
+    });
+  }
+
+  /**
+   * Emits a identify event with current wallet address.
+   * @param {Address} params.address
+   * @returns {Promise<void>}
+   */
+  public async identify(params?: { address: Address }): Promise<void> {
+    const address = params?.address || (await this.getAddress());
+    await this.trackEvent(Event.IDENTIFY, {
+      address,
+      // TODO: detect wallet type https://linear.app/getformo/issue/P-837/sdk-detect-user-wallet-type-in-identify-call
+    });
+  }
+
+  /**
+   * Emits a custom event with custom data.
+   * @param {string} action
+   * @param {Record<string, any>} payload
+   * @returns {Promise<void>}
+   */
+  async track(action: string, payload: Record<string, any>): Promise<void> {
+    await this.trackEvent(action, payload);
   }
 
   /*
@@ -142,24 +281,20 @@ export class FormoAnalytics implements IFormoAnalytics {
     this.currentConnectedAddress = undefined;
 
     if (this._provider) {
-      const eventNames = Object.keys(this._providerListeners);
-      for (const eventName of eventNames) {
-        this._provider.removeListener(
-          eventName,
-          this._providerListeners[eventName]
-        );
-        delete this._providerListeners[eventName];
+      const actions = Object.keys(this._providerListeners);
+      for (const action of actions) {
+        this._provider.removeListener(action, this._providerListeners[action]);
+        delete this._providerListeners[action];
       }
     }
 
-    console.log("Tracking new provider:", provider);
     this._provider = provider;
 
-    this.getAddress();
+    // Register listeners for web3 provider events
     this.registerAddressChangedListener();
     this.registerChainChangedListener();
-    // TODO: track signing and transactions
-    // https://linear.app/getformo/issue/P-607/sdk-support-signature-and-transaction-events
+    this.registerSignatureListener();
+    this.registerTransactionListener();
   }
 
   private registerAddressChangedListener(): void {
@@ -181,6 +316,120 @@ export class FormoAnalytics implements IFormoAnalytics {
     this._providerListeners["chainChanged"] = listener;
   }
 
+  private registerSignatureListener(): void {
+    if (!this.provider) {
+      console.error("_trackSigning: provider not found");
+      return;
+    }
+    if (
+      Object.getOwnPropertyDescriptor(this.provider, "request")?.writable ===
+      false
+    ) {
+      console.warn("_trackSigning: provider.request is not writable");
+      return;
+    }
+
+    const request = this.provider.request.bind(this.provider);
+    this.provider.request = async <T>({
+      method,
+      params,
+    }: RequestArguments): Promise<T | null | undefined> => {
+      if (
+        Array.isArray(params) &&
+        ["eth_signTypedData_v4", "personal_sign"].includes(method)
+      ) {
+        // Emit signature request event
+        this.signature({
+          status: SignatureStatus.REQUESTED,
+          ...this.buildSignatureEventPayload(method, params),
+        });
+
+        try {
+          const response = (await request({ method, params })) as T;
+          if (response) {
+            // Emit signature confirmed event
+            this.signature({
+              status: SignatureStatus.CONFIRMED,
+              ...this.buildSignatureEventPayload(method, params, response),
+            });
+          }
+          return response;
+        } catch (error) {
+          const rpcError = error as RPCError;
+          if (rpcError && rpcError?.code === 4001) {
+            // Emit signature rejected event
+            this.signature({
+              status: SignatureStatus.REJECTED,
+              ...this.buildSignatureEventPayload(method, params),
+            });
+          }
+          throw error;
+        }
+      }
+      return request({ method, params });
+    };
+    return;
+  }
+
+  private registerTransactionListener(): void {
+    if (!this.provider) {
+      console.error("_trackTransactions: provider not found");
+      return;
+    }
+    if (
+      Object.getOwnPropertyDescriptor(this.provider, "request")?.writable ===
+      false
+    ) {
+      console.warn("_trackTransactions: provider.request is not writable");
+      return;
+    }
+    const request = this.provider.request.bind(this.provider);
+    this.provider.request = async <T>({
+      method,
+      params,
+    }: RequestArguments): Promise<T | null | undefined> => {
+      if (
+        Array.isArray(params) &&
+        method === "eth_sendTransaction" &&
+        params[0]
+      ) {
+        // Track transaction start
+        const payload = await this.buildTransactionEventPayload(params);
+        this.transaction({ status: TransactionStatus.STARTED, ...payload });
+
+        try {
+          // Wait for the transaction hash
+          const transactionHash = (await request({ method, params })) as string;
+
+          // Track transaction broadcast
+          this.transaction({
+            status: TransactionStatus.BROADCASTED,
+            ...payload,
+            transactionHash,
+          });
+
+          return;
+        } catch (error) {
+          console.log("transaction listener catch");
+          console.log(error);
+          const rpcError = error as RPCError;
+          if (rpcError && rpcError?.code === 4001) {
+            // Emit transaction rejected event
+            this.transaction({
+              status: TransactionStatus.REJECTED,
+              ...payload,
+            });
+          }
+          throw error;
+        }
+      }
+
+      return request({ method, params });
+    };
+
+    return;
+  }
+
   private async onAddressChanged(addresses: Address[]): Promise<void> {
     if (addresses.length > 0) {
       this.onAddressConnected(addresses[0]);
@@ -201,18 +450,25 @@ export class FormoAnalytics implements IFormoAnalytics {
     this.connect({ chainId: this.currentChainId, address });
   }
 
-  private async handleDisconnect(chainId?: ChainID, address?: Address): Promise<void> {
+  private async handleDisconnect(
+    chainId?: ChainID,
+    address?: Address
+  ): Promise<void> {
     const payload = {
       chain_id: chainId || this.currentChainId,
       address: address || this.currentConnectedAddress,
     };
     this.currentChainId = undefined;
     this.currentConnectedAddress = undefined;
+
     await this.trackEvent(Event.DISCONNECT, payload);
   }
 
   private async onAddressDisconnected(): Promise<void> {
-    await this.handleDisconnect(this.currentChainId, this.currentConnectedAddress);
+    await this.handleDisconnect(
+      this.currentChainId,
+      this.currentConnectedAddress
+    );
   }
 
   private async onChainChanged(chainIdHex: string): Promise<void> {
@@ -225,7 +481,6 @@ export class FormoAnalytics implements IFormoAnalytics {
         return Promise.resolve();
       }
 
-      // Attempt to fetch and store the connected address
       const address = await this.getAddress();
       if (!address) {
         console.log(
@@ -234,7 +489,7 @@ export class FormoAnalytics implements IFormoAnalytics {
         return Promise.resolve();
       }
 
-      this.currentConnectedAddress = address[0];
+      this.currentConnectedAddress = address;
     }
 
     // Proceed only if the address exists
@@ -250,22 +505,60 @@ export class FormoAnalytics implements IFormoAnalytics {
     }
   }
 
-  // TOFIX: support multiple page hit events
+  private async trackFirstPageVisit(): Promise<void> {
+    if (sessionStorage.getItem(CURRENT_URL_KEY) === null) {
+      sessionStorage.setItem(CURRENT_URL_KEY, window.location.href);
+    }
+
+    return this.trackPageHit();
+  }
+
+  private async trackPagesChange(): Promise<void> {
+    const oldPushState = history.pushState;
+    history.pushState = function pushState(...args) {
+      const ret = oldPushState.apply(this, args);
+      window.dispatchEvent(new window.Event("locationchange"));
+      return ret;
+    };
+
+    const oldReplaceState = history.replaceState;
+    history.replaceState = function replaceState(...args) {
+      const ret = oldReplaceState.apply(this, args);
+      window.dispatchEvent(new window.Event("locationchange"));
+      return ret;
+    };
+
+    window.addEventListener("popstate", () => this.onLocationChange());
+
+    window.addEventListener("locationchange", () => this.onLocationChange());
+  }
+
+  private async onLocationChange(): Promise<void> {
+    const currentUrl = sessionStorage.getItem(CURRENT_URL_KEY);
+
+    if (currentUrl !== window.location.href) {
+      sessionStorage.setItem(CURRENT_URL_KEY, window.location.href);
+      this.trackPageHit();
+    }
+  }
+
   // TODO: Add event listener and support for SPA and hash-based navigation
   // https://linear.app/getformo/issue/P-800/sdk-support-spa-and-hash-based-routing
   private trackPageHit(): void {
     const pathname = window.location.pathname;
     const href = window.location.href;
+    const hash = window.location.hash;
 
     setTimeout(async () => {
       this.trackEvent(Event.PAGE, {
         pathname,
         href,
+        hash,
       });
     }, 300);
   }
 
-  // TODO: refactor this with event queue and flushing 
+  // TODO: refactor this with event queue and flushing
   // https://linear.app/getformo/issue/P-835/sdk-refactor-retries-with-event-queue-and-batching
   private async trackEvent(action: string, payload: any): Promise<void> {
     const address = await this.getAddress();
@@ -291,7 +584,12 @@ export class FormoAnalytics implements IFormoAnalytics {
       );
 
       if (response.status >= 200 && response.status < 300) {
-        console.log("Event sent successfully:", action);
+        console.log(
+          `Event sent successfully: ${this.getActionDescriptor(
+            action,
+            payload
+          )}`
+        );
       } else {
         throw new Error(`Failed with status: ${response.status}`);
       }
@@ -310,9 +608,10 @@ export class FormoAnalytics implements IFormoAnalytics {
 
   get provider(): EIP1193Provider | undefined {
     return this._provider;
-  }    
+  }
 
   private async getAddress(): Promise<Address | null> {
+    if (this.currentConnectedAddress) return this.currentConnectedAddress;
     if (!this.provider) {
       console.log("FormoAnalytics::getAddress: the provider is not set");
       return null;
@@ -321,11 +620,9 @@ export class FormoAnalytics implements IFormoAnalytics {
     try {
       const accounts = await this.getAccounts();
       if (accounts && accounts.length > 0) {
-        const address = accounts[0];
+        return accounts[0];
         // TODO: how to handle multiple addresses? Should we emit a connect event here? Since the user has not manually connected
         // https://linear.app/getformo/issue/P-691/sdk-detect-multiple-wallets-using-eip6963
-        this.onAddressConnected(address); 
-        return address;
       }
     } catch (err) {
       console.log("Failed to fetch accounts from provider:", err);
@@ -368,9 +665,7 @@ export class FormoAnalytics implements IFormoAnalytics {
         method: "eth_chainId",
       });
       if (!chainIdHex) {
-        console.log(
-          "FormoAnalytics::fetchChainId: chain id not found"
-        );
+        console.log("FormoAnalytics::fetchChainId: chain id not found");
         return 0;
       }
       return parseInt(chainIdHex as string, 16);
@@ -386,10 +681,12 @@ export class FormoAnalytics implements IFormoAnalytics {
   private getLocation(): string | undefined {
     try {
       const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
-      return COUNTRY_LIST[timezone as keyof typeof COUNTRY_LIST];
+      if (timezone in COUNTRY_LIST)
+        return COUNTRY_LIST[timezone as keyof typeof COUNTRY_LIST];
+      return timezone;
     } catch (error) {
       console.error("Error resolving timezone:", error);
-      return undefined;
+      return "";
     }
   }
 
@@ -430,5 +727,57 @@ export class FormoAnalytics implements IFormoAnalytics {
       ref: params.get("ref"),
       ...eventSpecificPayload,
     };
-  }  
+  }
+
+  private buildSignatureEventPayload(
+    method: string,
+    params: unknown[],
+    response?: unknown
+  ) {
+    const basePayload = {
+      chainId: this.currentChainId,
+      address:
+        method === "personal_sign"
+          ? (params[1] as Address)
+          : (params[0] as Address),
+    };
+
+    if (method === "personal_sign") {
+      const message = Buffer.from(
+        (params[0] as string).slice(2),
+        "hex"
+      ).toString("utf8");
+      return {
+        ...basePayload,
+        message,
+        ...(response ? { signatureHash: response as string } : {}),
+      };
+    }
+
+    return {
+      ...basePayload,
+      message: params[1] as string,
+      ...(response ? { signatureHash: response as string } : {}),
+    };
+  }
+
+  private async buildTransactionEventPayload(params: unknown[]) {
+    const { data, from, to, value } = params[0] as {
+      data: string;
+      from: string;
+      to: string;
+      value: string;
+    };
+    return {
+      chainId: this.currentChainId || (await this.getCurrentChainId()),
+      data,
+      address: from,
+      to,
+      value,
+    };
+  }
+
+  private getActionDescriptor(action: string, payload: any): string {
+    return `${action}${payload.status ? ` ${payload.status}` : ""}`;
+  }
 }