@formo/analytics 1.16.0 → 1.16.2

package/src/lib/event/EventFactory.ts

@@ -0,0 +1,263 @@
+import { UUID } from "crypto";
+import { COUNTRY_LIST } from "../../constants";
+import {
+  Address,
+  APIEvent,
+  ChainID,
+  SignatureStatus,
+  TransactionStatus,
+} from "../../types";
+import { logger } from "../logger";
+import { IEventFactory } from "./type";
+import { toChecksumAddress, toSnakeCase } from "../../utils";
+
+class EventFactory implements IEventFactory {
+  constructor() {}
+
+  private getLocation(): string | undefined {
+    try {
+      const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+      if (timezone in COUNTRY_LIST)
+        return COUNTRY_LIST[timezone as keyof typeof COUNTRY_LIST];
+      return timezone;
+    } catch (error) {
+      logger.error("Error resolving timezone:", error);
+      return "";
+    }
+  }
+
+  private getLanguage(): string {
+    try {
+      return (
+        (navigator.languages && navigator.languages.length
+          ? navigator.languages[0]
+          : navigator.language) || "en"
+      );
+    } catch (error) {
+      logger.error("Error resolving language:", error);
+      return "en";
+    }
+  }
+
+  private buildCommonProperties(
+    anonymous_id: UUID,
+    user_id: string | null,
+    address: string | null,
+    action: string
+  ) {
+    // common properties
+    return {
+      anonymous_id,
+      user_id,
+      address: address && toChecksumAddress(address),
+      timestamp: new Date().toISOString(),
+      action,
+      version: "1",
+    };
+  }
+
+  private buildCommonPayload() {
+    const url = new URL(window.location.href);
+
+    const location = this.getLocation();
+    const language = this.getLanguage();
+
+    // common properties
+    return {
+      "user-agent": window.navigator.userAgent,
+      href: url.href,
+      locale: language,
+      location,
+    };
+  }
+
+  generatePageEvent() {
+    const url = new URL(window.location.href);
+    const params = new URLSearchParams(url.search);
+    const pathname = window.location.pathname;
+    const hash = window.location.hash;
+
+    return {
+      pathname: pathname || url.pathname,
+      hash: hash || url.hash,
+      referrer: document.referrer,
+      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() || "",
+    };
+  }
+
+  generateConnectEvent(chainId: ChainID, address: Address) {
+    return {
+      chainId,
+      address,
+    };
+  }
+
+  generateDisconnectEvent(chainId: ChainID, address: Address) {
+    return {
+      chainId,
+      address,
+    };
+  }
+
+  generateDetectWalletEvent(providerName: string, rdns: string) {
+    return {
+      providerName,
+      rdns,
+    };
+  }
+
+  generateIdentifyEvent(
+    address: Address | null,
+    providerName: string,
+    rdns: string
+  ) {
+    return {
+      address,
+      providerName,
+      rdns,
+    };
+  }
+
+  generateChainChangedEvent(chainId: ChainID, address: Address) {
+    return {
+      chainId,
+      address,
+    };
+  }
+
+  generateSignatureEvent(
+    status: SignatureStatus,
+    chainId: ChainID,
+    address: Address,
+    message: string,
+    signatureHash: string
+  ) {
+    return {
+      status,
+      chainId,
+      address,
+      message,
+      signatureHash,
+    };
+  }
+
+  generateTransactionEvent(
+    status: TransactionStatus,
+    chainId: ChainID,
+    address: Address,
+    data: string,
+    to: string,
+    value: string,
+    transactionHash: string
+  ) {
+    return {
+      status,
+      chainId,
+      address,
+      data,
+      to,
+      value,
+      transactionHash,
+    };
+  }
+
+  generateCustomEvent(args: any) {
+    if (typeof args !== "object") {
+      logger.warn("Invalid event data");
+      return {};
+    }
+    const { action, ...rest } = args;
+
+    return {
+      ...rest,
+    };
+  }
+
+  create(
+    anonymous_id: UUID,
+    user_id: string | null,
+    address: string | null,
+    event: APIEvent
+  ) {
+    const commonProperties = this.buildCommonProperties(
+      anonymous_id,
+      user_id,
+      address,
+      event.action
+    );
+    const payload = this.buildCommonPayload();
+    let eventSpecificPayload = this.generateCustomEvent(event);
+    if (event.action === "page_hit") {
+      eventSpecificPayload = this.generatePageEvent();
+    }
+    if (event.action === "connect") {
+      eventSpecificPayload = this.generateConnectEvent(
+        event.chainId,
+        event.address
+      );
+    }
+    if (event.action === "disconnect") {
+      eventSpecificPayload = this.generateDisconnectEvent(
+        event.chainId,
+        event.address
+      );
+    }
+    if (event.action === "detect_wallet") {
+      eventSpecificPayload = this.generateDetectWalletEvent(
+        event.providerName,
+        event.rdns
+      );
+    }
+    if (event.action === "identify") {
+      eventSpecificPayload = this.generateIdentifyEvent(
+        event.address,
+        event.providerName,
+        event.rdns
+      );
+    }
+    if (event.action === "chain_changed") {
+      eventSpecificPayload = this.generateChainChangedEvent(
+        event.chainId,
+        event.address
+      );
+    }
+    if (event.action === "signature") {
+      eventSpecificPayload = this.generateSignatureEvent(
+        event.status,
+        event.chainId,
+        event.address,
+        event.message,
+        event.signatureHash
+      );
+    }
+    if (event.action === "transaction") {
+      eventSpecificPayload = this.generateTransactionEvent(
+        event.status,
+        event.chainId,
+        event.address,
+        event.data,
+        event.to,
+        event.value,
+        event.transactionHash
+      );
+    }
+
+    return toSnakeCase(
+      {
+        ...commonProperties,
+        payload: {
+          ...payload,
+          ...eventSpecificPayload,
+        },
+      },
+      ["user-agent"]
+    );
+  }
+}
+
+export { EventFactory };

package/src/lib/event/index.ts

@@ -0,0 +1,2 @@
+export * from "./EventFactory";
+export * from "./type";

package/src/lib/event/type.ts

@@ -0,0 +1,11 @@
+import { UUID } from "crypto";
+import { APIEvent, IFormoEvent } from "../../types";
+
+export interface IEventFactory {
+  create(
+    anonymous_id: UUID,
+    user_id: string | null,
+    address: string | null,
+    event: APIEvent
+  ): IFormoEvent;
+}

package/src/lib/index.ts

@@ -1,3 +1,4 @@
+export * from "./event";
 export * from "./logger";
 export * from "./queue";
 export * from "./storage";

package/src/lib/{logger.ts → logger/Logger.ts}

@@ -1,7 +1,7 @@
-export type LogLevel = "debug" | "info" | "warn" | "error" | "trace";
+import { ILogger, LogLevel } from "./type";
 
-export class Logger {
-  private static instance: Logger;
+export class Logger implements ILogger {
+  private static instance: ILogger;
   private enabledLevels: Set<LogLevel>;
   private enabled: boolean;
 
@@ -32,7 +32,7 @@ export class Logger {
   public static getInstance(config?: {
     enabled?: boolean;
     enabledLevels?: LogLevel[];
-  }): Logger {
+  }): ILogger {
     if (!Logger.instance) {
       Logger.instance = new Logger(
         config?.enabled ?? false,

package/src/lib/logger/index.ts

@@ -0,0 +1,2 @@
+export * from "./Logger";
+export * from "./type";

package/src/lib/logger/type.ts

@@ -0,0 +1,14 @@
+export interface ILogger {
+  setEnabledLevels(levels: LogLevel[]): void;
+  getEnabledLevels(): LogLevel[];
+  setEnabled(enabled: boolean): void;
+  isLoggingEnabled(): boolean;
+  log(...data: any[]): void;
+  info(...data: any[]): void;
+  debug(...data: any[]): void;
+  warn(...data: any[]): void;
+  error(...data: any[]): void;
+  trace(...data: any[]): void;
+}
+
+export type LogLevel = "debug" | "info" | "warn" | "error" | "trace";

package/src/lib/{queue.ts → queue/EventQueue.ts}

@@ -1,19 +1,20 @@
 import isNetworkError from "is-network-error";
-import { RequestEvent, RequestEventPayload } from "../types";
+import { IFormoEvent, IFormoEventPayload } from "../../types";
 import {
   clampNumber,
   getActionDescriptor,
   hash,
   millisecondsToSecond,
   toDateHourMinute,
-} from "../utils";
-import { logger } from "./logger";
-import { EVENTS_API_REQUEST_HEADER } from "../constants";
-import fetch from "./fetch";
+} from "../../utils";
+import { logger } from "../logger";
+import { EVENTS_API_REQUEST_HEADER } from "../../constants";
+import fetch from "../fetch";
+import { IEventQueue } from "./type";
 const noop = () => {};
 
 type QueueItem = {
-  message: RequestEventPayload;
+  message: IFormoEventPayload;
   callback: (...args: any) => any;
 };
 
@@ -43,7 +44,7 @@ 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 {
+export class EventQueue implements IEventQueue {
   private writeKey: string;
   private url: string;
   private queue: QueueItem[] = [];
@@ -96,7 +97,7 @@ export class EventQueue {
   }
 
   //#region Public functions
-  async enqueue(event: RequestEvent, callback?: (...args: any) => void) {
+  async enqueue(event: IFormoEvent, callback?: (...args: any) => void) {
     callback = callback || noop;
 
     const formattedTimestamp = toDateHourMinute(new Date(event.timestamp));
@@ -115,7 +116,10 @@ export class EventQueue {
       return;
     }
 
-    this.queue.push({ message: { ...event, timestamp: originTimestamp, id: eventId }, callback });
+    this.queue.push({
+      message: { ...event, timestamp: originTimestamp, id: eventId },
+      callback,
+    });
 
     logger.log(
       `Event enqueued: ${getActionDescriptor(event.action, event.payload)}`

package/src/lib/queue/index.ts

@@ -0,0 +1,2 @@
+export * from "./EventQueue";
+export * from "./type";

package/src/lib/queue/type.ts

@@ -0,0 +1,6 @@
+import { IFormoEvent } from "../../types";
+
+export interface IEventQueue {
+  enqueue(event: IFormoEvent, callback?: (...args: any) => void): Promise<void>;
+  flush(callback?: (...args: any) => void): Promise<any>;
+}

package/src/types/base.ts

@@ -7,6 +7,8 @@ export type ChainID = number;
 // Address (EVM, Solana, etc.)
 export type Address = string;
 
+export type ValidInputTypes = Uint8Array | bigint | string | number | boolean;
+
 export interface Options {
   provider?: EIP1193Provider;
   trackLocalhost?: boolean;

package/src/types/events.ts

@@ -1,6 +1,7 @@
 import { UUID } from "crypto";
+import { Address, ChainID } from "./base";
 
-export interface RequestEvent {
+export interface IFormoEvent {
   anonymous_id: UUID;
   user_id: string | null;
   action: string;
@@ -10,10 +11,60 @@ export interface RequestEvent {
   version: string;
 }
 
-export type RequestEventPayload = RequestEvent & {
+export type IFormoEventPayload = IFormoEvent & {
   id: string;
 };
 
+export type APIEvent =
+  | {
+      action: "page_hit";
+    }
+  | {
+      action: "detect_wallet";
+      providerName: string;
+      rdns: string;
+    }
+  | {
+      action: "identify";
+      address: string;
+      providerName: string;
+      rdns: string;
+      userId?: string;
+    }
+  | {
+      action: "chain_changed";
+      chainId: ChainID;
+      address: Address;
+    }
+  | {
+      action: "transaction";
+      status: TransactionStatus;
+      chainId: ChainID;
+      address: Address;
+      data: string;
+      to: string;
+      value: string;
+      transactionHash: string;
+    }
+  | {
+      action: "signature";
+      status: SignatureStatus;
+      chainId: ChainID;
+      address: Address;
+      message: string;
+      signatureHash: string;
+    }
+  | {
+      action: "disconnect";
+      chainId: ChainID;
+      address: Address;
+    }
+  | {
+      action: "connect";
+      chainId: ChainID;
+      address: Address;
+    };
+
 export enum SignatureStatus {
   REQUESTED = "requested",
   REJECTED = "rejected",

package/src/utils/address.ts

@@ -0,0 +1,43 @@
+import { Address } from "../types";
+import { keccak256 } from "ethereum-cryptography/keccak.js";
+import { utf8ToBytes } from "ethereum-cryptography/utils.js";
+import {
+  ensureIfUint8Array,
+  isAddress,
+  uint8ArrayToHexString,
+} from "../validators";
+import { isNullish } from "../validators/object";
+
+export const toChecksumAddress = (address: Address): string => {
+  if (!isAddress(address, false)) {
+    throw new Error("Invalid address " + address);
+  }
+
+  const lowerCaseAddress = address.toLowerCase().replace(/^0x/i, "");
+
+  const hash = uint8ArrayToHexString(
+    keccak256(ensureIfUint8Array(utf8ToBytes(lowerCaseAddress)))
+  );
+
+  if (
+    isNullish(hash) ||
+    hash ===
+      "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"
+  )
+    return ""; // // EIP-1052 if hash is equal to c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470, keccak was given empty data
+
+  let checksumAddress = "0x";
+
+  const addressHash = hash.replace(/^0x/i, "");
+
+  for (let i = 0; i < lowerCaseAddress.length; i += 1) {
+    // If ith character is 8 to f then make it uppercase
+    if (parseInt(addressHash[i], 16) > 7) {
+      checksumAddress += lowerCaseAddress[i].toUpperCase();
+    } else {
+      checksumAddress += lowerCaseAddress[i];
+    }
+  }
+
+  return checksumAddress;
+};

package/src/utils/base.ts

@@ -1,65 +1,3 @@
-import { UUID } from "crypto";
-
-const toSnake = (str: string) =>
-  str
-    .replace(/([a-z])([A-Z])/g, "$1_$2")
-    .replace(/[\s-]+/g, "_")
-    .toLowerCase();
-
-// Converts object keys to snake_case, omitting keys in the omitKeys array
-export function toSnakeCase(obj: any, omitKeys: string[] = []) {
-  const convert = (data: any): any => {
-    if (Array.isArray(data)) {
-      return data.map(convert); // Recursively handle array elements
-    } else if (data !== null && typeof data === "object") {
-      return Object.keys(data).reduce((acc: any, key) => {
-        // If the key is in omitKeys, keep it as it is
-        const resultKey = omitKeys.includes(key) ? key : toSnake(key);
-        acc[resultKey] = omitKeys.includes(key)
-          ? data[key]
-          : convert(data[key]);
-        return acc;
-      }, {});
-    }
-    return data;
-  };
-
-  return convert(obj);
-}
-
-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}` : ""}`;
 };
-
-export async function hash(input: string): Promise<string> {
-  const hashBuffer = await crypto.subtle.digest(
-    "SHA-256",
-    new TextEncoder().encode(input)
-  );
-  const byteArray = new Uint8Array(hashBuffer);
-  return Array.from(byteArray)
-    .map((byte) => byte.toString(16).padStart(2, "0"))
-    .join("");
-}
-
-export function generateNativeUUID(): UUID {
-  return crypto.randomUUID();
-}

package/src/utils/converter.ts

@@ -0,0 +1,44 @@
+const toSnake = (str: string) =>
+  str
+    .replace(/([a-z])([A-Z])/g, "$1_$2")
+    .replace(/[\s-]+/g, "_")
+    .toLowerCase();
+
+// Converts object keys to snake_case, omitting keys in the omitKeys array
+export function toSnakeCase(obj: any, omitKeys: string[] = []) {
+  const convert = (data: any): any => {
+    if (Array.isArray(data)) {
+      return data.map(convert); // Recursively handle array elements
+    } else if (data !== null && typeof data === "object") {
+      return Object.keys(data).reduce((acc: any, key) => {
+        // If the key is in omitKeys, keep it as it is
+        const resultKey = omitKeys.includes(key) ? key : toSnake(key);
+        acc[resultKey] = omitKeys.includes(key)
+          ? data[key]
+          : convert(data[key]);
+        return acc;
+      }, {});
+    }
+    return data;
+  };
+
+  return convert(obj);
+}
+
+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);
+};

package/src/utils/generate.ts

@@ -0,0 +1,16 @@
+import type { UUID } from "crypto";
+
+export async function hash(input: string): Promise<string> {
+  const hashBuffer = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(input)
+  );
+  const byteArray = new Uint8Array(hashBuffer);
+  return Array.from(byteArray)
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export function generateNativeUUID(): UUID {
+  return crypto.randomUUID();
+}

package/src/utils/index.ts

@@ -1,2 +1,4 @@
+export * from "./address";
 export * from "./base";
-export * from "./is";
+export * from "./converter";
+export * from "./generate";