@formo/analytics-react-native 0.1.0

package/src/lib/lifecycle/index.ts

@@ -0,0 +1,215 @@
+/**
+ * Application Lifecycle Event Manager
+ *
+ * Tracks application lifecycle events following the Segment/RudderStack spec:
+ * - Application Installed (first launch)
+ * - Application Updated (version/build changed)
+ * - Application Opened (every cold start + foreground return)
+ * - Application Backgrounded (app goes to background)
+ *
+ * Detection is JS-side using AsyncStorage (no native modules required).
+ */
+
+import { AppState, AppStateStatus, Linking } from "react-native";
+import { logger } from "../logger";
+import { storage, getStorageManager } from "../storage";
+import {
+  LOCAL_APP_VERSION_KEY,
+  LOCAL_APP_BUILD_KEY,
+} from "../../constants/storage";
+
+/** Interface for the analytics instance to avoid circular deps */
+interface IAnalyticsInstance {
+  track(event: string, properties?: Record<string, unknown>): Promise<void>;
+}
+
+/** App version info resolved from device or config */
+interface AppVersionInfo {
+  version: string;
+  build: string;
+}
+
+/**
+ * Resolves current app version and build from device info modules or options.
+ * Uses the same fallback chain as EventFactory.getDeviceInfo().
+ */
+async function resolveAppVersionInfo(
+  appOptions?: { version?: string; build?: string }
+): Promise<AppVersionInfo> {
+  // Use explicit options first
+  if (appOptions?.version && appOptions?.build) {
+    return { version: appOptions.version, build: appOptions.build };
+  }
+
+  // Try react-native-device-info
+  try {
+    const DeviceInfo = require("react-native-device-info").default;
+    return {
+      version: appOptions?.version || DeviceInfo.getVersion(),
+      build: appOptions?.build || DeviceInfo.getBuildNumber(),
+    };
+  } catch {
+    // Not available
+  }
+
+  // Try expo-application
+  try {
+    const ExpoApplication = require("expo-application");
+    return {
+      version: appOptions?.version || ExpoApplication.nativeApplicationVersion || "",
+      build: appOptions?.build || ExpoApplication.nativeBuildVersion || "",
+    };
+  } catch {
+    // Not available
+  }
+
+  return {
+    version: appOptions?.version || "",
+    build: appOptions?.build || "",
+  };
+}
+
+export class AppLifecycleManager {
+  private analytics: IAnalyticsInstance;
+  private appStateSubscription: { remove: () => void } | null = null;
+  private lastAppState: AppStateStatus = AppState.currentState;
+  private appVersionInfo: AppVersionInfo = { version: "", build: "" };
+
+  constructor(analytics: IAnalyticsInstance) {
+    this.analytics = analytics;
+  }
+
+  /**
+   * Initialize lifecycle tracking.
+   * Detects install/update, fires Application Opened, and sets up AppState listener.
+   */
+  async start(
+    appOptions?: { version?: string; build?: string }
+  ): Promise<void> {
+    this.appVersionInfo = await resolveAppVersionInfo(appOptions);
+
+    // Detect install vs update
+    await this.detectInstallOrUpdate();
+
+    // Fire Application Opened (cold start)
+    let initialUrl: string | undefined;
+    try {
+      const url = await Linking.getInitialURL();
+      if (url) {
+        initialUrl = url;
+      }
+    } catch {
+      // Linking not available
+    }
+
+    await this.analytics.track("Application Opened", {
+      version: this.appVersionInfo.version,
+      build: this.appVersionInfo.build,
+      from_background: false,
+      ...(initialUrl && { url: initialUrl }),
+    });
+
+    // Subscribe to AppState changes
+    this.appStateSubscription = AppState.addEventListener(
+      "change",
+      this.handleAppStateChange.bind(this)
+    );
+
+    logger.info("AppLifecycleManager: Started");
+  }
+
+  /**
+   * Compare stored version/build with current to detect install or update.
+   * Requires persistent storage (AsyncStorage) — skips if only MemoryStorage is available,
+   * since MemoryStorage is empty on every cold start and would false-positive as "installed".
+   */
+  private async detectInstallOrUpdate(): Promise<void> {
+    const manager = getStorageManager();
+    const hasPersistentStorage = manager?.hasPersistentStorage() ?? false;
+
+    if (!hasPersistentStorage) {
+      logger.warn(
+        "AppLifecycleManager: AsyncStorage not available, skipping install/update detection. " +
+          "Provide asyncStorage to FormoAnalyticsProvider for accurate lifecycle tracking."
+      );
+      return;
+    }
+
+    const previousVersion = storage().get(LOCAL_APP_VERSION_KEY) as string | null;
+    const previousBuild = storage().get(LOCAL_APP_BUILD_KEY) as string | null;
+
+    const { version, build } = this.appVersionInfo;
+
+    if (previousVersion === null && previousBuild === null) {
+      // No stored version — first install
+      logger.info("AppLifecycleManager: Application Installed");
+      await this.analytics.track("Application Installed", {
+        version,
+        build,
+      });
+    } else if (previousVersion !== version || previousBuild !== build) {
+      // Version or build changed — update
+      logger.info("AppLifecycleManager: Application Updated");
+      await this.analytics.track("Application Updated", {
+        version,
+        build,
+        previous_version: previousVersion || "",
+        previous_build: previousBuild || "",
+      });
+    }
+
+    // Persist current version/build for next comparison
+    // Use setAsync to ensure data is written to AsyncStorage before continuing,
+    // preventing duplicate install events if the app is terminated before persistence completes
+    await storage().setAsync(LOCAL_APP_VERSION_KEY, version);
+    await storage().setAsync(LOCAL_APP_BUILD_KEY, build);
+  }
+
+  /**
+   * Handle AppState transitions for foreground/background events.
+   */
+  private handleAppStateChange(nextAppState: AppStateStatus): void {
+    // Ignore "inactive" (iOS transitional state) and "unknown"
+    if (nextAppState === "inactive" || nextAppState === "unknown") {
+      return;
+    }
+
+    if (nextAppState === "active" && this.lastAppState === "background") {
+      // Returning from background
+      this.analytics
+        .track("Application Opened", {
+          version: this.appVersionInfo.version,
+          build: this.appVersionInfo.build,
+          from_background: true,
+        })
+        .catch((error) => {
+          logger.error("AppLifecycleManager: Error tracking Application Opened", error);
+        });
+    }
+
+    if (nextAppState === "background" && this.lastAppState === "active") {
+      // Going to background
+      this.analytics
+        .track("Application Backgrounded", {
+          version: this.appVersionInfo.version,
+          build: this.appVersionInfo.build,
+        })
+        .catch((error) => {
+          logger.error("AppLifecycleManager: Error tracking Application Backgrounded", error);
+        });
+    }
+
+    this.lastAppState = nextAppState;
+  }
+
+  /**
+   * Clean up AppState listener.
+   */
+  cleanup(): void {
+    if (this.appStateSubscription) {
+      this.appStateSubscription.remove();
+      this.appStateSubscription = null;
+    }
+    logger.info("AppLifecycleManager: Cleaned up");
+  }
+}

package/src/lib/logger/index.ts

@@ -0,0 +1,56 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "log";
+
+interface LoggerConfig {
+  enabled?: boolean;
+  enabledLevels?: LogLevel[];
+}
+
+class LoggerClass {
+  private config: LoggerConfig = {
+    enabled: false,
+    enabledLevels: [],
+  };
+
+  init(config: LoggerConfig) {
+    this.config = config;
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    if (!this.config.enabled) return false;
+    if (this.config.enabledLevels?.length === 0) return true;
+    return this.config.enabledLevels?.includes(level) ?? false;
+  }
+
+  debug(...args: unknown[]) {
+    if (this.shouldLog("debug")) {
+      console.debug("[Formo RN]", ...args);
+    }
+  }
+
+  info(...args: unknown[]) {
+    if (this.shouldLog("info")) {
+      console.info("[Formo RN]", ...args);
+    }
+  }
+
+  warn(...args: unknown[]) {
+    if (this.shouldLog("warn")) {
+      console.warn("[Formo RN]", ...args);
+    }
+  }
+
+  error(...args: unknown[]) {
+    if (this.shouldLog("error")) {
+      console.error("[Formo RN]", ...args);
+    }
+  }
+
+  log(...args: unknown[]) {
+    if (this.shouldLog("log")) {
+      console.log("[Formo RN]", ...args);
+    }
+  }
+}
+
+export const Logger = new LoggerClass();
+export const logger = Logger;

package/src/lib/session/index.ts

@@ -0,0 +1,103 @@
+import {
+  SESSION_WALLET_DETECTED_KEY,
+  SESSION_WALLET_IDENTIFIED_KEY,
+} from "../../constants";
+import { storage } from "../storage";
+import { logger } from "../logger";
+
+export { SESSION_WALLET_DETECTED_KEY, SESSION_WALLET_IDENTIFIED_KEY };
+
+/**
+ * Session manager for tracking wallet detection and identification
+ * Persists to session storage to avoid duplicate detection/identification events
+ * within the same session
+ */
+export class FormoAnalyticsSession {
+  private detectedWallets: Set<string> = new Set();
+  private identifiedWallets: Set<string> = new Set();
+
+  constructor() {
+    this.loadFromStorage();
+  }
+
+  /**
+   * Load session state from storage
+   */
+  private loadFromStorage(): void {
+    try {
+      const detected = storage().get(SESSION_WALLET_DETECTED_KEY);
+      if (detected) {
+        const parsed = JSON.parse(detected) as string[];
+        this.detectedWallets = new Set(parsed);
+      }
+
+      const identified = storage().get(SESSION_WALLET_IDENTIFIED_KEY);
+      if (identified) {
+        const parsed = JSON.parse(identified) as string[];
+        this.identifiedWallets = new Set(parsed);
+      }
+    } catch (error) {
+      logger.debug("Session: Failed to load from storage", error);
+    }
+  }
+
+  /**
+   * Save session state to storage
+   */
+  private saveToStorage(): void {
+    try {
+      storage().set(
+        SESSION_WALLET_DETECTED_KEY,
+        JSON.stringify(Array.from(this.detectedWallets))
+      );
+      storage().set(
+        SESSION_WALLET_IDENTIFIED_KEY,
+        JSON.stringify(Array.from(this.identifiedWallets))
+      );
+    } catch (error) {
+      logger.debug("Session: Failed to save to storage", error);
+    }
+  }
+
+  /**
+   * Check if a wallet has been detected in this session
+   */
+  public isWalletDetected(rdns: string): boolean {
+    return this.detectedWallets.has(rdns);
+  }
+
+  /**
+   * Mark a wallet as detected
+   */
+  public markWalletDetected(rdns: string): void {
+    this.detectedWallets.add(rdns);
+    this.saveToStorage();
+  }
+
+  /**
+   * Check if a wallet + address combination has been identified
+   */
+  public isWalletIdentified(address: string, rdns: string): boolean {
+    const key = `${address.toLowerCase()}:${rdns}`;
+    return this.identifiedWallets.has(key);
+  }
+
+  /**
+   * Mark a wallet + address combination as identified
+   */
+  public markWalletIdentified(address: string, rdns: string): void {
+    const key = `${address.toLowerCase()}:${rdns}`;
+    this.identifiedWallets.add(key);
+    this.saveToStorage();
+  }
+
+  /**
+   * Clear all session data
+   */
+  public clear(): void {
+    this.detectedWallets.clear();
+    this.identifiedWallets.clear();
+    storage().remove(SESSION_WALLET_DETECTED_KEY);
+    storage().remove(SESSION_WALLET_IDENTIFIED_KEY);
+  }
+}

package/src/lib/storage/AsyncStorageAdapter.ts

@@ -0,0 +1,173 @@
+import StorageBlueprint from "./StorageBlueprint";
+import { AsyncStorageInterface } from "./types";
+import { logger } from "../logger";
+
+/**
+ * AsyncStorage adapter for React Native
+ * Provides persistent storage across app restarts
+ */
+class AsyncStorageAdapter extends StorageBlueprint {
+  private asyncStorage: AsyncStorageInterface | null = null;
+  private cache: Map<string, string> = new Map();
+
+  constructor(writeKey: string, asyncStorage?: AsyncStorageInterface) {
+    super(writeKey);
+    if (asyncStorage) {
+      this.asyncStorage = asyncStorage;
+    }
+  }
+
+  /**
+   * Initialize with AsyncStorage instance and preload all Formo keys
+   * This ensures consent flags and other critical data are available synchronously
+   */
+  public async initialize(asyncStorage: AsyncStorageInterface): Promise<void> {
+    this.asyncStorage = asyncStorage;
+
+    // Preload all Formo keys into cache for synchronous access
+    // This is critical for consent checks on cold start (GDPR compliance)
+    try {
+      const allKeys = await asyncStorage.getAllKeys();
+      // getKey("") returns "formo_rn_{writeKey}_" - use this exact prefix
+      // to avoid matching keys from other instances (e.g., "abc" matching "abc123")
+      const formoPrefix = this.getKey("");
+
+      // Filter to only our keys (exact prefix match including trailing underscore)
+      const formoKeys = allKeys.filter((key) => key.startsWith(formoPrefix));
+
+      if (formoKeys.length > 0) {
+        const pairs = await asyncStorage.multiGet(formoKeys);
+        for (const [key, value] of pairs) {
+          if (value !== null) {
+            this.cache.set(key, value);
+          }
+        }
+        logger.debug(
+          `AsyncStorageAdapter: Preloaded ${formoKeys.length} keys into cache`
+        );
+      }
+    } catch (error) {
+      logger.error("AsyncStorageAdapter: Failed to preload keys", error);
+    }
+
+    logger.debug("AsyncStorageAdapter: Initialized");
+  }
+
+  public isAvailable(): boolean {
+    return this.asyncStorage !== null;
+  }
+
+  /**
+   * Synchronous get from cache (may return stale data)
+   * Use getAsync for guaranteed fresh data
+   */
+  public get(key: string): string | null {
+    const cachedValue = this.cache.get(this.getKey(key));
+    if (cachedValue !== undefined) {
+      return cachedValue;
+    }
+
+    // Trigger async fetch to populate cache
+    this.getAsync(key).catch(() => {
+      // Ignore errors in background fetch
+    });
+
+    return null;
+  }
+
+  /**
+   * Async get from storage
+   */
+  public async getAsync(key: string): Promise<string | null> {
+    if (!this.asyncStorage) {
+      return this.cache.get(this.getKey(key)) ?? null;
+    }
+
+    try {
+      const fullKey = this.getKey(key);
+      const value = await this.asyncStorage.getItem(fullKey);
+
+      if (value !== null) {
+        this.cache.set(fullKey, value);
+      }
+
+      return value;
+    } catch (error) {
+      logger.error("AsyncStorageAdapter: Failed to get item", error);
+      return this.cache.get(this.getKey(key)) ?? null;
+    }
+  }
+
+  /**
+   * Synchronous set (writes to cache immediately, persists async)
+   */
+  public set(key: string, value: string): void {
+    const fullKey = this.getKey(key);
+    this.cache.set(fullKey, value);
+
+    // Persist asynchronously
+    this.setAsync(key, value).catch((error) => {
+      logger.error("AsyncStorageAdapter: Failed to persist item", error);
+    });
+  }
+
+  /**
+   * Async set to storage
+   */
+  public async setAsync(key: string, value: string): Promise<void> {
+    const fullKey = this.getKey(key);
+    this.cache.set(fullKey, value);
+
+    if (!this.asyncStorage) {
+      return;
+    }
+
+    try {
+      await this.asyncStorage.setItem(fullKey, value);
+    } catch (error) {
+      logger.error("AsyncStorageAdapter: Failed to set item", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Synchronous remove (removes from cache immediately, persists async)
+   */
+  public remove(key: string): void {
+    const fullKey = this.getKey(key);
+    this.cache.delete(fullKey);
+
+    // Persist asynchronously
+    this.removeAsync(key).catch((error) => {
+      logger.error("AsyncStorageAdapter: Failed to remove item", error);
+    });
+  }
+
+  /**
+   * Async remove from storage
+   */
+  public async removeAsync(key: string): Promise<void> {
+    const fullKey = this.getKey(key);
+    this.cache.delete(fullKey);
+
+    if (!this.asyncStorage) {
+      return;
+    }
+
+    try {
+      await this.asyncStorage.removeItem(fullKey);
+    } catch (error) {
+      logger.error("AsyncStorageAdapter: Failed to remove item", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Clear all cached data
+   */
+  public clearCache(): void {
+    this.cache.clear();
+  }
+}
+
+export default AsyncStorageAdapter;

package/src/lib/storage/MemoryStorage.ts

@@ -0,0 +1,43 @@
+import StorageBlueprint from "./StorageBlueprint";
+
+/**
+ * In-memory storage fallback
+ * Data is lost when the app is closed
+ */
+class MemoryStorage extends StorageBlueprint {
+  private storage: Map<string, string> = new Map();
+
+  public isAvailable(): boolean {
+    return true;
+  }
+
+  public get(key: string): string | null {
+    return this.storage.get(this.getKey(key)) ?? null;
+  }
+
+  public async getAsync(key: string): Promise<string | null> {
+    return this.get(key);
+  }
+
+  public set(key: string, value: string): void {
+    this.storage.set(this.getKey(key), value);
+  }
+
+  public async setAsync(key: string, value: string): Promise<void> {
+    this.set(key, value);
+  }
+
+  public remove(key: string): void {
+    this.storage.delete(this.getKey(key));
+  }
+
+  public async removeAsync(key: string): Promise<void> {
+    this.remove(key);
+  }
+
+  public clear(): void {
+    this.storage.clear();
+  }
+}
+
+export default MemoryStorage;

package/src/lib/storage/StorageBlueprint.ts

@@ -0,0 +1,30 @@
+import { STORAGE_PREFIX } from "../../constants";
+import { IStorage } from "./types";
+
+/**
+ * Base storage class with key prefixing
+ */
+abstract class StorageBlueprint implements IStorage {
+  protected writeKey: string;
+
+  constructor(writeKey: string) {
+    this.writeKey = writeKey;
+  }
+
+  /**
+   * Generate storage key with prefix
+   */
+  public getKey(key: string): string {
+    return `${STORAGE_PREFIX}${this.writeKey}_${key}`;
+  }
+
+  abstract isAvailable(): boolean;
+  abstract get(key: string): string | null;
+  abstract getAsync(key: string): Promise<string | null>;
+  abstract set(key: string, value: string): void;
+  abstract setAsync(key: string, value: string): Promise<void>;
+  abstract remove(key: string): void;
+  abstract removeAsync(key: string): Promise<void>;
+}
+
+export default StorageBlueprint;