@mostly-good-metrics/react-native 0.1.0

package/src/index.ts

@@ -0,0 +1,308 @@
+import { AppState, Platform } from 'react-native';
+import type { AppStateStatus } from 'react-native';
+import {
+  MostlyGoodMetrics as MGMClient,
+  type MGMConfiguration,
+  type EventProperties,
+  SystemEvents,
+  SystemProperties,
+} from '@mostly-good-metrics/javascript';
+import { AsyncStorageEventStorage, persistence, getStorageType } from './storage';
+
+export type { MGMConfiguration, EventProperties };
+
+export interface ReactNativeConfig extends Omit<MGMConfiguration, 'storage'> {
+  /**
+   * The app version string. Required for install/update tracking.
+   */
+  appVersion?: string;
+}
+
+// Use global to persist state across hot reloads
+const g = globalThis as typeof globalThis & {
+  __MGM_RN_STATE__?: {
+    appStateSubscription: { remove: () => void } | null;
+    isConfigured: boolean;
+    currentAppState: AppStateStatus;
+    debugLogging: boolean;
+    lastLifecycleEvent: { name: string; time: number } | null;
+  };
+};
+
+// Initialize or restore state
+if (!g.__MGM_RN_STATE__) {
+  g.__MGM_RN_STATE__ = {
+    appStateSubscription: null,
+    isConfigured: false,
+    currentAppState: AppState.currentState,
+    debugLogging: false,
+    lastLifecycleEvent: null,
+  };
+}
+
+const state = g.__MGM_RN_STATE__;
+
+const DEDUPE_INTERVAL_MS = 1000; // Ignore duplicate events within 1 second
+
+function log(...args: unknown[]) {
+  if (state.debugLogging) {
+    console.log('[MostlyGoodMetrics]', ...args);
+  }
+}
+
+/**
+ * Track a lifecycle event with deduplication.
+ */
+function trackLifecycleEvent(eventName: string, properties?: EventProperties) {
+  const now = Date.now();
+
+  // Deduplicate events that fire multiple times in quick succession
+  if (state.lastLifecycleEvent &&
+      state.lastLifecycleEvent.name === eventName &&
+      now - state.lastLifecycleEvent.time < DEDUPE_INTERVAL_MS) {
+    log(`Skipping duplicate ${eventName} (${now - state.lastLifecycleEvent.time}ms ago)`);
+    return;
+  }
+
+  state.lastLifecycleEvent = { name: eventName, time: now };
+  log(`Tracking lifecycle event: ${eventName}`);
+  MGMClient.track(eventName, properties);
+}
+
+/**
+ * Handle app state changes for lifecycle tracking.
+ */
+function handleAppStateChange(nextAppState: AppStateStatus) {
+  if (!MGMClient.shared) return;
+
+  log(`AppState change: ${state.currentAppState} -> ${nextAppState}`);
+
+  // App came to foreground
+  if (state.currentAppState.match(/inactive|background/) && nextAppState === 'active') {
+    trackLifecycleEvent(SystemEvents.APP_OPENED);
+  }
+
+  // App went to background
+  if (state.currentAppState === 'active' && nextAppState.match(/inactive|background/)) {
+    trackLifecycleEvent(SystemEvents.APP_BACKGROUNDED);
+    // Flush events when going to background
+    MGMClient.flush().catch((e) => log('Flush error:', e));
+  }
+
+  state.currentAppState = nextAppState;
+}
+
+/**
+ * Track app install or update events.
+ */
+async function trackInstallOrUpdate(appVersion?: string) {
+  if (!appVersion) return;
+
+  const previousVersion = await persistence.getAppVersion();
+  const isFirst = await persistence.isFirstLaunch();
+
+  if (isFirst) {
+    trackLifecycleEvent(SystemEvents.APP_INSTALLED, {
+      [SystemProperties.VERSION]: appVersion,
+    });
+    await persistence.setAppVersion(appVersion);
+  } else if (previousVersion && previousVersion !== appVersion) {
+    trackLifecycleEvent(SystemEvents.APP_UPDATED, {
+      [SystemProperties.VERSION]: appVersion,
+      [SystemProperties.PREVIOUS_VERSION]: previousVersion,
+    });
+    await persistence.setAppVersion(appVersion);
+  } else if (!previousVersion) {
+    await persistence.setAppVersion(appVersion);
+  }
+}
+
+/**
+ * MostlyGoodMetrics React Native SDK
+ */
+const MostlyGoodMetrics = {
+  /**
+   * Configure the SDK with an API key and optional settings.
+   */
+  configure(apiKey: string, config: Omit<ReactNativeConfig, 'apiKey'> = {}): void {
+    // Check both our state and the underlying JS SDK
+    if (state.isConfigured || MGMClient.isConfigured) {
+      log('Already configured, skipping');
+      return;
+    }
+
+    state.debugLogging = config.enableDebugLogging ?? false;
+    log('Configuring with options:', config);
+
+    // Create AsyncStorage-based storage
+    const storage = new AsyncStorageEventStorage(config.maxStoredEvents);
+
+    // Restore user ID from storage
+    persistence.getUserId().then((userId) => {
+      if (userId) {
+        log('Restored user ID:', userId);
+      }
+    });
+
+    // Configure the JS SDK
+    // Disable its built-in lifecycle tracking since we handle it ourselves
+    MGMClient.configure({
+      apiKey,
+      ...config,
+      storage,
+      osVersion: getOSVersion(),
+      trackAppLifecycleEvents: false, // We handle this with AppState
+    });
+
+    state.isConfigured = true;
+
+    // Set up React Native lifecycle tracking
+    if (config.trackAppLifecycleEvents !== false) {
+      log('Setting up lifecycle tracking, currentAppState:', state.currentAppState);
+
+      // Remove any existing listener (in case of hot reload)
+      if (state.appStateSubscription) {
+        state.appStateSubscription.remove();
+        state.appStateSubscription = null;
+      }
+
+      // Track initial app open
+      trackLifecycleEvent(SystemEvents.APP_OPENED);
+
+      // Track install/update
+      trackInstallOrUpdate(config.appVersion).catch((e) => log('Install/update tracking error:', e));
+
+      // Subscribe to app state changes
+      state.appStateSubscription = AppState.addEventListener('change', handleAppStateChange);
+    }
+  },
+
+  /**
+   * Track an event with optional properties.
+   */
+  track(name: string, properties?: EventProperties): void {
+    if (!state.isConfigured) {
+      console.warn('[MostlyGoodMetrics] SDK not configured. Call configure() first.');
+      return;
+    }
+
+    // Add React Native specific properties
+    const enrichedProperties: EventProperties = {
+      [SystemProperties.DEVICE_TYPE]: getDeviceType(),
+      $storage_type: getStorageType(),
+      ...properties,
+    };
+
+    MGMClient.track(name, enrichedProperties);
+  },
+
+  /**
+   * Identify a user.
+   */
+  identify(userId: string): void {
+    if (!state.isConfigured) {
+      console.warn('[MostlyGoodMetrics] SDK not configured. Call configure() first.');
+      return;
+    }
+
+    log('Identifying user:', userId);
+    MGMClient.identify(userId);
+    // Also persist to AsyncStorage for restoration
+    persistence.setUserId(userId).catch((e) => log('Failed to persist user ID:', e));
+  },
+
+  /**
+   * Clear the current user identity.
+   */
+  resetIdentity(): void {
+    if (!state.isConfigured) return;
+
+    log('Resetting identity');
+    MGMClient.resetIdentity();
+    persistence.setUserId(null).catch((e) => log('Failed to clear user ID:', e));
+  },
+
+  /**
+   * Manually flush pending events to the server.
+   */
+  flush(): void {
+    if (!state.isConfigured) return;
+
+    log('Flushing events');
+    MGMClient.flush().catch((e) => log('Flush error:', e));
+  },
+
+  /**
+   * Start a new session with a fresh session ID.
+   */
+  startNewSession(): void {
+    if (!state.isConfigured) return;
+
+    log('Starting new session');
+    MGMClient.startNewSession();
+  },
+
+  /**
+   * Clear all pending events without sending them.
+   */
+  clearPendingEvents(): void {
+    if (!state.isConfigured) return;
+
+    log('Clearing pending events');
+    MGMClient.clearPendingEvents().catch((e) => log('Clear error:', e));
+  },
+
+  /**
+   * Get the number of pending events.
+   */
+  async getPendingEventCount(): Promise<number> {
+    if (!state.isConfigured) return 0;
+    return MGMClient.getPendingEventCount();
+  },
+
+  /**
+   * Clean up resources. Call when unmounting the app.
+   */
+  destroy(): void {
+    if (state.appStateSubscription) {
+      state.appStateSubscription.remove();
+      state.appStateSubscription = null;
+    }
+    MGMClient.reset();
+    state.isConfigured = false;
+    state.lastLifecycleEvent = null;
+    log('Destroyed');
+  },
+};
+
+/**
+ * Get device type based on platform.
+ */
+function getDeviceType(): string {
+  if (Platform.OS === 'ios') {
+    // Could use react-native-device-info for more accuracy
+    return Platform.isPad ? 'tablet' : 'phone';
+  }
+  if (Platform.OS === 'android') {
+    return 'phone'; // Could detect tablet with dimensions
+  }
+  return 'unknown';
+}
+
+/**
+ * Get OS version based on platform.
+ */
+function getOSVersion(): string {
+  const version = Platform.Version;
+  if (Platform.OS === 'ios') {
+    // iOS returns a string like "15.0"
+    return String(version);
+  }
+  if (Platform.OS === 'android') {
+    // Android returns SDK version number (e.g., 31 for Android 12)
+    return String(version);
+  }
+  return 'unknown';
+}
+
+export default MostlyGoodMetrics;

package/src/storage.ts

@@ -0,0 +1,171 @@
+import type { IEventStorage, MGMEvent } from '@mostly-good-metrics/javascript';
+
+const STORAGE_KEY = 'mostlygoodmetrics_events';
+const USER_ID_KEY = 'mostlygoodmetrics_user_id';
+const APP_VERSION_KEY = 'mostlygoodmetrics_app_version';
+const FIRST_LAUNCH_KEY = 'mostlygoodmetrics_installed';
+
+// Try to import AsyncStorage, fall back to null if not available
+let AsyncStorage: typeof import('@react-native-async-storage/async-storage').default | null = null;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  AsyncStorage = require('@react-native-async-storage/async-storage').default;
+} catch {
+  // AsyncStorage not installed - will use in-memory storage
+}
+
+/**
+ * Returns the storage type being used.
+ */
+export function getStorageType(): 'persistent' | 'memory' {
+  return AsyncStorage ? 'persistent' : 'memory';
+}
+
+/**
+ * In-memory fallback storage when AsyncStorage is not available.
+ */
+const memoryStorage: Record<string, string> = {};
+
+/**
+ * Storage helpers that work with or without AsyncStorage.
+ */
+async function getItem(key: string): Promise<string | null> {
+  if (AsyncStorage) {
+    try {
+      return await AsyncStorage.getItem(key);
+    } catch {
+      return memoryStorage[key] ?? null;
+    }
+  }
+  return memoryStorage[key] ?? null;
+}
+
+async function setItem(key: string, value: string): Promise<void> {
+  memoryStorage[key] = value;
+  if (AsyncStorage) {
+    try {
+      await AsyncStorage.setItem(key, value);
+    } catch {
+      // Fall back to memory storage (already set above)
+    }
+  }
+}
+
+async function removeItem(key: string): Promise<void> {
+  delete memoryStorage[key];
+  if (AsyncStorage) {
+    try {
+      await AsyncStorage.removeItem(key);
+    } catch {
+      // Already removed from memory
+    }
+  }
+}
+
+/**
+ * Event storage for React Native.
+ * Uses AsyncStorage if available, otherwise falls back to in-memory storage.
+ */
+export class AsyncStorageEventStorage implements IEventStorage {
+  private maxEvents: number;
+  private events: MGMEvent[] | null = null;
+
+  constructor(maxEvents: number = 10000) {
+    this.maxEvents = Math.max(maxEvents, 100);
+  }
+
+  private async loadEvents(): Promise<MGMEvent[]> {
+    if (this.events !== null) {
+      return this.events;
+    }
+
+    try {
+      const stored = await getItem(STORAGE_KEY);
+      if (stored) {
+        this.events = JSON.parse(stored) as MGMEvent[];
+      } else {
+        this.events = [];
+      }
+    } catch {
+      this.events = [];
+    }
+
+    return this.events;
+  }
+
+  private async saveEvents(): Promise<void> {
+    await setItem(STORAGE_KEY, JSON.stringify(this.events ?? []));
+  }
+
+  async store(event: MGMEvent): Promise<void> {
+    const events = await this.loadEvents();
+    events.push(event);
+
+    // Trim oldest events if we exceed the limit
+    if (events.length > this.maxEvents) {
+      const excess = events.length - this.maxEvents;
+      events.splice(0, excess);
+    }
+
+    await this.saveEvents();
+  }
+
+  async fetchEvents(limit: number): Promise<MGMEvent[]> {
+    const events = await this.loadEvents();
+    return events.slice(0, limit);
+  }
+
+  async removeEvents(count: number): Promise<void> {
+    const events = await this.loadEvents();
+    events.splice(0, count);
+    await this.saveEvents();
+  }
+
+  async eventCount(): Promise<number> {
+    const events = await this.loadEvents();
+    return events.length;
+  }
+
+  async clear(): Promise<void> {
+    this.events = [];
+    await removeItem(STORAGE_KEY);
+  }
+}
+
+/**
+ * Persistence helpers for user ID and app version.
+ */
+export const persistence = {
+  async getUserId(): Promise<string | null> {
+    return getItem(USER_ID_KEY);
+  },
+
+  async setUserId(userId: string | null): Promise<void> {
+    if (userId) {
+      await setItem(USER_ID_KEY, userId);
+    } else {
+      await removeItem(USER_ID_KEY);
+    }
+  },
+
+  async getAppVersion(): Promise<string | null> {
+    return getItem(APP_VERSION_KEY);
+  },
+
+  async setAppVersion(version: string | null): Promise<void> {
+    if (version) {
+      await setItem(APP_VERSION_KEY, version);
+    } else {
+      await removeItem(APP_VERSION_KEY);
+    }
+  },
+
+  async isFirstLaunch(): Promise<boolean> {
+    const hasLaunched = await getItem(FIRST_LAUNCH_KEY);
+    if (!hasLaunched) {
+      await setItem(FIRST_LAUNCH_KEY, 'true');
+      return true;
+    }
+    return false;
+  },
+};