@formo/analytics 1.14.3 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formo/analytics",
-  "version": "1.14.3",
+  "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, {
@@ -321,9 +355,7 @@ export class FormoAnalytics implements IFormoAnalytics {
   private trackProvider(provider: EIP1193Provider): void {
     try {
       if (provider === this._provider) {
-        console.warn(
-          "FormoAnalytics::trackProvider: Provider already tracked."
-        );
+        logger.warn("TrackProvider: Provider already tracked.");
         return;
       }
 
@@ -349,7 +381,7 @@ export class FormoAnalytics implements IFormoAnalytics {
       this.registerSignatureListener();
       this.registerTransactionListener();
     } catch (error) {
-      console.error("FormoAnalytics::trackProvider: error:", error);
+      logger.error("Error tracking provider:", error);
     }
   }
 
@@ -374,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;
     }
 
@@ -429,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);
@@ -466,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
@@ -495,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 });
@@ -516,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);
   }
@@ -531,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
@@ -555,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();
@@ -589,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();
     }
   }
@@ -602,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"
       );
     }
 
@@ -618,8 +650,11 @@ export class FormoAnalytics implements IFormoAnalytics {
   private async trackEvent(action: string, payload: any): Promise<void> {
     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,
@@ -629,11 +664,11 @@ export class FormoAnalytics implements IFormoAnalytics {
 
       await this.eventQueue.enqueue(requestData, (err, _, data) => {
         if (err) {
-          console.error(err);
-        } else console.log(`Events sent successfully: ${data.length} events`);
+          logger.error("Error sending events:", err);
+        } else logger.info(`Events sent successfully: ${data.length} events`);
       });
     } catch (error) {
-      console.error("FormoAnalytics::trackEvent: error:", error);
+      logger.error("Error tracking event:", error);
     }
   }
 
@@ -682,7 +717,7 @@ export class FormoAnalytics implements IFormoAnalytics {
         }
       }
     } catch (err) {
-      console.log("identifying all => err", err);
+      logger.error("Error identifying all:", err);
     }
   }
 
@@ -690,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;
@@ -721,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
         );
@@ -732,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;
@@ -741,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;
     }
   }
@@ -761,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 "";
     }
   }
@@ -774,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";

package/src/lib/logger.ts

@@ -0,0 +1,93 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "trace";
+
+export class Logger {
+  private static instance: Logger;
+  private enabledLevels: Set<LogLevel>;
+  private enabled: boolean;
+
+  private constructor(enabled: boolean = true, enabledLevels: LogLevel[] = []) {
+    this.enabled = enabled;
+    this.enabledLevels = new Set(enabledLevels);
+  }
+
+  public static getInstance(
+    enabled: boolean = false,
+    enabledLevels: LogLevel[] = []
+  ): Logger {
+    if (!Logger.instance) {
+      Logger.instance = new Logger(enabled, enabledLevels);
+    }
+    return Logger.instance;
+  }
+
+  public setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  public isLoggingEnabled(): boolean {
+    return this.enabled;
+  }
+
+  public setEnabledLevels(levels: LogLevel[]): void {
+    this.enabledLevels = new Set(levels);
+  }
+
+  public getEnabledLevels(): LogLevel[] {
+    return Array.from(this.enabledLevels);
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    if (!this.enabled) return false;
+    return this.enabledLevels.has(level);
+  }
+
+  private formatMessage(message: string): string {
+    const timestamp = new Date().toLocaleString("en-US", {
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hour12: false,
+    });
+    return `[Formo Analytics][${timestamp}] ${message}`;
+  }
+
+  public debug(message: string, ...args: any[]): void {
+    if (this.shouldLog("debug")) {
+      console.debug(this.formatMessage(message), ...args);
+    }
+  }
+
+  public info(message: string, ...args: any[]): void {
+    if (this.shouldLog("info")) {
+      console.info(this.formatMessage(message), ...args);
+    }
+  }
+
+  public warn(message: string, ...args: any[]): void {
+    if (this.shouldLog("warn")) {
+      console.warn(this.formatMessage(message), ...args);
+    }
+  }
+
+  public error(message: string, ...args: any[]): void {
+    if (this.shouldLog("error")) {
+      console.error(this.formatMessage(message), ...args);
+    }
+  }
+
+  public trace(message: string, ...args: any[]): void {
+    if (this.shouldLog("trace")) {
+      console.trace(this.formatMessage(message), ...args);
+    }
+  }
+
+  public log(message: string, ...args: any[]): void {
+    this.info(message, ...args);
+  }
+}
+
+// Export a default instance for easy use
+export const logger = Logger.getInstance();