@formo/analytics 1.15.1 → 1.16.0

package/package.json

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

package/src/FormoAnalytics.ts

@@ -6,8 +6,6 @@ import {
   EVENTS_API_URL,
   Event,
   SESSION_USER_ID_KEY,
-  EVENTS_API_REQUEST_HEADER,
-  USER_API_URL,
 } from "./constants";
 import {
   ChainID,
@@ -21,14 +19,14 @@ import {
   TransactionStatus,
   RequestEvent,
 } from "./types";
-import { session, local, logger, EventQueue, fetch } from "./lib";
+import { session, local, logger, EventQueue, Logger } from "./lib";
 import {
   isLocalhost,
   isAddress,
   toSnakeCase,
   generateNativeUUID,
 } from "./utils";
-import { SESSION_IDENTIFIED_KEY } from "./constants";
+import { SESSION_WALLET_DETECTED_KEY } from "./constants";
 import { UUID } from "crypto";
 
 interface IFormoAnalytics {
@@ -77,7 +75,7 @@ export class FormoAnalytics implements IFormoAnalytics {
   private session: FormoAnalyticsSession;
   private eventQueue: EventQueue;
   private anonymousId: UUID | null = null;
-  private userId: UUID | null = null;
+  private userId: string | null = null;
 
   config: Config;
   currentChainId?: ChainID;
@@ -95,13 +93,10 @@ 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);
-    }
+    Logger.init({
+      enabled: options.logger?.enabled || false,
+      enabledLevels: options.logger?.levels || [],
+    });
 
     this.eventQueue = new EventQueue(this.config.writeKey, {
       url: EVENTS_API_URL,
@@ -112,7 +107,7 @@ export class FormoAnalytics implements IFormoAnalytics {
     });
 
     this.anonymousId = this.getAnonymousId();
-    this.getUserId(null).then((userId) => (this.userId = userId));
+    this.userId = session.get(SESSION_USER_ID_KEY) as string | null;
 
     // TODO: replace with eip6963
     const provider = options.provider || window?.ethereum;
@@ -130,9 +125,9 @@ export class FormoAnalytics implements IFormoAnalytics {
   ): Promise<FormoAnalytics> {
     const analytics = new FormoAnalytics(writeKey, options);
 
-    // Identify
+    // Detect
     const providers = await analytics.getProviders();
-    await analytics.identifyAll(providers);
+    await analytics.detectWallets(providers);
 
     return analytics;
   }
@@ -321,16 +316,15 @@ export class FormoAnalytics implements IFormoAnalytics {
   public async identify({
     address,
     providerName,
+    userId,
     rdns,
   }: {
     address: Address | null;
     providerName?: string;
+    userId?: string;
     rdns?: string;
   }): Promise<void> {
-    if (this.session.isIdentified())
-      return logger.warn("Identify: Wallet already identified in this session");
-
-    this.session.identify();
+    if (userId) this.userId = userId || null;
     await this.trackEvent(Event.IDENTIFY, {
       address,
       providerName,
@@ -338,6 +332,30 @@ export class FormoAnalytics implements IFormoAnalytics {
     });
   }
 
+  /**
+   * Emits an identify event with current wallet address.
+   * @param {Address} params.address
+   * @returns {Promise<void>}
+   */
+  private async detectWallet({
+    providerName,
+    rdns,
+  }: {
+    providerName: string;
+    rdns: string;
+  }): Promise<void> {
+    if (this.session.isWalletDetected(rdns))
+      return logger.warn(
+        `detectWallet: Wallet ${providerName} already detected in this session`
+      );
+
+    this.session.markWalletdetected(rdns);
+    await this.trackEvent(Event.DETECT_WALLET, {
+      providerName,
+      rdns,
+    });
+  }
+
   /**
    * Emits a custom event with custom data.
    * @param {string} action
@@ -498,7 +516,6 @@ export class FormoAnalytics implements IFormoAnalytics {
 
           return;
         } catch (error) {
-          logger.info("Transaction listener catch");
           logger.error("Transaction error:", error);
           const rpcError = error as RPCError;
           if (rpcError && rpcError?.code === 4001) {
@@ -577,7 +594,6 @@ export class FormoAnalytics implements IFormoAnalytics {
         return Promise.resolve();
       }
       this.currentConnectedAddress = address;
-      this.userId = await this.getUserId(address);
     }
 
     // Proceed only if the address exists
@@ -650,12 +666,16 @@ 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 user_id = this.userId;
+
+      if (payload?.userId) {
+        delete payload.userId;
+      }
 
       const requestData: RequestEvent = {
         anonymous_id: this.anonymousId as UUID,
         user_id,
-        address,
+        address: address?.toLowerCase() || null,
         timestamp: new Date().toISOString(),
         action,
         version: "1",
@@ -689,38 +709,54 @@ export class FormoAnalytics implements IFormoAnalytics {
     return providers;
   }
 
-  private async identifyAll(
+  private async detectWallets(
     providers: readonly EIP6963ProviderDetail[]
   ): Promise<void> {
     try {
       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: eip6963ProviderDetail?.info.name,
-              rdns: eip6963ProviderDetail?.info.rdns,
-            });
-          }
-        } else {
-          // Identify without accounts
-          await this.identify({
-            address: null,
-            providerName: eip6963ProviderDetail?.info.name,
-            rdns: eip6963ProviderDetail?.info.rdns,
-          });
-        }
+        await this.detectWallet({
+          providerName: eip6963ProviderDetail?.info.name,
+          rdns: eip6963ProviderDetail?.info.rdns,
+        });
       }
     } catch (err) {
-      logger.error("Error identifying all:", err);
+      logger.error("Error detect all wallets:", err);
     }
   }
 
+  // TODO: Refactoring => public this function as API
+  // private async identifyAll(
+  //   providers: readonly EIP6963ProviderDetail[]
+  // ): Promise<void> {
+  //   try {
+  //     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: eip6963ProviderDetail?.info.name,
+  //             rdns: eip6963ProviderDetail?.info.rdns,
+  //           });
+  //         }
+  //       } else {
+  //         // Identify without accounts
+  //         await this.identify({
+  //           address: null,
+  //           providerName: eip6963ProviderDetail?.info.name,
+  //           rdns: eip6963ProviderDetail?.info.rdns,
+  //         });
+  //       }
+  //     }
+  //   } catch (err) {
+  //     logger.error("Error identifying all:", err);
+  //   }
+  // }
+
   get provider(): EIP1193Provider | undefined {
     return this._provider;
   }
@@ -734,31 +770,6 @@ export class FormoAnalytics implements IFormoAnalytics {
     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) {
@@ -769,7 +780,6 @@ export class FormoAnalytics implements IFormoAnalytics {
     try {
       const accounts = await this.getAccounts();
       if (accounts && accounts.length > 0) {
-        // TODO: fetch userId if account is valid, generate userId if no userId matches address from tinybird
         if (isAddress(accounts[0])) {
           return accounts[0];
         }
@@ -865,12 +875,12 @@ export class FormoAnalytics implements IFormoAnalytics {
       locale: language,
       location,
       referrer: document.referrer,
-      utm_source: params.get("utm_source"),
-      utm_medium: params.get("utm_medium"),
-      utm_campaign: params.get("utm_campaign"),
-      utm_content: params.get("utm_content"),
-      utm_term: params.get("utm_term"),
-      ref: params.get("ref"),
+      utm_source: params.get("utm_source")?.trim() || "",
+      utm_medium: params.get("utm_medium")?.trim() || "",
+      utm_campaign: params.get("utm_campaign")?.trim() || "",
+      utm_content: params.get("utm_content")?.trim() || "",
+      utm_term: params.get("utm_term")?.trim() || "",
+      ref: params.get("ref")?.trim() || "",
       ...eventSpecificPayload,
     };
   }
@@ -925,18 +935,21 @@ export class FormoAnalytics implements IFormoAnalytics {
 }
 
 interface IFormoAnalyticsSession {
-  isIdentified(): boolean;
-  identify(): void;
+  isWalletDetected(rdns: string): boolean;
+  markWalletdetected(rdns: string): void;
 }
 
 class FormoAnalyticsSession implements IFormoAnalyticsSession {
   constructor() {}
 
-  public isIdentified(): boolean {
-    return session.get(SESSION_IDENTIFIED_KEY) === true;
+  public isWalletDetected(rdns: string): boolean {
+    const rdnses = (session.get(SESSION_WALLET_DETECTED_KEY) as string[]) || [];
+    return rdnses.includes(rdns);
   }
 
-  public identify(): void {
-    session.set(SESSION_IDENTIFIED_KEY, true);
+  public markWalletdetected(rdns: string): void {
+    const rdnses = (session.get(SESSION_WALLET_DETECTED_KEY) as string[]) || [];
+    rdnses.push(rdns);
+    session.set(SESSION_WALLET_DETECTED_KEY, rdnses);
   }
 }

package/src/constants/base.ts

@@ -2,8 +2,9 @@ const STORAGE_PREFIX = "formo-";
 
 const generateStoragePrefix = (prefix: string) => `${STORAGE_PREFIX}${prefix}`;
 
-export const SESSION_IDENTIFIED_KEY =
-  generateStoragePrefix("session-identified");
+export const SESSION_WALLET_DETECTED_KEY = generateStoragePrefix(
+  "session-wallet-detected"
+);
 export const SESSION_CURRENT_URL_KEY = generateStoragePrefix(
   "analytics-current-url"
 );

package/src/constants/events.ts

@@ -1,9 +1,10 @@
 export enum Event {
-  PAGE = 'page_hit',
-  IDENTIFY = 'identify',  
-  CONNECT = 'connect',
-  DISCONNECT = 'disconnect',
-  CHAIN_CHANGED = 'chain_changed',
-  SIGNATURE = 'signature',
-  TRANSACTION = 'transaction',
+  PAGE = "page_hit",
+  IDENTIFY = "identify",
+  DETECT_WALLET = "detect_wallet",
+  CONNECT = "connect",
+  DISCONNECT = "disconnect",
+  CHAIN_CHANGED = "chain_changed",
+  SIGNATURE = "signature",
+  TRANSACTION = "transaction",
 }

package/src/lib/logger.ts

@@ -5,17 +5,39 @@ export class Logger {
   private enabledLevels: Set<LogLevel>;
   private enabled: boolean;
 
-  private constructor(enabled: boolean = true, enabledLevels: LogLevel[] = []) {
+  private constructor(
+    enabled: boolean = false,
+    enabledLevels: LogLevel[] = []
+  ) {
     this.enabled = enabled;
     this.enabledLevels = new Set(enabledLevels);
   }
 
-  public static getInstance(
-    enabled: boolean = false,
-    enabledLevels: LogLevel[] = []
-  ): Logger {
+  public static init(config: {
+    enabled?: boolean;
+    enabledLevels?: LogLevel[];
+  }): void {
+    // Get or create instance
+    const instance = Logger.getInstance();
+
+    // Update configuration
+    if (config.enabled !== undefined) {
+      instance.setEnabled(config.enabled);
+    }
+    if (config.enabledLevels !== undefined) {
+      instance.setEnabledLevels(config.enabledLevels);
+    }
+  }
+
+  public static getInstance(config?: {
+    enabled?: boolean;
+    enabledLevels?: LogLevel[];
+  }): Logger {
     if (!Logger.instance) {
-      Logger.instance = new Logger(enabled, enabledLevels);
+      Logger.instance = new Logger(
+        config?.enabled ?? false,
+        config?.enabledLevels ?? []
+      );
     }
     return Logger.instance;
   }

package/src/lib/queue.ts

@@ -96,16 +96,17 @@ export class EventQueue {
   }
 
   //#region Public functions
-  async enqueue(message: RequestEvent, callback?: (...args: any) => void) {
+  async enqueue(event: RequestEvent, callback?: (...args: any) => void) {
     callback = callback || noop;
 
-    const formattedTimestamp = toDateHourMinute(new Date(message.timestamp));
-    message.timestamp = formattedTimestamp;
+    const formattedTimestamp = toDateHourMinute(new Date(event.timestamp));
+    const originTimestamp = event.timestamp;
+    event.timestamp = formattedTimestamp;
 
-    const messageString = JSON.stringify(message);
-    const hashToken = await hash(messageString);
+    const eventString = JSON.stringify(event);
+    const eventId = await hash(eventString);
     // check if the message already exists
-    if (await this.isDuplicated(hashToken)) {
+    if (await this.isDuplicate(eventId)) {
       logger.warn(
         `Event already enqueued, try again after ${millisecondsToSecond(
           this.flushIntervalMs
@@ -114,10 +115,10 @@ export class EventQueue {
       return;
     }
 
-    this.queue.push({ message: { ...message, id: hashToken }, callback });
+    this.queue.push({ message: { ...event, timestamp: originTimestamp, id: eventId }, callback });
 
     logger.log(
-      `Event enqueued: ${getActionDescriptor(message.action, message.payload)}`
+      `Event enqueued: ${getActionDescriptor(event.action, event.payload)}`
     );
 
     if (!this.flushed) {
@@ -220,11 +221,11 @@ export class EventQueue {
     return false;
   }
 
-  private async isDuplicated(hashToken: string) {
+  private async isDuplicate(eventId: string) {
     // check if exists a message with identical payload within 1 minute
-    if (this.payloadHashes.has(hashToken)) return true;
+    if (this.payloadHashes.has(eventId)) return true;
 
-    this.payloadHashes.add(hashToken);
+    this.payloadHashes.add(eventId);
     return false;
   }
 

package/src/types/events.ts

@@ -2,7 +2,7 @@ import { UUID } from "crypto";
 
 export interface RequestEvent {
   anonymous_id: UUID;
-  user_id: UUID | null;
+  user_id: string | null;
   action: string;
   payload: Record<string, unknown>;
   address: string | null;