@formo/analytics 1.14.2 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formo/analytics",
-  "version": "1.14.2",
+  "version": "1.15.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/getformo/sdk.git"
@@ -21,7 +21,6 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@fingerprintjs/fingerprintjs": "^4.6.0",
     "fetch-retry": "^6.0.0",
     "is-network-error": "^1.1.0",
     "mipd": "^0.0.7"

package/src/FormoAnalytics.ts

@@ -1,9 +1,13 @@
 import { createStore, EIP6963ProviderDetail } from "mipd";
 import {
+  LOCAL_ANONYMOUS_ID_KEY,
   COUNTRY_LIST,
-  CURRENT_URL_KEY,
+  SESSION_CURRENT_URL_KEY,
   EVENTS_API_URL,
   Event,
+  SESSION_USER_ID_KEY,
+  EVENTS_API_REQUEST_HEADER,
+  USER_API_URL,
 } from "./constants";
 import {
   ChainID,
@@ -17,12 +21,19 @@ import {
   TransactionStatus,
   RequestEvent,
 } from "./types";
-import { session, isLocalhost, toSnakeCase, isAddress } from "./lib";
+import { session, local, logger, EventQueue, fetch } from "./lib";
+import {
+  isLocalhost,
+  isAddress,
+  toSnakeCase,
+  generateNativeUUID,
+} from "./utils";
 import { SESSION_IDENTIFIED_KEY } from "./constants";
-import { EventQueue } from "./lib/queue";
+import { UUID } from "crypto";
 
 interface IFormoAnalytics {
   page(): void;
+  reset(): 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>;
@@ -65,6 +76,8 @@ export class FormoAnalytics implements IFormoAnalytics {
   private _providerListeners: Record<string, (...args: unknown[]) => void> = {};
   private session: FormoAnalyticsSession;
   private eventQueue: EventQueue;
+  private anonymousId: UUID | null = null;
+  private userId: UUID | null = null;
 
   config: Config;
   currentChainId?: ChainID;
@@ -81,6 +94,15 @@ export class FormoAnalytics implements IFormoAnalytics {
 
     this.session = new FormoAnalyticsSession();
 
+    // Initialize logger with configuration from options
+    const loggerConfig = options.logger || {
+      enabled: false,
+    };
+    logger.setEnabled(loggerConfig.enabled);
+    if (loggerConfig.levels) {
+      logger.setEnabledLevels(loggerConfig.levels);
+    }
+
     this.eventQueue = new EventQueue(this.config.writeKey, {
       url: EVENTS_API_URL,
       flushAt: options.flushAt,
@@ -89,6 +111,9 @@ export class FormoAnalytics implements IFormoAnalytics {
       flushInterval: options.flushInterval,
     });
 
+    this.anonymousId = this.getAnonymousId();
+    this.getUserId(null).then((userId) => (this.userId = userId));
+
     // TODO: replace with eip6963
     const provider = options.provider || window?.ethereum;
     if (provider) {
@@ -120,10 +145,21 @@ export class FormoAnalytics implements IFormoAnalytics {
    * Emits a page visit event with the current URL information, fire on page change.
    * @returns {Promise<void>}
    */
-  async page(): Promise<void> {
+  public async page(): Promise<void> {
     await this.trackPageHit();
   }
 
+  /**
+   * Reset the current user session.
+   * @returns {void}
+   */
+  public reset(): void {
+    this.anonymousId = this.getAnonymousId();
+    this.userId = null;
+    local.remove(LOCAL_ANONYMOUS_ID_KEY);
+    session.remove(SESSION_USER_ID_KEY);
+  }
+
   /**
    * Emits a wallet connect event.
    * @param {ChainID} params.chainId
@@ -139,10 +175,10 @@ export class FormoAnalytics implements IFormoAnalytics {
     address: Address;
   }): Promise<void> {
     if (!chainId) {
-      throw new Error("FormoAnalytics::connect: chain ID cannot be empty");
+      logger.warn("Connect: Chain ID cannot be empty");
     }
     if (!address) {
-      throw new Error("FormoAnalytics::connect: address cannot be empty");
+      logger.warn("Connect: Address cannot be empty");
     }
 
     this.currentChainId = chainId;
@@ -292,9 +328,7 @@ export class FormoAnalytics implements IFormoAnalytics {
     rdns?: string;
   }): Promise<void> {
     if (this.session.isIdentified())
-      return console.warn(
-        "FormoAnalytics::identify: Wallet already identified in this session"
-      );
+      return logger.warn("Identify: Wallet already identified in this session");
 
     this.session.identify();
     await this.trackEvent(Event.IDENTIFY, {
@@ -319,29 +353,36 @@ export class FormoAnalytics implements IFormoAnalytics {
   */
 
   private trackProvider(provider: EIP1193Provider): void {
-    if (provider === this._provider) {
-      console.warn("FormoAnalytics::trackProvider: Provider already tracked.");
-      return;
-    }
-
-    this.currentChainId = undefined;
-    this.currentConnectedAddress = undefined;
+    try {
+      if (provider === this._provider) {
+        logger.warn("TrackProvider: Provider already tracked.");
+        return;
+      }
 
-    if (this._provider) {
-      const actions = Object.keys(this._providerListeners);
-      for (const action of actions) {
-        this._provider.removeListener(action, this._providerListeners[action]);
-        delete this._providerListeners[action];
+      this.currentChainId = undefined;
+      this.currentConnectedAddress = undefined;
+
+      if (this._provider) {
+        const actions = Object.keys(this._providerListeners);
+        for (const action of actions) {
+          this._provider.removeListener(
+            action,
+            this._providerListeners[action]
+          );
+          delete this._providerListeners[action];
+        }
       }
-    }
 
-    this._provider = provider;
+      this._provider = provider;
 
-    // Register listeners for web3 provider events
-    this.registerAddressChangedListener();
-    this.registerChainChangedListener();
-    this.registerSignatureListener();
-    this.registerTransactionListener();
+      // Register listeners for web3 provider events
+      this.registerAddressChangedListener();
+      this.registerChainChangedListener();
+      this.registerSignatureListener();
+      this.registerTransactionListener();
+    } catch (error) {
+      logger.error("Error tracking provider:", error);
+    }
   }
 
   private registerAddressChangedListener(): void {
@@ -365,14 +406,14 @@ export class FormoAnalytics implements IFormoAnalytics {
 
   private registerSignatureListener(): void {
     if (!this.provider) {
-      console.error("_trackSigning: provider not found");
+      logger.error("Provider not found for signature tracking");
       return;
     }
     if (
       Object.getOwnPropertyDescriptor(this.provider, "request")?.writable ===
       false
     ) {
-      console.warn("_trackSigning: provider.request is not writable");
+      logger.warn("Provider.request is not writable");
       return;
     }
 
@@ -420,14 +461,14 @@ export class FormoAnalytics implements IFormoAnalytics {
 
   private registerTransactionListener(): void {
     if (!this.provider) {
-      console.error("_trackTransactions: provider not found");
+      logger.error("Provider not found for transaction tracking");
       return;
     }
     if (
       Object.getOwnPropertyDescriptor(this.provider, "request")?.writable ===
       false
     ) {
-      console.warn("_trackTransactions: provider.request is not writable");
+      logger.warn("Provider.request is not writable");
       return;
     }
     const request = this.provider.request.bind(this.provider);
@@ -457,8 +498,8 @@ export class FormoAnalytics implements IFormoAnalytics {
 
           return;
         } catch (error) {
-          console.log("transaction listener catch");
-          console.log(error);
+          logger.info("Transaction listener catch");
+          logger.error("Transaction error:", error);
           const rpcError = error as RPCError;
           if (rpcError && rpcError?.code === 4001) {
             // Emit transaction rejected event
@@ -486,12 +527,11 @@ export class FormoAnalytics implements IFormoAnalytics {
   }
 
   private async onAddressConnected(address: Address): Promise<void> {
-    if (address === this.currentConnectedAddress) {
+    if (address === this.currentConnectedAddress)
       // We have already reported this address
       return;
-    } else {
-      this.currentConnectedAddress = address;
-    }
+
+    this.currentConnectedAddress = address;
 
     this.currentChainId = await this.getCurrentChainId();
     this.connect({ chainId: this.currentChainId, address });
@@ -507,6 +547,7 @@ export class FormoAnalytics implements IFormoAnalytics {
     };
     this.currentChainId = undefined;
     this.currentConnectedAddress = undefined;
+    session.remove(SESSION_USER_ID_KEY);
 
     await this.trackEvent(Event.DISCONNECT, payload);
   }
@@ -522,21 +563,21 @@ export class FormoAnalytics implements IFormoAnalytics {
     this.currentChainId = parseInt(chainIdHex);
     if (!this.currentConnectedAddress) {
       if (!this.provider) {
-        console.log(
-          "FormoAnalytics::onChainChanged: provider not found. CHAIN_CHANGED not reported"
+        logger.info(
+          "OnChainChanged: Provider not found. CHAIN_CHANGED not reported"
         );
         return Promise.resolve();
       }
 
       const address = await this.getAddress();
       if (!address) {
-        console.log(
-          "FormoAnalytics::onChainChanged: Unable to fetch or store connected address"
+        logger.info(
+          "OnChainChanged: Unable to fetch or store connected address"
         );
         return Promise.resolve();
       }
-
       this.currentConnectedAddress = address;
+      this.userId = await this.getUserId(address);
     }
 
     // Proceed only if the address exists
@@ -546,15 +587,15 @@ export class FormoAnalytics implements IFormoAnalytics {
         address: this.currentConnectedAddress,
       });
     } else {
-      console.log(
-        "FormoAnalytics::onChainChanged: currentConnectedAddress is null despite fetch attempt"
+      logger.info(
+        "OnChainChanged: Current connected address is null despite fetch attempt"
       );
     }
   }
 
   private async trackFirstPageHit(): Promise<void> {
-    if (session.get(CURRENT_URL_KEY) === null) {
-      session.set(CURRENT_URL_KEY, window.location.href);
+    if (session.get(SESSION_CURRENT_URL_KEY) === null) {
+      session.set(SESSION_CURRENT_URL_KEY, window.location.href);
     }
 
     return this.trackPageHit();
@@ -580,10 +621,10 @@ export class FormoAnalytics implements IFormoAnalytics {
   }
 
   private async onLocationChange(): Promise<void> {
-    const currentUrl = session.get(CURRENT_URL_KEY);
+    const currentUrl = session.get(SESSION_CURRENT_URL_KEY);
 
     if (currentUrl !== window.location.href) {
-      session.set(CURRENT_URL_KEY, window.location.href);
+      session.set(SESSION_CURRENT_URL_KEY, window.location.href);
       this.trackPageHit();
     }
   }
@@ -593,8 +634,8 @@ export class FormoAnalytics implements IFormoAnalytics {
     const hash = window.location.hash;
 
     if (!this.config.trackLocalhost && isLocalhost()) {
-      return console.warn(
-        "FormoAnalytics::trackPageHit: Ignoring event because website is running locally"
+      return logger.warn(
+        "Track page hit: Ignoring event because website is running locally"
       );
     }
 
@@ -607,64 +648,76 @@ export class FormoAnalytics implements IFormoAnalytics {
   }
 
   private async trackEvent(action: string, payload: any): Promise<void> {
-    const address = await this.getAddress();
-
-    const requestData: RequestEvent = {
-      address,
-      timestamp: new Date().toISOString(),
-      action,
-      version: "1",
-      payload: await this.buildEventPayload(toSnakeCase(payload)),
-    };
+    try {
+      const address = await this.getAddress();
+      const user_id = await this.getUserId(address);
+
+      const requestData: RequestEvent = {
+        anonymous_id: this.anonymousId as UUID,
+        user_id,
+        address,
+        timestamp: new Date().toISOString(),
+        action,
+        version: "1",
+        payload: await this.buildEventPayload(toSnakeCase(payload)),
+      };
 
-    await this.eventQueue.enqueue(requestData, (err, _, data) => {
-      if (err) {
-        console.error(err);
-      } else console.log(`Events sent successfully: ${data.length} events`);
-    });
+      await this.eventQueue.enqueue(requestData, (err, _, data) => {
+        if (err) {
+          logger.error("Error sending events:", err);
+        } else logger.info(`Events sent successfully: ${data.length} events`);
+      });
+    } catch (error) {
+      logger.error("Error tracking event:", error);
+    }
   }
 
   /*
     Utility functions
   */
 
-  private async getProviders(): Promise<EIP6963ProviderDetail[]> {
+  private async getProviders(): Promise<readonly EIP6963ProviderDetail[]> {
     const store = createStore();
-    const providers = [...store.getProviders()];
+    let providers = store.getProviders();
     // TODO: consider using store.subscribe to detect changes to providers list
-    // store.subscribe(providers => (state.providers = providers))
+    store.subscribe((providerDetails) => (providers = providerDetails));
 
     // Fallback to injected provider if no providers are found
     if (providers.length === 0) {
-      return [window?.ethereum];
+      return window?.ethereum ? [window.ethereum] : [];
     }
     return providers;
   }
 
-  private async identifyAll(providers: EIP6963ProviderDetail[]): Promise<void> {
+  private async identifyAll(
+    providers: readonly EIP6963ProviderDetail[]
+  ): Promise<void> {
     try {
-      for (const { provider, info } of providers) {
-        const accounts = await this.getAccounts(provider);
+      for (const eip6963ProviderDetail of providers) {
+        if (!eip6963ProviderDetail) continue;
+        const accounts = await this.getAccounts(
+          eip6963ProviderDetail?.provider
+        );
         // Identify with accounts
         if (accounts && accounts.length > 0) {
           for (const address of accounts) {
             await this.identify({
               address,
-              providerName: info.name,
-              rdns: info.rdns,
+              providerName: eip6963ProviderDetail?.info.name,
+              rdns: eip6963ProviderDetail?.info.rdns,
             });
           }
         } else {
           // Identify without accounts
           await this.identify({
             address: null,
-            providerName: info.name,
-            rdns: info.rdns,
+            providerName: eip6963ProviderDetail?.info.name,
+            rdns: eip6963ProviderDetail?.info.rdns,
           });
         }
       }
     } catch (err) {
-      console.log("identifying all => err", err);
+      logger.error("Error identifying all:", err);
     }
   }
 
@@ -672,20 +725,57 @@ export class FormoAnalytics implements IFormoAnalytics {
     return this._provider;
   }
 
+  private getAnonymousId(): UUID {
+    const storedAnonymousId = local.get(LOCAL_ANONYMOUS_ID_KEY);
+    if (storedAnonymousId && typeof storedAnonymousId === "string")
+      return storedAnonymousId as UUID;
+    const newAnonymousId = generateNativeUUID();
+    local.set(LOCAL_ANONYMOUS_ID_KEY, newAnonymousId);
+    return newAnonymousId;
+  }
+
+  private async getUserId(address: string | null): Promise<UUID | null> {
+    const storedUserId = session.get(SESSION_USER_ID_KEY);
+    if (storedUserId && typeof storedUserId === "string")
+      return storedUserId as UUID;
+
+    if (address) {
+      const res = await fetch(`${USER_API_URL}?address=${address}`, {
+        headers: EVENTS_API_REQUEST_HEADER(this.writeKey),
+        method: "GET",
+      });
+      const data = await res.json();
+      const userId = data?.data?.[0]?.user_id;
+      if (userId) {
+        session.set(SESSION_USER_ID_KEY, userId);
+        return userId;
+      }
+
+      const newUserId = generateNativeUUID();
+      session.set(SESSION_USER_ID_KEY, newUserId);
+      return newUserId;
+    }
+
+    return null;
+  }
+
   private async getAddress(): Promise<Address | null> {
     if (this.currentConnectedAddress) return this.currentConnectedAddress;
     if (!this?.provider) {
-      console.log("FormoAnalytics::getAddress: the provider is not set");
+      logger.info("The provider is not set");
       return null;
     }
 
     try {
       const accounts = await this.getAccounts();
       if (accounts && accounts.length > 0) {
-        return isAddress(accounts[0]) ? accounts[0] : null;
+        // TODO: fetch userId if account is valid, generate userId if no userId matches address from tinybird
+        if (isAddress(accounts[0])) {
+          return accounts[0];
+        }
       }
     } catch (err) {
-      console.log("Failed to fetch accounts from provider:", err);
+      logger.error("Failed to fetch accounts from provider:", err);
       return null;
     }
     return null;
@@ -703,7 +793,7 @@ export class FormoAnalytics implements IFormoAnalytics {
       return res.filter(isAddress);
     } catch (err) {
       if ((err as any).code !== 4001) {
-        console.log(
+        logger.error(
           "FormoAnalytics::getAccounts: eth_accounts threw an error",
           err
         );
@@ -714,7 +804,7 @@ export class FormoAnalytics implements IFormoAnalytics {
 
   private async getCurrentChainId(): Promise<number> {
     if (!this.provider) {
-      console.error("FormoAnalytics::getCurrentChainId: provider not set");
+      logger.error("Provider not set for chain ID");
     }
 
     let chainIdHex;
@@ -723,15 +813,12 @@ export class FormoAnalytics implements IFormoAnalytics {
         method: "eth_chainId",
       });
       if (!chainIdHex) {
-        console.log("FormoAnalytics::fetchChainId: chain id not found");
+        logger.info("Chain id not found");
         return 0;
       }
       return parseInt(chainIdHex as string, 16);
     } catch (err) {
-      console.log(
-        "FormoAnalytics::fetchChainId: eth_chainId threw an error",
-        err
-      );
+      logger.error("eth_chainId threw an error:", err);
       return 0;
     }
   }
@@ -743,7 +830,7 @@ export class FormoAnalytics implements IFormoAnalytics {
         return COUNTRY_LIST[timezone as keyof typeof COUNTRY_LIST];
       return timezone;
     } catch (error) {
-      console.error("Error resolving timezone:", error);
+      logger.error("Error resolving timezone:", error);
       return "";
     }
   }
@@ -756,7 +843,7 @@ export class FormoAnalytics implements IFormoAnalytics {
           : navigator.language) || "en"
       );
     } catch (error) {
-      console.error("Error resolving language:", error);
+      logger.error("Error resolving language:", error);
       return "en";
     }
   }

package/src/FormoAnalyticsProvider.tsx

@@ -1,6 +1,7 @@
 import { createContext, useContext, useEffect, useState, useRef } from "react";
 import { FormoAnalytics } from "./FormoAnalytics";
 import { FormoAnalyticsProviderProps } from "./types";
+import { logger } from "./lib";
 
 export const FormoAnalyticsContext = createContext<FormoAnalytics | undefined>(
   undefined
@@ -11,12 +12,12 @@ export const FormoAnalyticsProvider = (props: FormoAnalyticsProviderProps) => {
 
   // Keep the app running without analytics if no Write Key is provided or disabled
   if (!writeKey) {
-    console.error("FormoAnalyticsProvider: No Write Key provided");
+    logger.error("FormoAnalyticsProvider: No Write Key provided");
     return children;
   }
 
   if (disabled) {
-    console.warn("FormoAnalytics is disabled");
+    logger.warn("FormoAnalytics is disabled");
     return children;
   }
 
@@ -35,9 +36,9 @@ const InitializedAnalytics = ({
     try {
       const sdkInstance = await FormoAnalytics.init(writeKey, options);
       setSdk(sdkInstance);
-      console.log("FormoAnalytics SDK initialized successfully");
+      logger.log("FormoAnalytics SDK initialized successfully");
     } catch (error) {
-      console.error("Failed to initialize FormoAnalytics SDK", error);
+      logger.error("Failed to initialize FormoAnalytics SDK", error);
     }
   };
 
@@ -63,7 +64,7 @@ export const useFormoAnalytics = () => {
   const context = useContext(FormoAnalyticsContext);
 
   if (!context) {
-    console.warn("useFormoAnalytics called without a valid context");
+    logger.warn("useFormoAnalytics called without a valid context");
   }
 
   return context; // Return undefined if SDK is not initialized, handle accordingly in consumer

package/src/constants/base.ts

@@ -1,2 +1,12 @@
-export const SESSION_PREFIX = "f0-";
-export const SESSION_IDENTIFIED_KEY = SESSION_PREFIX + "session_identified";
+const STORAGE_PREFIX = "formo-";
+
+const generateStoragePrefix = (prefix: string) => `${STORAGE_PREFIX}${prefix}`;
+
+export const SESSION_IDENTIFIED_KEY =
+  generateStoragePrefix("session-identified");
+export const SESSION_CURRENT_URL_KEY = generateStoragePrefix(
+  "analytics-current-url"
+);
+export const SESSION_USER_ID_KEY = generateStoragePrefix("user-id");
+
+export const LOCAL_ANONYMOUS_ID_KEY = generateStoragePrefix("anonymous-id");

package/src/constants/config.ts

@@ -1,5 +1,12 @@
-export const EVENTS_API_URL = "https://events.formo.so/events";
-export const CURRENT_URL_KEY = "formo-analytics-current-url";
+export const EVENTS_API_HOST = "https://events.formo.so";
+export const EVENTS_API_URL = `${EVENTS_API_HOST}/events`;
+export const USER_API_URL = `${EVENTS_API_HOST}/user-id`;
+
+export const EVENTS_API_REQUEST_HEADER = (writeKey: string) => ({
+  "Content-Type": "application/json",
+  Authorization: `Basic ${writeKey}`,
+});
+
 export const COUNTRY_LIST = {
   // Africa
   "Africa/Abidjan": "CI",

package/src/lib/fetch.ts

@@ -0,0 +1,3 @@
+import fetch from "fetch-retry";
+
+export default fetch(global.fetch);

package/src/lib/index.ts

@@ -1,2 +1,4 @@
-export { default as session } from "./session-storage";
-export * from "./utils";
+export * from "./logger";
+export * from "./queue";
+export * from "./storage";
+export { default as fetch } from "./fetch";