@formo/analytics-react-native 0.1.0

package/src/lib/event/EventManager.ts

@@ -0,0 +1,50 @@
+import { Address, APIEvent, Options } from "../../types";
+import { logger } from "../logger";
+import { EventFactory } from "./EventFactory";
+import { IEventFactory, IEventManager, IEventQueue } from "./types";
+import { isBlockedAddress } from "../../utils/address";
+
+/**
+ * Event manager for React Native SDK
+ * Generates valid event payloads and queues them for processing
+ */
+class EventManager implements IEventManager {
+  eventQueue: IEventQueue;
+  eventFactory: IEventFactory;
+
+  constructor(eventQueue: IEventQueue, options?: Options) {
+    this.eventQueue = eventQueue;
+    this.eventFactory = new EventFactory(options);
+  }
+
+  /**
+   * Add event to queue
+   */
+  async addEvent(
+    event: APIEvent,
+    address?: Address,
+    userId?: string
+  ): Promise<void> {
+    const { callback, ..._event } = event;
+    const formoEvent = await this.eventFactory.create(_event, address, userId);
+
+    // Check if the final event has a blocked address
+    if (formoEvent.address && isBlockedAddress(formoEvent.address)) {
+      logger.warn(
+        `Event blocked: Address ${formoEvent.address} is in the blocked list`
+      );
+      return;
+    }
+
+    await this.eventQueue.enqueue(formoEvent, (err, _, data) => {
+      if (err) {
+        logger.error("Error sending events:", err);
+      } else {
+        logger.info(`Events sent successfully: ${(data as unknown[])?.length ?? 0} events`);
+      }
+      callback?.(err, _, data);
+    });
+  }
+}
+
+export { EventManager };

package/src/lib/event/EventQueue.ts

@@ -0,0 +1,371 @@
+import { AppState, AppStateStatus } from "react-native";
+import { IFormoEvent, IFormoEventPayload } from "../../types";
+import { EVENTS_API_REQUEST_HEADER } from "../../constants";
+import {
+  clampNumber,
+  getActionDescriptor,
+  millisecondsToSecond,
+  isNetworkError,
+} from "../../utils";
+import { hash } from "../../utils/hash";
+import { toDateHourMinute } from "../../utils/timestamp";
+import { logger } from "../logger";
+import { IEventQueue } from "./types";
+
+type QueueItem = {
+  message: IFormoEventPayload;
+  callback: (...args: unknown[]) => void;
+  hash: string;
+};
+
+type IFormoEventFlushPayload = IFormoEventPayload & {
+  sent_at: string;
+};
+
+interface Options {
+  apiHost: string;
+  flushAt?: number;
+  flushInterval?: number;
+  retryCount?: number;
+  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; // 30 seconds
+const MAX_FLUSH_INTERVAL = 1_000 * 300; // 5 minutes
+const MIN_FLUSH_INTERVAL = 1_000 * 10; // 10 seconds
+
+const noop = () => {};
+
+/**
+ * Event queue for React Native
+ * Handles batching, flushing, and retries with app lifecycle awareness
+ */
+export class EventQueue implements IEventQueue {
+  private writeKey: string;
+  private apiHost: string;
+  private queue: QueueItem[] = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private flushAt: number;
+  private flushIntervalMs: number;
+  private maxQueueSize: number;
+  private retryCount: number;
+  private payloadHashes: Set<string> = new Set();
+  private flushMutex: Promise<void> = Promise.resolve();
+  private appStateSubscription: { remove: () => void } | null = null;
+
+  constructor(writeKey: string, options: Options) {
+    this.writeKey = writeKey;
+    this.apiHost = options.apiHost;
+    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.flushIntervalMs = clampNumber(
+      options.flushInterval || DEFAULT_FLUSH_INTERVAL,
+      MAX_FLUSH_INTERVAL,
+      MIN_FLUSH_INTERVAL
+    );
+    // Set up app state listener for React Native
+    this.setupAppStateListener();
+  }
+
+  /**
+   * Set up listener for app state changes
+   * Flush events when app goes to background
+   */
+  private setupAppStateListener(): void {
+    this.appStateSubscription = AppState.addEventListener(
+      "change",
+      this.handleAppStateChange.bind(this)
+    );
+  }
+
+  /**
+   * Handle app state changes
+   */
+  private handleAppStateChange(nextAppState: AppStateStatus): void {
+    // Flush when app goes to background or becomes inactive
+    if (nextAppState === "background" || nextAppState === "inactive") {
+      logger.debug("EventQueue: App going to background, flushing events");
+      this.flush().catch((error) => {
+        logger.error("EventQueue: Failed to flush on background", error);
+      });
+    }
+  }
+
+  /**
+   * Generate message ID for deduplication
+   */
+  private async generateMessageId(event: IFormoEvent): Promise<string> {
+    const formattedTimestamp = toDateHourMinute(
+      new Date(event.original_timestamp)
+    );
+    const eventForHashing = { ...event, original_timestamp: formattedTimestamp };
+    const eventString = JSON.stringify(eventForHashing);
+    return hash(eventString);
+  }
+
+  /**
+   * Check if event is a duplicate
+   */
+  private isDuplicate(eventId: string): boolean {
+    if (this.payloadHashes.has(eventId)) return true;
+    this.payloadHashes.add(eventId);
+    return false;
+  }
+
+  /**
+   * Add event to queue
+   */
+  async enqueue(
+    event: IFormoEvent,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void> {
+    callback = callback || noop;
+
+    const message_id = await this.generateMessageId(event);
+
+    // Check for duplicate
+    if (this.isDuplicate(message_id)) {
+      logger.warn(
+        `Event already enqueued, try again after ${millisecondsToSecond(
+          this.flushIntervalMs
+        )} seconds.`
+      );
+      return;
+    }
+
+    this.queue.push({
+      message: { ...event, message_id },
+      callback,
+      hash: message_id,
+    });
+
+    logger.log(
+      `Event enqueued: ${getActionDescriptor(event.type, event.properties)}`
+    );
+
+    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) {
+      // Clear timer to prevent double flush
+      if (this.timer) {
+        clearTimeout(this.timer);
+        this.timer = null;
+      }
+      // Flush uses internal mutex to serialize operations
+      this.flush().catch((error) => {
+        logger.error("EventQueue: Failed to flush on threshold", error);
+      });
+      return;
+    }
+
+    if (this.flushIntervalMs && !this.timer) {
+      this.timer = setTimeout(this.flush.bind(this), this.flushIntervalMs);
+    }
+  }
+
+  /**
+   * Flush events to API
+   * Uses a mutex to ensure only one flush operation runs at a time,
+   * preventing race conditions with re-queued items on failure.
+   */
+  async flush(callback?: (...args: unknown[]) => void): Promise<void> {
+    callback = callback || noop;
+
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+
+    // Use mutex to serialize flush operations and prevent race conditions
+    const previousMutex = this.flushMutex;
+    let resolveMutex: () => void;
+    this.flushMutex = new Promise((resolve) => {
+      resolveMutex = resolve;
+    });
+
+    try {
+      // Wait for any previous flush to complete
+      await previousMutex;
+
+      if (!this.queue.length) {
+        callback();
+        return;
+      }
+
+      const items = this.queue.splice(0, this.flushAt);
+
+      const sentAt = new Date().toISOString();
+      const data: IFormoEventFlushPayload[] = items.map((item) => ({
+        ...item.message,
+        sent_at: sentAt,
+      }));
+
+      const done = (err?: Error) => {
+        items.forEach(({ message, callback: itemCallback }) =>
+          itemCallback(err, message, data)
+        );
+        callback!(err, data);
+      };
+
+      try {
+        await this.sendWithRetry(data);
+        // Only remove hashes after successful send
+        items.forEach((item) => this.payloadHashes.delete(item.hash));
+        done();
+        logger.info(`Events sent successfully: ${data.length} events`);
+      } catch (err) {
+        // Re-add items to the front of the queue for retry on next flush
+        // Note: We intentionally keep hashes in payloadHashes to prevent duplicate
+        // events from being enqueued while these items are pending retry.
+        this.queue.unshift(...items);
+        done(err as Error);
+        logger.error("Error sending events, re-queued for retry:", err);
+        throw err;
+      }
+    } finally {
+      resolveMutex!();
+    }
+  }
+
+  /**
+   * Send events with retry logic
+   */
+  private async sendWithRetry(
+    data: IFormoEventFlushPayload[],
+    attempt = 0
+  ): Promise<void> {
+    try {
+      const response = await fetch(this.apiHost, {
+        method: "POST",
+        headers: EVENTS_API_REQUEST_HEADER(this.writeKey),
+        body: JSON.stringify(data),
+      });
+
+      if (!response.ok) {
+        const shouldRetry = this.shouldRetry(response.status);
+        if (shouldRetry && attempt < this.retryCount) {
+          const delay = Math.pow(2, attempt) * 1000;
+          await new Promise<void>((resolve) => setTimeout(() => resolve(), delay));
+          return this.sendWithRetry(data, attempt + 1);
+        }
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+    } catch (error) {
+      if (isNetworkError(error) && attempt < this.retryCount) {
+        const delay = Math.pow(2, attempt) * 1000;
+        logger.warn(`Network error, retrying in ${delay}ms...`);
+        await new Promise<void>((resolve) => setTimeout(() => resolve(), delay));
+        return this.sendWithRetry(data, attempt + 1);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Check if error should be retried
+   */
+  private shouldRetry(status: number): boolean {
+    // Retry on server errors (5xx) and rate limiting (429)
+    return (status >= 500 && status <= 599) || status === 429;
+  }
+
+  /**
+   * Discard all pending events without sending them.
+   * Used when the user opts out of tracking to prevent queued events
+   * from being sent after consent is revoked.
+   */
+  public clear(): void {
+    this.queue = [];
+    this.payloadHashes.clear();
+
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+
+    logger.debug("EventQueue: Cleared all pending events");
+  }
+
+  /**
+   * Clean up resources, flushing any pending events first
+   */
+  public async cleanup(): Promise<void> {
+    // Flush all remaining queued events before teardown
+    // Loop until queue is empty since flush() only sends flushAt events per call
+    // Safety limit prevents infinite loops if flush silently fails
+    const maxAttempts = Math.ceil(this.queue.length / this.flushAt) + 3;
+    let attempts = 0;
+    const initialQueueLength = this.queue.length;
+
+    while (this.queue.length > 0 && attempts < maxAttempts) {
+      const queueLengthBefore = this.queue.length;
+      try {
+        await this.flush();
+      } catch (error) {
+        logger.error("EventQueue: Failed to flush during cleanup", error);
+        // Break on error to avoid infinite loop if flush keeps failing
+        break;
+      }
+
+      // If queue length didn't decrease, flush is silently failing
+      if (this.queue.length >= queueLengthBefore) {
+        logger.warn("EventQueue: Flush did not reduce queue size, aborting cleanup");
+        break;
+      }
+
+      attempts++;
+    }
+
+    if (attempts >= maxAttempts && this.queue.length > 0) {
+      logger.warn(
+        `EventQueue: Cleanup safety limit reached. Discarding ${this.queue.length} events.`
+      );
+      this.queue = [];
+      this.payloadHashes.clear();
+    }
+
+    if (initialQueueLength > 0) {
+      logger.debug(`EventQueue: Cleanup completed, flushed ${initialQueueLength - this.queue.length} events`);
+    }
+
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+
+    if (this.appStateSubscription) {
+      this.appStateSubscription.remove();
+      this.appStateSubscription = null;
+    }
+  }
+}

package/src/lib/event/index.ts

@@ -0,0 +1,4 @@
+export * from "./EventFactory";
+export * from "./EventManager";
+export * from "./EventQueue";
+export * from "./types";

package/src/lib/event/types.ts

@@ -0,0 +1,107 @@
+import {
+  Address,
+  APIEvent,
+  IFormoEvent,
+  IFormoEventContext,
+  IFormoEventProperties,
+  Nullable,
+  SignatureStatus,
+  TransactionStatus,
+  ChainID,
+} from "../../types";
+
+export interface IEventFactory {
+  create(
+    event: APIEvent,
+    address?: Address,
+    userId?: string
+  ): Promise<IFormoEvent>;
+
+  generateScreenEvent(
+    name: string,
+    category?: string,
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext
+  ): Promise<IFormoEvent>;
+
+  generateDetectWalletEvent(
+    providerName: string,
+    rdns: string,
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext
+  ): Promise<IFormoEvent>;
+
+  generateIdentifyEvent(
+    providerName: string,
+    rdns: string,
+    address: Nullable<Address>,
+    userId?: Nullable<string>,
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext
+  ): Promise<IFormoEvent>;
+
+  generateConnectEvent(
+    chainId: ChainID,
+    address: Address,
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext
+  ): Promise<IFormoEvent>;
+
+  generateDisconnectEvent(
+    chainId?: ChainID,
+    address?: Address,
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext
+  ): Promise<IFormoEvent>;
+
+  generateChainChangedEvent(
+    chainId: ChainID,
+    address: Address,
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext
+  ): Promise<IFormoEvent>;
+
+  generateSignatureEvent(
+    status: SignatureStatus,
+    chainId: ChainID | undefined,
+    address: Address,
+    message: string,
+    signatureHash?: string,
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext
+  ): Promise<IFormoEvent>;
+
+  generateTransactionEvent(
+    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
+  ): Promise<IFormoEvent>;
+
+  generateTrackEvent(
+    event: string,
+    properties?: IFormoEventProperties,
+    context?: IFormoEventContext
+  ): Promise<IFormoEvent>;
+}
+
+export interface IEventManager {
+  addEvent(event: APIEvent, address?: Address, userId?: string): Promise<void>;
+}
+
+export interface IEventQueue {
+  enqueue(
+    event: IFormoEvent,
+    callback?: (...args: unknown[]) => void
+  ): Promise<void>;
+  flush(callback?: (...args: unknown[]) => void): Promise<void>;
+  clear(): void;
+  cleanup(): Promise<void>;
+}