@formo/analytics-react-native 0.1.0

package/src/types/base.ts

@@ -0,0 +1,287 @@
+import { ReactNode } from "react";
+import { LogLevel } from "../lib/logger";
+import {
+  IFormoEventContext,
+  IFormoEventProperties,
+  SignatureStatus,
+  TransactionStatus,
+} from "./events";
+
+export type Nullable<T> = T | null;
+// Decimal chain ID
+export type ChainID = number;
+
+// Address (EVM, Solana, etc.)
+export type Address = string;
+
+export type ValidInputTypes = Uint8Array | bigint | string | number | boolean;
+
+export interface IFormoAnalytics {
+  screen(
+    name: string,
+    category?: string,
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void>;
+  reset(): void;
+  cleanup(): Promise<void>;
+  detect(
+    params: { rdns: string; providerName: string },
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void>;
+  connect(
+    params: { chainId: ChainID; address: Address },
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void>;
+  disconnect(
+    params?: { chainId?: ChainID; address?: Address },
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void>;
+  chain(
+    params: { chainId: ChainID; address?: Address },
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void>;
+  signature(
+    params: {
+      status: SignatureStatus;
+      chainId?: ChainID;
+      address: Address;
+      message: string;
+      signatureHash?: string;
+    },
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void>;
+  transaction(
+    params: {
+      status: TransactionStatus;
+      chainId: ChainID;
+      address: Address;
+      data?: string;
+      to?: string;
+      value?: string;
+      transactionHash?: string;
+      function_name?: string;
+      function_args?: Record<string, unknown>;
+    },
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void>;
+  identify(
+    params: {
+      address: Address;
+      providerName?: string;
+      userId?: string;
+      rdns?: string;
+    },
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void>;
+  track(
+    event: string,
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void>;
+
+  // Event flushing
+  flush(): Promise<void>;
+
+  // Traffic source management
+  setTrafficSourceFromUrl(url: string): void;
+
+  // Consent management methods
+  optOutTracking(): void;
+  optInTracking(): void;
+  hasOptedOutTracking(): boolean;
+}
+
+export interface Config {
+  writeKey: string;
+}
+
+/**
+ * Configuration options for controlling tracking exclusions
+ */
+export interface TrackingOptions {
+  excludeChains?: ChainID[];
+}
+
+/**
+ * Configuration options for controlling wallet event autocapture
+ * All events are enabled by default unless explicitly set to false
+ */
+export interface AutocaptureOptions {
+  /**
+   * Track wallet connect events
+   * @default true
+   */
+  connect?: boolean;
+
+  /**
+   * Track wallet disconnect events
+   * @default true
+   */
+  disconnect?: boolean;
+
+  /**
+   * Track wallet signature events (personal_sign, eth_signTypedData_v4)
+   * @default true
+   */
+  signature?: boolean;
+
+  /**
+   * Track wallet transaction events (eth_sendTransaction)
+   * @default true
+   */
+  transaction?: boolean;
+
+  /**
+   * Track wallet chain change events
+   * @default true
+   */
+  chain?: boolean;
+
+  /**
+   * Track application lifecycle events (installed, updated, opened, backgrounded)
+   * @default true
+   */
+  lifecycle?: boolean;
+}
+
+/**
+ * Configuration options for Wagmi integration
+ * Allows the SDK to hook into Wagmi v2 wallet events
+ */
+export interface WagmiOptions {
+  /**
+   * Wagmi config instance from createConfig()
+   * The SDK will subscribe to this config's state changes to track wallet events
+   */
+  config: any;
+
+  /**
+   * Optional QueryClient instance from @tanstack/react-query
+   * Required for tracking signature and transaction events via mutation cache
+   * If not provided, only connection/disconnection/chain events will be tracked
+   */
+  queryClient?: any;
+}
+
+/**
+ * App information for context enrichment
+ */
+export interface AppInfo {
+  /**
+   * App name
+   */
+  name?: string;
+
+  /**
+   * App version
+   */
+  version?: string;
+
+  /**
+   * App build number
+   */
+  build?: string;
+
+  /**
+   * Bundle/package identifier
+   */
+  bundleId?: string;
+}
+
+/**
+ * Configuration options for custom referral query parameter parsing
+ */
+export interface ReferralOptions {
+  /**
+   * Custom query parameter names to check for referral codes
+   * These are checked in addition to the defaults: ref, referral, refcode, referrer_code
+   */
+  queryParams?: string[];
+  /**
+   * Path pattern for extracting referral codes from URL paths
+   */
+  pathPattern?: string;
+}
+
+export interface Options {
+  tracking?: boolean | TrackingOptions;
+  /**
+   * Control wallet event autocapture
+   * - `false`: Disable all wallet autocapture
+   * - `true`: Enable all wallet events (default)
+   * - `AutocaptureOptions`: Granular control over specific events
+   * @default true
+   */
+  autocapture?: boolean | AutocaptureOptions;
+  /**
+   * Wagmi integration configuration
+   * When provided, the SDK will hook into Wagmi's event system
+   * @requires wagmi@>=2.0.0
+   * @requires @tanstack/react-query@>=5.0.0 (for mutation tracking)
+   */
+  wagmi?: WagmiOptions;
+  /**
+   * Custom API host for sending events
+   */
+  apiHost?: string;
+  flushAt?: number;
+  flushInterval?: number;
+  retryCount?: number;
+  maxQueueSize?: number;
+  logger?: {
+    enabled?: boolean;
+    levels?: LogLevel[];
+  };
+  /**
+   * App information for context enrichment
+   */
+  app?: AppInfo;
+  /**
+   * Custom referral query parameter configuration
+   */
+  referral?: ReferralOptions;
+  /**
+   * Global error handler for SDK errors
+   */
+  errorHandler?: (err: Error) => void;
+  ready?: (formo: IFormoAnalytics) => void;
+}
+
+export interface FormoAnalyticsProviderProps {
+  writeKey: string;
+  options?: Options;
+  disabled?: boolean;
+  /**
+   * AsyncStorage instance from @react-native-async-storage/async-storage
+   * Required for persistent storage
+   */
+  asyncStorage?: import("../lib/storage").AsyncStorageInterface;
+  /**
+   * Callback when SDK is ready
+   * Note: Use useCallback to avoid re-initialization on every render
+   */
+  onReady?: (sdk: IFormoAnalytics) => void;
+  /**
+   * Callback when SDK initialization fails
+   * Note: Use useCallback to avoid re-initialization on every render
+   */
+  onError?: (error: Error) => void;
+  children: ReactNode;
+}

package/src/types/events.ts

@@ -0,0 +1,140 @@
+import { Address, ChainID, Nullable } from "./base";
+import { TEventChannel, TEventType } from "../constants";
+
+export type AnonymousID = string;
+
+export interface ICommonProperties {
+  anonymous_id: AnonymousID;
+  user_id: Nullable<string>;
+  address: Nullable<string>;
+  type: TEventType;
+  channel: TEventChannel;
+  version: string;
+  original_timestamp: string;
+  event?: Nullable<string>;
+}
+
+export type IFormoEventProperties = Record<string, unknown>;
+export type IFormoEventContext = Record<string, unknown>;
+
+export type UTMParameters = {
+  utm_source: string;
+  utm_medium: string;
+  utm_campaign: string;
+  utm_term: string;
+  utm_content: string;
+};
+
+export type ITrafficSource = UTMParameters & {
+  ref: string;
+  referrer: string;
+};
+
+export interface IFormoEvent extends ICommonProperties {
+  context: Nullable<IFormoEventContext>;
+  properties: Nullable<IFormoEventProperties>;
+}
+
+export type IFormoEventPayload = IFormoEvent & {
+  message_id: string;
+};
+
+//#region Specific Event Types
+export interface ScreenAPIEvent {
+  type: "screen";
+  name: string;
+  category?: string;
+}
+
+export interface DetectAPIEvent {
+  type: "detect";
+  providerName: string;
+  rdns: string;
+}
+
+export interface IdentifyAPIEvent {
+  type: "identify";
+  address: string;
+  providerName: string;
+  rdns: string;
+  userId?: Nullable<string>;
+}
+
+export interface ChainAPIEvent {
+  type: "chain";
+  chainId: ChainID;
+  address: Address;
+}
+
+export interface TransactionAPIEvent {
+  type: "transaction";
+  status: TransactionStatus;
+  chainId: ChainID;
+  address: Address;
+  data?: string;
+  to?: string;
+  value?: string;
+  transactionHash?: string;
+  function_name?: string;
+  function_args?: Record<string, unknown>;
+}
+
+export interface SignatureAPIEvent {
+  type: "signature";
+  status: SignatureStatus;
+  chainId?: ChainID;
+  address: Address;
+  message: string;
+  signatureHash?: string;
+}
+
+export interface ConnectAPIEvent {
+  type: "connect";
+  chainId: ChainID;
+  address: Address;
+}
+
+export interface DisconnectAPIEvent {
+  type: "disconnect";
+  chainId?: ChainID;
+  address?: Address;
+}
+
+export interface TrackAPIEvent {
+  type: "track";
+  event: string;
+  volume?: number;
+  revenue?: number;
+  currency?: string;
+  points?: number;
+}
+
+export type APIEvent = {
+  properties?: IFormoEventProperties;
+  context?: IFormoEventContext;
+  callback?: (...args: unknown[]) => void;
+} & (
+  | ScreenAPIEvent
+  | DetectAPIEvent
+  | IdentifyAPIEvent
+  | ChainAPIEvent
+  | TransactionAPIEvent
+  | SignatureAPIEvent
+  | ConnectAPIEvent
+  | DisconnectAPIEvent
+  | TrackAPIEvent
+);
+
+export enum SignatureStatus {
+  REQUESTED = "requested",
+  REJECTED = "rejected",
+  CONFIRMED = "confirmed",
+}
+
+export enum TransactionStatus {
+  STARTED = "started",
+  REJECTED = "rejected",
+  BROADCASTED = "broadcasted",
+  CONFIRMED = "confirmed",
+  REVERTED = "reverted",
+}

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from "./base";
+export * from "./events";

package/src/utils/address.ts

@@ -0,0 +1,84 @@
+/**
+ * Address validation and checksum utilities
+ *
+ * Uses ethereum-cryptography for proper EIP-55 checksum computation
+ */
+
+import { keccak256 } from "ethereum-cryptography/keccak.js";
+import { utf8ToBytes } from "ethereum-cryptography/utils.js";
+
+/**
+ * Convert Uint8Array to hex string
+ */
+function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Check if a string is a valid Ethereum address
+ */
+export function isValidAddress(address: string): boolean {
+  if (!address) return false;
+  if (typeof address !== "string") return false;
+
+  // Check if it matches basic hex address format
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+
+/**
+ * Convert address to EIP-55 checksum format
+ *
+ * Uses keccak256 from ethereum-cryptography for correct checksumming
+ * See: https://eips.ethereum.org/EIPS/eip-55
+ */
+export function toChecksumAddress(address: string): string {
+  if (!isValidAddress(address)) {
+    return address;
+  }
+
+  const lowercaseAddress = address.toLowerCase().replace("0x", "");
+  const hash = toHex(keccak256(utf8ToBytes(lowercaseAddress)));
+
+  let checksumAddress = "0x";
+
+  for (let i = 0; i < lowercaseAddress.length; i++) {
+    const char = lowercaseAddress[i];
+    if (char && parseInt(hash[i] || "0", 16) >= 8) {
+      checksumAddress += char.toUpperCase();
+    } else {
+      checksumAddress += char;
+    }
+  }
+
+  return checksumAddress;
+}
+
+/**
+ * Get valid address or null
+ */
+export function getValidAddress(
+  address: string | undefined | null
+): string | null {
+  if (!address) return null;
+  const trimmed = typeof address === "string" ? address.trim() : address;
+  if (!isValidAddress(trimmed)) return null;
+  return trimmed;
+}
+
+/**
+ * Blocked addresses that should not emit events
+ * (zero address, dead address)
+ */
+const BLOCKED_ADDRESSES = new Set<string>([
+  "0x0000000000000000000000000000000000000000",
+  "0x000000000000000000000000000000000000dead",
+]);
+
+/**
+ * Check if address is in blocked list
+ */
+export function isBlockedAddress(address: string): boolean {
+  return BLOCKED_ADDRESSES.has(address.toLowerCase());
+}

package/src/utils/hash.ts

@@ -0,0 +1,23 @@
+import { sha256 } from "ethereum-cryptography/sha256";
+import { utf8ToBytes, bytesToHex } from "ethereum-cryptography/utils";
+
+/**
+ * Generate a SHA-256 hash for event deduplication
+ * Returns full 64 hex chars to match web SDK format
+ */
+export async function hash(input: string): Promise<string> {
+  const bytes = utf8ToBytes(input);
+  const hashBytes = sha256(bytes);
+  return bytesToHex(hashBytes);
+}
+
+/**
+ * Generate a UUID v4
+ */
+export function generateUUID(): string {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === "x" ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}

package/src/utils/helpers.ts

@@ -0,0 +1,139 @@
+/**
+ * Clamp a number between min and max values
+ */
+export function clampNumber(value: number, max: number, min: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Check if value is undefined
+ */
+export function isUndefined(value: unknown): value is undefined {
+  return value === undefined;
+}
+
+/**
+ * Convert a camelCase/PascalCase string to snake_case
+ * Handles consecutive uppercase letters (acronyms) correctly:
+ * - "userID" -> "user_id"
+ * - "XMLParser" -> "xml_parser"
+ * - "getHTTPResponse" -> "get_http_response"
+ */
+function camelToSnake(str: string): string {
+  return str
+    // Insert underscore before sequences of uppercase followed by lowercase (e.g., "XMLParser" -> "XML_Parser")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    // Insert underscore before single uppercase preceded by lowercase (e.g., "userID" -> "user_ID")
+    .replace(/([a-z\d])([A-Z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+/**
+ * Check if value is a plain object (not Date, Map, Set, RegExp, etc.)
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Convert object keys to snake_case (recursively handles nested objects and arrays)
+ * Preserves Date, Map, Set, RegExp, and other built-in objects unchanged
+ */
+export function toSnakeCase<T extends Record<string, unknown>>(obj: T): T {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    const snakeKey = camelToSnake(key);
+
+    if (Array.isArray(value)) {
+      // Recursively convert plain objects inside arrays
+      result[snakeKey] = value.map((item) =>
+        isPlainObject(item) ? toSnakeCase(item) : item
+      );
+    } else if (isPlainObject(value)) {
+      result[snakeKey] = toSnakeCase(value);
+    } else {
+      // Preserve Date, Map, Set, RegExp, and other built-in objects unchanged
+      result[snakeKey] = value;
+    }
+  }
+
+  return result as T;
+}
+
+/**
+ * Deep merge two objects
+ */
+export function mergeDeepRight<T extends Record<string, unknown>>(
+  target: T,
+  source: Partial<T>
+): T {
+  const output = { ...target };
+
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const sourceValue = source[key];
+      const targetValue = output[key];
+
+      if (
+        sourceValue !== null &&
+        typeof sourceValue === "object" &&
+        !Array.isArray(sourceValue) &&
+        targetValue !== null &&
+        typeof targetValue === "object" &&
+        !Array.isArray(targetValue)
+      ) {
+        output[key] = mergeDeepRight(
+          targetValue as Record<string, unknown>,
+          sourceValue as Record<string, unknown>
+        ) as T[Extract<keyof T, string>];
+      } else if (sourceValue !== undefined) {
+        output[key] = sourceValue as T[Extract<keyof T, string>];
+      }
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Get action descriptor for logging
+ */
+export function getActionDescriptor(
+  type: string,
+  properties?: Record<string, unknown> | null
+): string {
+  if (type === "track" && properties?.event) {
+    return `track:${properties.event}`;
+  }
+  if (type === "screen" && properties?.name) {
+    return `screen:${properties.name}`;
+  }
+  return type;
+}
+
+/**
+ * Check if error is a network error
+ */
+export function isNetworkError(error: unknown): boolean {
+  if (!error) return false;
+
+  const message = error instanceof Error ? error.message : String(error);
+  const networkErrorMessages = [
+    "Network request failed",
+    "Failed to fetch",
+    "Network Error",
+    "timeout",
+    "ETIMEDOUT",
+    "ECONNREFUSED",
+    "ENOTFOUND",
+  ];
+
+  return networkErrorMessages.some((msg) =>
+    message.toLowerCase().includes(msg.toLowerCase())
+  );
+}

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export * from "./address";
+export * from "./hash";
+export * from "./timestamp";
+export * from "./helpers";
+export * from "./trafficSource";

package/src/utils/timestamp.ts

@@ -0,0 +1,25 @@
+/**
+ * Get current time in ISO format
+ */
+export function getCurrentTimeFormatted(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Format date to YYYY-MM-DD HH:mm format for hashing
+ */
+export function toDateHourMinute(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  return `${year}-${month}-${day} ${hours}:${minutes}`;
+}
+
+/**
+ * Convert milliseconds to seconds
+ */
+export function millisecondsToSecond(ms: number): number {
+  return Math.floor(ms / 1000);
+}