@formo/analytics 1.13.4 → 1.14.2

package/src/constants/config.ts

@@ -64,7 +64,7 @@ export const COUNTRY_LIST = {
   "America/Araguaina": "BR",
   "America/Argentina/Buenos_Aires": "AR",
   "America/Argentina/Catamarca": "AR",
-  "America/Argentina/ComodRivadavi": "AR",
+  "America/Argentina/ComodRivadavia": "AR",
   "America/Argentina/Cordoba": "AR",
   "America/Argentina/Jujuy": "AR",
   "America/Argentina/La_Rioja": "AR",
@@ -181,7 +181,7 @@ export const COUNTRY_LIST = {
   "America/North_Dakota/New_Salem": "US",
   "America/Nuuk": "GL",
   "America/Ojinaga": "MX",
-  "America/Panama": "PA,CA,KY",
+  "America/Panama": "PA",
   "America/Pangnirtung": "CA",
   "America/Paramaribo": "SR",
   "America/Phoenix": "US,CA",
@@ -392,58 +392,58 @@ export const COUNTRY_LIST = {
   "Canada/Saskatchewan": "CA",
   "Canada/Yukon": "CA",
   // CET
-  CET: "",
+  CET: "CET",
   // Chile
   "Chile/Continental": "CL",
   "Chile/EasterIsland": "CL",
   // CST6CDT
-  CST6CDT: "",
+  CST6CDT: "CST6CDT",
   // Cuba
   Cuba: "CU",
   // EET
-  EET: "",
+  EET: "EET",
   // Egypt
   Egypt: "EG",
   // Eire
   Eire: "IE",
   // EST
-  EST: "",
-  EST5EDT: "",
-  "Etc/GMT": "",
-  "Etc/GMT+0": "",
-  "Etc/GMT+1": "",
-  "Etc/GMT+10": "",
-  "Etc/GMT+11": "",
-  "Etc/GMT+12": "",
-  "Etc/GMT+2": "",
-  "Etc/GMT+3": "",
-  "Etc/GMT+4": "",
-  "Etc/GMT+5": "",
-  "Etc/GMT+6": "",
-  "Etc/GMT+7": "",
-  "Etc/GMT+8": "",
-  "Etc/GMT+9": "",
-  "Etc/GMT-0": "",
-  "Etc/GMT-1": "",
-  "Etc/GMT-10": "",
-  "Etc/GMT-11": "",
-  "Etc/GMT-12": "",
-  "Etc/GMT-13": "",
-  "Etc/GMT-14": "",
-  "Etc/GMT-2": "",
-  "Etc/GMT-3": "",
-  "Etc/GMT-4": "",
-  "Etc/GMT-5": "",
-  "Etc/GMT-6": "",
-  "Etc/GMT-7": "",
-  "Etc/GMT-8": "",
-  "Etc/GMT-9": "",
-  "Etc/GMT0": "",
-  "Etc/Greenwich": "",
-  "Etc/UCT": "",
-  "Etc/UTC": "",
-  "Etc/Universal": "",
-  "Etc/Zulu": "",
+  EST: "EST",
+  EST5EDT: "EST5EDT",
+  "Etc/GMT": "Etc/GMT",
+  "Etc/GMT+0": "Etc/GMT+0",
+  "Etc/GMT+1": "Etc/GMT+1",
+  "Etc/GMT+10": "Etc/GMT+10",
+  "Etc/GMT+11": "Etc/GMT+11",
+  "Etc/GMT+12": "Etc/GMT+12",
+  "Etc/GMT+2": "Etc/GMT+2",
+  "Etc/GMT+3": "Etc/GMT+3",
+  "Etc/GMT+4": "Etc/GMT+4",
+  "Etc/GMT+5": "Etc/GMT+5",
+  "Etc/GMT+6": "Etc/GMT+6",
+  "Etc/GMT+7": "Etc/GMT+7",
+  "Etc/GMT+8": "Etc/GMT+8",
+  "Etc/GMT+9": "Etc/GMT+9",
+  "Etc/GMT-0": "Etc/GMT-0",
+  "Etc/GMT-1": "Etc/GMT-1",
+  "Etc/GMT-10": "Etc/GMT-10",
+  "Etc/GMT-11": "Etc/GMT-11",
+  "Etc/GMT-12": "Etc/GMT-12",
+  "Etc/GMT-13": "Etc/GMT-13",
+  "Etc/GMT-14": "Etc/GMT-14",
+  "Etc/GMT-2": "Etc/GMT-2",
+  "Etc/GMT-3": "Etc/GMT-3",
+  "Etc/GMT-4": "Etc/GMT-4",
+  "Etc/GMT-5": "Etc/GMT-5",
+  "Etc/GMT-6": "Etc/GMT-6",
+  "Etc/GMT-7": "Etc/GMT-7",
+  "Etc/GMT-8": "Etc/GMT-8",
+  "Etc/GMT-9": "Etc/GMT-9",
+  "Etc/GMT0": "Etc/GMT0",
+  "Etc/Greenwich": "Etc/Greenwich",
+  "Etc/UCT": "Etc/UCT",
+  "Etc/UTC": "Etc/UTC",
+  "Etc/Universal": "Etc/Universal",
+  "Etc/Zulu": "Etc/Zulu",
   // Europe
   "Europe/Amsterdam": "NL",
   "Europe/Andorra": "AD",
@@ -510,20 +510,20 @@ export const COUNTRY_LIST = {
   "Europe/Zaporozhye": "UA",
   "Europe/Zurich": "CH",
   // Factory
-  Factory: "",
+  Factory: "Factory",
   // GB
   GB: "GB",
   "GB-Eire": "GB",
   // GMT
-  GMT: "",
-  "GMT+0": "",
-  "GMT-0": "",
-  GMT0: "",
-  Greenwich: "",
+  GMT: "GMT",
+  "GMT+0": "GMT+0",
+  "GMT-0": "GMT-0",
+  GMT0: "GMT0",
+  Greenwich: "Greenwich",
   // HK
   Hongkong: "HK",
   // HST
-  HST: "",
+  HST: "HST",
   // Iceland
   Iceland: "IS",
   // Indian
@@ -551,14 +551,14 @@ export const COUNTRY_LIST = {
   // Libya
   Libya: "LY",
   // MET
-  MET: "",
+  MET: "MET",
   // Mexico
   "Mexico/BajaNorte": "MX",
   "Mexico/BajaSur": "MX",
   "Mexico/General": "MX",
   // MST
-  MST: "",
-  MST7MDT: "",
+  MST: "MST",
+  MST7MDT: "MST7MDT",
   // Navajo
   Navajo: "US",
   // NZ
@@ -616,7 +616,7 @@ export const COUNTRY_LIST = {
   // PRC
   PRC: "CN",
   // PST8PDT
-  PST8PDT: "",
+  PST8PDT: "PST8PDT",
   // ROC
   ROC: "TW",
   // ROK
@@ -626,9 +626,9 @@ export const COUNTRY_LIST = {
   // Turkey
   Turkey: "TR",
   // UCT
-  UCT: "",
+  UCT: "UCT",
   // Universal
-  Universal: "",
+  Universal: "Universal",
   // US
   "US/Alaska": "US",
   "US/Aleutian": "US",
@@ -643,11 +643,11 @@ export const COUNTRY_LIST = {
   "US/Pacific": "US",
   "US/Samoa": "AS",
   // UTC
-  UTC: "",
+  UTC: "UTC",
   // W-SU
   "W-SU": "RU",
   // WET
-  WET: "",
+  WET: "WET",
   // Zulu
-  Zulu: "",
+  Zulu: "Zulu",
 };

package/src/constants/index.ts

@@ -1,2 +1,4 @@
-export * from './config';
-export * from './events';
+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/fingerprint.ts

@@ -0,0 +1,9 @@
+import { load } from "@fingerprintjs/fingerprintjs";
+
+export class Fingerprint {
+  static async getVisitorId(): Promise<string> {
+    const fp = await load();
+    const { visitorId } = await fp.get();
+    return visitorId;
+  }
+}

package/src/lib/index.ts

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

package/src/lib/queue.ts

@@ -0,0 +1,310 @@
+import fetch from "fetch-retry";
+import isNetworkError from "is-network-error";
+import { RequestEvent } from "../types";
+import {
+  clampNumber,
+  getActionDescriptor,
+  millisecondsToSecond,
+  toDateHourMinute,
+} from "./utils";
+import { Fingerprint } from "./fingerprint";
+
+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 * 30; // 1 MINUTE
+const MAX_FLUSH_INTERVAL = 1_000 * 300; // 5 MINUTES
+const MIN_FLUSH_INTERVAL = 1_000 * 10; // 10 SECONDS
+
+export class EventQueue {
+  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;
+  private payloadHashes: Set<string> = new Set();
+
+  constructor(writeKey: string, options: Options) {
+    options = options || {};
+
+    this.queue = [];
+    this.writeKey = writeKey;
+    this.url = options.url;
+    this.retryCount = clampNumber(
+      options.retryCount || DEFAULT_RETRY,
+      MAX_RETRY,
+      MIN_RETRY
+    );
+    this.flushAt = clampNumber(
+      options.flushAt || DEFAULT_FLUSH_AT,
+      MAX_FLUSH_AT,
+      MIN_FLUSH_AT
+    );
+    this.maxQueueSize = clampNumber(
+      options.maxQueueSize || DEFAULT_QUEUE_SIZE,
+      MAX_QUEUE_SIZE,
+      MIN_QUEUE_SIZE
+    );
+    this.flushInterval = clampNumber(
+      options.flushInterval || DEFAULT_FLUSH_INTERVAL,
+      MAX_FLUSH_INTERVAL,
+      MIN_FLUSH_INTERVAL
+    );
+    this.flushed = true;
+    this.errorHandler = options.errorHandler;
+    this.pendingFlush = null;
+    this.timer = null;
+
+    this.onPageLeave(async (isAccessible: boolean) => {
+      if (isAccessible === false) {
+        await this.flush();
+      }
+    });
+  }
+
+  //#region Public functions
+  async enqueue(message: RequestEvent, callback?: (...args: any) => void) {
+    callback = callback || noop;
+
+    // check if the message already exists
+    if (await this.checkDuplicate(message)) {
+      console.warn(
+        `Event already enqueued, try again after ${millisecondsToSecond(
+          this.flushInterval
+        )} seconds.`
+      );
+      return;
+    }
+
+    this.queue.push({ message, callback });
+
+    console.log(
+      `Event enqueued: ${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);
+    this.payloadHashes.clear();
+    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 Fingerprint.getVisitorId(),
+      },
+    };
+
+    return (this.pendingFlush = sdkFetch(`${this.url}`, {
+      method: "POST",
+      body: JSON.stringify(data),
+      keepalive: true,
+      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;
+      }));
+  }
+
+  //#region Utility functions
+  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 async checkDuplicate(newMessage: RequestEvent) {
+    // check if exists a message with identical payload within 1 minute
+    const formattedTimestamp = toDateHourMinute(new Date(newMessage.timestamp));
+    newMessage.timestamp = formattedTimestamp;
+
+    const hash = await this.hashPayload(newMessage);
+    if (this.payloadHashes.has(hash)) {
+      return true;
+    }
+    this.payloadHashes.add(hash);
+    return false;
+  }
+
+  private async hashPayload(payload: RequestEvent, algo = "SHA-1") {
+    return Array.from(
+      new Uint8Array(
+        await crypto.subtle.digest(
+          algo,
+          new TextEncoder().encode(JSON.stringify(payload))
+        )
+      ),
+      (byte) => byte.toString(16).padStart(2, "0")
+    ).join("");
+  }
+
+  private onPageLeave = (callback: (isAccessible: boolean) => void) => {
+    // To ensure the callback is only called once even if more than one events
+    // are fired at once.
+    let pageLeft = false;
+    let isAccessible = false;
+
+    function handleOnLeave() {
+      if (pageLeft) {
+        return;
+      }
+
+      pageLeft = true;
+
+      callback(isAccessible);
+
+      // Reset pageLeft on the next tick
+      // to ensure callback executes for other listeners
+      // when closing an inactive browser tab.
+      setTimeout(() => {
+        pageLeft = false;
+      }, 0);
+    }
+
+    // Catches the unloading of the page (e.g., closing the tab or navigating away).
+    // Includes user actions like clicking a link, entering a new URL,
+    // refreshing the page, or closing the browser tab
+    // Note that 'pagehide' is not supported in IE.
+    // So, this is a fallback.
+    (globalThis as typeof window).addEventListener("beforeunload", () => {
+      isAccessible = false;
+      handleOnLeave();
+    });
+
+    (globalThis as typeof window).addEventListener("blur", () => {
+      isAccessible = true;
+      handleOnLeave();
+    });
+
+    (globalThis as typeof window).addEventListener("focus", () => {
+      pageLeft = false;
+    });
+
+    // Catches the page being hidden, including scenarios like closing the tab.
+    document.addEventListener("pagehide", () => {
+      isAccessible = document.visibilityState === "hidden";
+      handleOnLeave();
+    });
+
+    // Catches visibility changes, such as switching tabs or minimizing the browser.
+    document.addEventListener("visibilitychange", () => {
+      isAccessible = true;
+      if (document.visibilityState === "hidden") {
+        handleOnLeave();
+      } else {
+        pageLeft = false;
+      }
+    });
+  };
+}

package/src/lib/session-storage.ts

@@ -0,0 +1,53 @@
+export class SessionStorage {
+  private readonly json_prefix = "__json=";
+
+  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 get(key: string): string | boolean | Record<any, any> | null {
+    const value = sessionStorage.getItem(key);
+
+    if (!value || typeof value !== "string") return null;
+    if (["null", "undefined"].some((item) => item == value)) return null;
+
+    if (value.startsWith(this.json_prefix)) {
+      try {
+        return JSON.parse(value.slice(7));
+      } catch (error) {
+        console.error(
+          "[FORMO_ERROR] SessionStorage failed to parse JSON",
+          error
+        );
+        return null;
+      }
+    }
+
+    if (["true", "false"].some((item) => item == value)) {
+      return JSON.parse(value);
+    }
+
+    return value;
+  }
+
+  public removeMatch(pattern: RegExp): void {
+    for (const key in sessionStorage) {
+      if (pattern.test(key)) {
+        this.remove(key);
+      }
+    }
+  }
+
+  public remove(key: string): void {
+    sessionStorage.removeItem(key);
+  }
+
+  public clear(): void {
+    sessionStorage.clear();
+  }
+}
+
+export default new SessionStorage();

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")
@@ -24,3 +26,32 @@ export function toSnakeCase(obj: any, omitKeys: string[] = []) {
 
   return convert(obj);
 }
+
+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);
+
+export const millisecondsToSecond = (milliseconds: number): number =>
+  Math.ceil(milliseconds / 1_000);
+
+export const toDateHourMinute = (date: Date) =>
+  date.getUTCFullYear() +
+  "-" +
+  ("0" + (date.getUTCMonth() + 1)).slice(-2) +
+  "-" +
+  ("0" + date.getUTCDate()).slice(-2) +
+  " " +
+  ("0" + date.getUTCHours()).slice(-2) +
+  ":" +
+  ("0" + date.getUTCMinutes()).slice(-2);
+
+export const clampNumber = (value: number, max: number, min: number) => {
+  return Math.min(Math.max(value, min), max);
+};
+
+export const getActionDescriptor = (action: string, payload: any): string => {
+  return `${action}${payload?.status ? ` ${payload?.status}` : ""}`;
+};

package/src/types/base.ts

@@ -1,22 +1,29 @@
 import { EIP1193Provider } from "./provider";
 
 // Decimal chain ID
-export type ChainID = number
+export type ChainID = number;
 
 // Address (EVM, Solana, etc.)
-export type Address = string
+export type Address = string;
 
 export interface Options {
   provider?: EIP1193Provider;
+  trackLocalhost?: boolean;
+
+  flushAt?: number;
+  flushInterval?: number;
+  retryCount?: number;
+  maxQueueSize?: number;
 }
 
 export interface FormoAnalyticsProviderProps {
-  apiKey: string;
+  writeKey: string;
   options?: Options;
   disabled?: boolean;
   children: React.ReactNode;
 }
 
 export interface Config {
-  apiKey: string;
-}
+  writeKey: string;
+  trackLocalhost?: boolean;
+}

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",
+}