@formo/analytics 1.13.4-alpha.9 → 1.14.1

package/package.json

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

package/src/FormoAnalytics.ts

@@ -1,4 +1,3 @@
-import axios from "axios";
 import { createStore, EIP6963ProviderDetail } from "mipd";
 import {
   COUNTRY_LIST,
@@ -16,9 +15,11 @@ import {
   RPCError,
   SignatureStatus,
   TransactionStatus,
+  RequestEvent,
 } from "./types";
-import { formoSessionStorage, isLocalhost, toSnakeCase } from "./lib";
+import { session, isLocalhost, toSnakeCase, isAddress } from "./lib";
 import { SESSION_IDENTIFIED_KEY } from "./constants";
+import { FormoAnalyticsEventQueue } from "./FormoAnalyticsEventQueue";
 
 interface IFormoAnalytics {
   page(): void;
@@ -62,7 +63,8 @@ interface IFormoAnalytics {
 export class FormoAnalytics implements IFormoAnalytics {
   private _provider?: EIP1193Provider;
   private _providerListeners: Record<string, (...args: unknown[]) => void> = {};
-  private sessionIdentified?: boolean = false;
+  private session: FormoAnalyticsSession;
+  private eventQueue: FormoAnalyticsEventQueue;
 
   config: Config;
   currentChainId?: ChainID;
@@ -74,11 +76,18 @@ export class FormoAnalytics implements IFormoAnalytics {
   ) {
     this.config = {
       apiKey,
-      trackLocalhost: options.trackLocalhost,
+      trackLocalhost: options.trackLocalhost || false,
     };
 
-    this.sessionIdentified =
-      (formoSessionStorage.getItem(SESSION_IDENTIFIED_KEY) as boolean) ?? false;
+    this.session = new FormoAnalyticsSession();
+
+    this.eventQueue = new FormoAnalyticsEventQueue(this.config.apiKey, {
+      url: EVENTS_API_URL,
+      flushAt: options.flushAt,
+      retryCount: options.retryCount,
+      maxQueueSize: options.maxQueueSize,
+      flushInterval: options.flushInterval,
+    });
 
     // TODO: replace with eip6963
     const provider = options.provider || window?.ethereum;
@@ -282,15 +291,17 @@ export class FormoAnalytics implements IFormoAnalytics {
     providerName?: string;
     rdns?: string;
   }): Promise<void> {
-    if (this.sessionIdentified === false) {
-      this.sessionIdentified = true;
-      formoSessionStorage.setItem(SESSION_IDENTIFIED_KEY, true);
-      await this.trackEvent(Event.IDENTIFY, {
-        address,
-        providerName,
-        rdns,
-      });
-    }
+    if (this.session.isIdentified())
+      return console.warn(
+        "FormoAnalytics::identify: Wallet already identified in this session"
+      );
+
+    this.session.identify();
+    await this.trackEvent(Event.IDENTIFY, {
+      address,
+      providerName,
+      rdns,
+    });
   }
 
   /**
@@ -309,7 +320,7 @@ export class FormoAnalytics implements IFormoAnalytics {
 
   private trackProvider(provider: EIP1193Provider): void {
     if (provider === this._provider) {
-      console.log("Provider already tracked.");
+      console.warn("FormoAnalytics::trackProvider: Provider already tracked.");
       return;
     }
 
@@ -542,8 +553,8 @@ export class FormoAnalytics implements IFormoAnalytics {
   }
 
   private async trackFirstPageHit(): Promise<void> {
-    if (formoSessionStorage.getItem(CURRENT_URL_KEY) === null) {
-      formoSessionStorage.setItem(CURRENT_URL_KEY, window.location.href);
+    if (session.get(CURRENT_URL_KEY) === null) {
+      session.set(CURRENT_URL_KEY, window.location.href);
     }
 
     return this.trackPageHit();
@@ -569,40 +580,36 @@ export class FormoAnalytics implements IFormoAnalytics {
   }
 
   private async onLocationChange(): Promise<void> {
-    const currentUrl = formoSessionStorage.getItem(CURRENT_URL_KEY);
+    const currentUrl = session.get(CURRENT_URL_KEY);
 
     if (currentUrl !== window.location.href) {
-      formoSessionStorage.setItem(CURRENT_URL_KEY, window.location.href);
+      session.set(CURRENT_URL_KEY, window.location.href);
       this.trackPageHit();
     }
   }
 
   private trackPageHit(): void {
     const pathname = window.location.pathname;
-    const href = window.location.href;
     const hash = window.location.hash;
 
     if (!this.config.trackLocalhost && isLocalhost()) {
       return console.warn(
-        "[Formo] Ignoring event because website is running locally"
+        "FormoAnalytics::trackPageHit: Ignoring event because website is running locally"
       );
     }
 
     setTimeout(async () => {
       this.trackEvent(Event.PAGE, {
         pathname,
-        href,
         hash,
       });
     }, 300);
   }
 
-  // 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();
 
-    const requestData = {
+    const requestData: RequestEvent = {
       address,
       timestamp: new Date().toISOString(),
       action,
@@ -610,31 +617,11 @@ export class FormoAnalytics implements IFormoAnalytics {
       payload: await this.buildEventPayload(toSnakeCase(payload)),
     };
 
-    try {
-      const response = await axios.post(
-        EVENTS_API_URL,
-        JSON.stringify(requestData),
-        {
-          headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${this.config.apiKey}`,
-          },
-        }
-      );
-
-      if (response.status >= 200 && response.status < 300) {
-        console.log(
-          `Event sent successfully: ${this.getActionDescriptor(
-            action,
-            payload
-          )}`
-        );
-      } else {
-        throw new Error(`Failed with status: ${response.status}`);
-      }
-    } catch (error) {
-      console.error(`Event "${action}" failed. Error: ${error}`);
-    }
+    this.eventQueue.enqueue(requestData, (err, _, data) => {
+      if (err) {
+        console.error(err);
+      } else console.log(`Events sent successfully: ${data.length} events`);
+    });
   }
 
   /*
@@ -655,8 +642,8 @@ export class FormoAnalytics implements IFormoAnalytics {
   }
 
   private async identifyAll(providers: EIP6963ProviderDetail[]): Promise<void> {
-    for (const { provider, info } of providers) {
-      try {
+    try {
+      for (const { provider, info } of providers) {
         const accounts = await this.getAccounts(provider);
         // Identify with accounts
         if (accounts && accounts.length > 0) {
@@ -675,9 +662,9 @@ export class FormoAnalytics implements IFormoAnalytics {
             rdns: info.rdns,
           });
         }
-      } catch (err) {
-        console.log("identifying all => err", err);
       }
+    } catch (err) {
+      console.log("identifying all => err", err);
     }
   }
 
@@ -687,7 +674,7 @@ export class FormoAnalytics implements IFormoAnalytics {
 
   private async getAddress(): Promise<Address | null> {
     if (this.currentConnectedAddress) return this.currentConnectedAddress;
-    if (!this.provider) {
+    if (!this?.provider) {
       console.log("FormoAnalytics::getAddress: the provider is not set");
       return null;
     }
@@ -695,7 +682,7 @@ export class FormoAnalytics implements IFormoAnalytics {
     try {
       const accounts = await this.getAccounts();
       if (accounts && accounts.length > 0) {
-        return accounts[0];
+        return isAddress(accounts[0]) ? accounts[0] : null;
       }
     } catch (err) {
       console.log("Failed to fetch accounts from provider:", err);
@@ -713,7 +700,7 @@ export class FormoAnalytics implements IFormoAnalytics {
         method: "eth_accounts",
       });
       if (!res || res.length === 0) return null;
-      return res;
+      return res.filter(isAddress);
     } catch (err) {
       if ((err as any).code !== 4001) {
         console.log(
@@ -787,13 +774,15 @@ export class FormoAnalytics implements IFormoAnalytics {
     // common browser properties
     return {
       "user-agent": window.navigator.userAgent,
-      origin: url.origin,
+      href: url.href,
       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"),
       ...eventSpecificPayload,
     };
@@ -846,8 +835,21 @@ export class FormoAnalytics implements IFormoAnalytics {
       value,
     };
   }
+}
+
+interface IFormoAnalyticsSession {
+  isIdentified(): boolean;
+  identify(): void;
+}
+
+class FormoAnalyticsSession implements IFormoAnalyticsSession {
+  constructor() {}
+
+  public isIdentified(): boolean {
+    return session.get(SESSION_IDENTIFIED_KEY) === true;
+  }
 
-  private getActionDescriptor(action: string, payload: any): string {
-    return `${action}${payload.status ? ` ${payload.status}` : ""}`;
+  public identify(): void {
+    session.set(SESSION_IDENTIFIED_KEY, true);
   }
 }

package/src/FormoAnalyticsEventQueue.ts

@@ -0,0 +1,282 @@
+import fetch from "fetch-retry";
+import isNetworkError from "is-network-error";
+import FingerprintJS from "@fingerprintjs/fingerprintjs";
+import { RequestEvent } from "./types";
+
+const sdkFetch = fetch(global.fetch);
+
+const noop = () => {};
+
+type QueueItem = {
+  message: RequestEvent;
+  callback: (...args: any) => any;
+};
+
+type Options = {
+  url: string;
+  flushAt?: number;
+  flushInterval?: number;
+  host?: string;
+  retryCount?: number;
+  errorHandler?: any;
+  maxQueueSize?: number;
+};
+
+const DEFAULT_RETRY = 3;
+const MAX_RETRY = 5;
+const MIN_RETRY = 1;
+
+const DEFAULT_FLUSH_AT = 20;
+const MAX_FLUSH_AT = 20;
+const MIN_FLUSH_AT = 1;
+
+const DEFAULT_QUEUE_SIZE = 1_024 * 500; // 500kB
+const MAX_QUEUE_SIZE = 1_024 * 500; // 500kB
+const MIN_QUEUE_SIZE = 200; // 200 bytes
+
+const DEFAULT_FLUSH_INTERVAL = 1_000 * 60; // 1 MINUTE
+const MAX_FLUSH_INTERVAL = 1_000 * 300; // 5 MINUTES
+const MIN_FLUSH_INTERVAL = 1_000 * 10; // 10 SECONDS
+
+export class FormoAnalyticsEventQueue {
+  private writeKey: string;
+  private url: string;
+  private queue: QueueItem[];
+  private timer: null | NodeJS.Timeout;
+  private flushAt: number;
+  private flushInterval: number;
+  private flushed: boolean;
+  private maxQueueSize: number; // min 200 bytes, max 500kB
+  private errorHandler: any;
+  private retryCount: number;
+  private pendingFlush: Promise<any> | null;
+
+  constructor(writeKey: string, options: Options) {
+    options = options || {};
+
+    this.queue = [];
+    this.writeKey = writeKey;
+    this.url = options.url;
+    this.retryCount = this.getFormattedNumericParams(
+      options.retryCount || DEFAULT_RETRY,
+      MAX_RETRY,
+      MIN_RETRY
+    );
+    this.flushAt = this.getFormattedNumericParams(
+      options.flushAt || DEFAULT_FLUSH_AT,
+      MAX_FLUSH_AT,
+      MIN_FLUSH_AT
+    );
+    this.maxQueueSize = this.getFormattedNumericParams(
+      options.maxQueueSize || DEFAULT_QUEUE_SIZE,
+      MAX_QUEUE_SIZE,
+      MIN_QUEUE_SIZE
+    );
+    this.flushInterval = this.getFormattedNumericParams(
+      options.flushInterval || DEFAULT_FLUSH_INTERVAL,
+      MAX_FLUSH_INTERVAL,
+      MIN_FLUSH_INTERVAL
+    );
+    this.flushed = true;
+    this.errorHandler = options.errorHandler;
+    this.pendingFlush = null;
+    this.timer = null;
+
+    // flush before page close
+    window.addEventListener("beforeunload", async (e) => {
+      e.stopImmediatePropagation();
+      await this.flush();
+    });
+  }
+
+  //#region Public functions
+  enqueue(message: RequestEvent, callback?: (...args: any) => void) {
+    callback = callback || noop;
+
+    // check if the message already exists
+    if (this.checkDuplicate(message)) {
+      console.warn(
+        `Event already enqueued, try again after ${this.millisecondsToSecond(
+          this.flushInterval
+        )} seconds.`
+      );
+      return;
+    }
+
+    this.queue.push({ message, callback });
+    console.log(
+      `Event enqueued: ${this.getActionDescriptor(
+        message.action,
+        message.payload
+      )}`
+    );
+
+    if (!this.flushed) {
+      this.flushed = true;
+      this.flush();
+      return;
+    }
+
+    const hasReachedFlushAt = this.queue.length >= this.flushAt;
+    const hasReachedQueueSize =
+      this.queue.reduce((acc, item) => acc + JSON.stringify(item).length, 0) >=
+      this.maxQueueSize;
+
+    if (hasReachedFlushAt || hasReachedQueueSize) {
+      this.flush();
+      return;
+    }
+
+    if (this.flushInterval && !this.timer) {
+      this.timer = setTimeout(this.flush.bind(this), this.flushInterval);
+    }
+  }
+
+  async flush(callback?: (...args: any) => void) {
+    callback = callback || noop;
+
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+
+    if (!this.queue.length) {
+      callback();
+      return Promise.resolve();
+    }
+
+    try {
+      if (this.pendingFlush) {
+        await this.pendingFlush;
+      }
+    } catch (err) {
+      this.pendingFlush = null;
+      throw err;
+    }
+
+    const items = this.queue.splice(0, this.flushAt);
+    const data = items.map((item) => item.message);
+
+    const done = (err?: Error) => {
+      items.forEach(({ message, callback }) => callback(err, message, data));
+      callback(err, data);
+    };
+
+    const req = {
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Basic ${this.writeKey}`,
+        "X-Visitor-Id": await this.getVisitorId(),
+      },
+    };
+
+    return (this.pendingFlush = sdkFetch(`${this.url}`, {
+      method: "POST",
+      body: JSON.stringify(data),
+      retries: this.retryCount,
+      retryDelay: (attempt) => Math.pow(2, attempt) * 1_000, // exponential backoff
+      retryOn: (_, error) => this.isErrorRetryable(error),
+      ...req,
+    })
+      .then(() => {
+        done();
+        return Promise.resolve(data);
+      })
+      .catch((err) => {
+        if (typeof this.errorHandler === "function") {
+          done(err);
+          return this.errorHandler(err);
+        }
+
+        if (err.response) {
+          const error = new Error(err.response.statusText);
+          done(error);
+          throw error;
+        }
+
+        done(err);
+        throw err;
+      }));
+  }
+
+  //#endregion
+
+  //#region Utility functions
+
+  private async getVisitorId(): Promise<string> {
+    const fp = await FingerprintJS.load();
+    const { visitorId } = await fp.get();
+    return visitorId;
+  }
+
+  private isErrorRetryable(error: any) {
+    // Retry Network Errors.
+    if (isNetworkError(error)) return true;
+
+    // Cannot determine if the request can be retried
+    if (!error?.response) return false;
+
+    // Retry Server Errors (5xx).
+    if (error?.response?.status >= 500 && error?.response?.status <= 599)
+      return true;
+
+    // Retry if rate limited.
+    if (error?.response?.status === 429) return true;
+
+    return false;
+  }
+
+  private millisecondsToSecond(milliseconds: number): number {
+    return Math.ceil(milliseconds / 1_000);
+  }
+
+  private toDateHourMinute(date: Date) {
+    return (
+      date.getUTCFullYear() +
+      "-" +
+      ("0" + (date.getUTCMonth() + 1)).slice(-2) +
+      "-" +
+      ("0" + date.getUTCDate()).slice(-2) +
+      " " +
+      ("0" + date.getUTCHours()).slice(-2) +
+      ":" +
+      ("0" + date.getUTCMinutes()).slice(-2)
+    );
+  }
+
+  private checkDuplicate(newMessage: RequestEvent) {
+    // check if exists a message with identical payload within 1 minute
+    const formattedTimestamp = this.toDateHourMinute(
+      new Date(newMessage.timestamp)
+    );
+    const stringifiedMessage = JSON.stringify({
+      ...newMessage,
+      timestamp: formattedTimestamp,
+    });
+
+    return this.queue.some((item) => {
+      const { message } = item;
+      const formattedItemTimestamp = this.toDateHourMinute(
+        new Date(message.timestamp)
+      );
+      const stringifiedItem = JSON.stringify({
+        ...message,
+        timestamp: formattedItemTimestamp,
+      });
+
+      return stringifiedItem === stringifiedMessage;
+    });
+  }
+
+  private getActionDescriptor(action: string, payload: any): string {
+    return `${action}${payload?.status ? ` ${payload?.status}` : ""}`;
+  }
+
+  private getFormattedNumericParams(value: number, max: number, min: number) {
+    if (value < min) return min;
+    if (value > max) return max;
+
+    return value;
+  }
+  //#endregion
+}

package/src/FormoAnalyticsProvider.tsx

@@ -29,7 +29,6 @@ const InitializedAnalytics = ({
   children,
 }: FormoAnalyticsProviderProps) => {
   const [sdk, setSdk] = useState<FormoAnalytics | undefined>();
-  const [isInitialized, setIsInitialized] = useState(false);
   const initializedStartedRef = useRef(false);
 
   const initializeFormoAnalytics = async (apiKey: string, options: any) => {
@@ -39,8 +38,6 @@ const InitializedAnalytics = ({
       console.log("FormoAnalytics SDK initialized successfully");
     } catch (error) {
       console.error("Failed to initialize FormoAnalytics SDK", error);
-    } finally {
-      setIsInitialized(true); // Ensure UI renders even after failure
     }
   };
 
@@ -55,11 +52,6 @@ const InitializedAnalytics = ({
     initialize();
   }, [apiKey, options]);
 
-  if (!isInitialized) {
-    // Optionally show a loading state until initialization attempt finishes
-    return <div>Loading analytics...</div>;
-  }
-
   return (
     <FormoAnalyticsContext.Provider value={sdk}>
       {children}

package/src/constants/index.ts

@@ -1,3 +1,4 @@
 export * from "./base";
 export * from "./config";
 export * from "./events";
+export * from "./regex";

package/src/constants/regex.ts

@@ -0,0 +1,3 @@
+export const REGEX = {
+  addressRegex: /^0x[a-fA-F0-9]{40}$/,
+};

package/src/lib/index.ts

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

package/src/lib/session-storage.ts

@@ -1,14 +1,14 @@
 export class SessionStorage {
   private readonly json_prefix = "__json=";
 
-  public setItem(key: string, value: any): void {
+  public set(key: string, value: any): void {
     if (typeof value === "boolean") value = value === true ? "true" : "false";
     if (typeof value === "object")
       value = this.json_prefix + JSON.stringify(value);
     sessionStorage.setItem(key, value);
   }
 
-  public getItem(key: string): string | boolean | Record<any, any> | null {
+  public get(key: string): string | boolean | Record<any, any> | null {
     const value = sessionStorage.getItem(key);
 
     if (!value || typeof value !== "string") return null;
@@ -36,12 +36,12 @@ export class SessionStorage {
   public removeMatch(pattern: RegExp): void {
     for (const key in sessionStorage) {
       if (pattern.test(key)) {
-        this.removeItem(key);
+        this.remove(key);
       }
     }
   }
 
-  public removeItem(key: string): void {
+  public remove(key: string): void {
     sessionStorage.removeItem(key);
   }
 

package/src/lib/utils.ts

@@ -1,3 +1,5 @@
+import { REGEX } from "../constants";
+
 const toSnake = (str: string) =>
   str
     .replace(/([a-z])([A-Z])/g, "$1_$2")
@@ -29,3 +31,5 @@ export const isLocalhost = () =>
   /^localhost$|^127(?:\.[0-9]+){0,2}\.[0-9]+$|^(?:0*:)*?:?0*1$/.test(
     window.location.hostname
   ) || window.location.protocol === "file:";
+
+export const isAddress = (address: string) => REGEX.addressRegex.test(address);

package/src/types/base.ts

@@ -9,6 +9,11 @@ export type Address = string;
 export interface Options {
   provider?: EIP1193Provider;
   trackLocalhost?: boolean;
+
+  flushAt?: number;
+  flushInterval?: number;
+  retryCount?: number;
+  maxQueueSize?: number;
 }
 
 export interface FormoAnalyticsProviderProps {

package/src/types/events.ts

@@ -1,11 +1,19 @@
+export interface RequestEvent {
+  action: string;
+  payload: Record<string, unknown>;
+  address: string | null;
+  timestamp: string;
+  version: string;
+}
+
 export enum SignatureStatus {
-  REQUESTED = 'requested',
-  REJECTED = 'rejected',
-  CONFIRMED = 'confirmed',
+  REQUESTED = "requested",
+  REJECTED = "rejected",
+  CONFIRMED = "confirmed",
 }
 
 export enum TransactionStatus {
-  STARTED = 'started',
-  REJECTED = 'rejected',
-  BROADCASTED = 'broadcasted',
-}
+  STARTED = "started",
+  REJECTED = "rejected",
+  BROADCASTED = "broadcasted",
+}