@mobileai/react-native 0.9.17 → 0.9.18

package/src/services/telemetry/TelemetryService.ts

@@ -1,323 +0,0 @@
-/**
- * TelemetryService — Batches and sends analytics events to MobileAI Cloud.
- *
- * Features:
- * - Event batching (flush every N seconds or N events)
- * - Offline queue with retry on reconnect
- * - Lightweight — no native dependencies
- * - Opt-in only (requires analyticsKey or analyticsProxyUrl)
- */
-
-import { AppState, Platform } from 'react-native';
-import { logger } from '../../utils/logger';
-import { ENDPOINTS } from '../../config/endpoints';
-import type {
-  TelemetryEvent,
-  TelemetryBatch,
-  TelemetryConfig,
-} from './types';
-import { scrubPII } from './PiiScrubber';
-import { FlagService } from '../flags/FlagService';
-
-// Optional: AsyncStorage for offline event persistence
-// SDK works without it — just loses crash recovery for queued events
-let _asyncStorage: any = null;
-let _asyncStorageLoaded = false;
-
-function loadAsyncStorage(): any {
-  if (_asyncStorageLoaded) return _asyncStorage;
-  _asyncStorageLoaded = true;
-  try {
-    // Suppress the RN red box that AsyncStorage triggers when its native module
-    // isn't linked ("NativeModule: AsyncStorage is null").
-    const origError = console.error;
-    console.error = (...args: unknown[]) => {
-      const msg = args[0];
-      if (typeof msg === 'string' && msg.includes('AsyncStorage')) return;
-      origError.apply(console, args);
-    };
-    try {
-      const mod = require('@react-native-async-storage/async-storage');
-      _asyncStorage = mod.default ?? mod;
-    } finally {
-      console.error = origError;
-    }
-    // Verify the native module actually works by checking for the native bridge
-    if (!_asyncStorage || typeof _asyncStorage.getItem !== 'function') {
-      _asyncStorage = null;
-    }
-  } catch {
-    // Not installed — offline queue persistence disabled
-  }
-  return _asyncStorage;
-}
-
-// ─── Constants ─────────────────────────────────────────────────
-
-const CLOUD_API_URL = ENDPOINTS.telemetryIngest;
-const STORAGE_KEY = '@mobileai/telemetry_queue';
-const DEFAULT_FLUSH_INTERVAL_MS = 30_000;
-const DEFAULT_MAX_BATCH_SIZE = 50;
-const SDK_VERSION = '0.10.0';
-const LOG_TAG = 'Telemetry';
-
-// ─── Utility ───────────────────────────────────────────────────
-
-function generateSessionId(): string {
-  return `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
-}
-
-import { getDeviceId } from './device';
-
-// ─── Service ───────────────────────────────────────────────────
-
-export class TelemetryService {
-  private queue: TelemetryEvent[] = [];
-  private config: TelemetryConfig;
-  private sessionId: string;
-  private currentScreen = 'Unknown';
-  private screenFlow: string[] = [];
-  private flushTimer: ReturnType<typeof setInterval> | null = null;
-  private isFlushing = false;
-  private appStateSubscription: ReturnType<typeof AppState.addEventListener> | null = null;
-
-  get screen(): string {
-    return this.currentScreen;
-  }
-
-  getScreenFlow(): string[] {
-    return [...this.screenFlow];
-  }
-
-  /**
-   * True while the AI agent is executing a tool (tap, type, navigate, etc.).
-   * The touch interceptor checks this flag to avoid double-counting AI actions
-   * as human interactions. Agent steps are already tracked as agent_step events.
-   */
-  isAgentActing = false;
-  
-  public flags: FlagService;
-
-  /** Set by AgentRuntime before/after each tool execution. */
-  setAgentActing(active: boolean): void {
-    this.isAgentActing = active;
-  }
-
-  constructor(config: TelemetryConfig) {
-    this.config = config;
-    this.sessionId = generateSessionId();
-    
-    // Extract base URL for flags API (e.g. drop /v1/events)
-    let baseUrl = new URL(ENDPOINTS.escalation).origin;
-    try {
-      if (config.analyticsProxyUrl) {
-        baseUrl = new URL(config.analyticsProxyUrl).origin;
-      }
-    } catch {}
-    this.flags = new FlagService(baseUrl);
-  }
-
-  // ─── Lifecycle ──────────────────────────────────────────────
-
-  /** Start the telemetry service (call on mount) */
-  async start(): Promise<void> {
-    if (!this.isEnabled()) {
-      logger.debug(LOG_TAG, 'Disabled — no analyticsKey or proxyUrl');
-      return;
-    }
-
-    // Restore queued events from previous session
-    await this.restoreQueue();
-
-    // Fetch feature flags asynchronously (do not block startup)
-    if (this.config.analyticsKey) {
-      this.flags.fetch(this.config.analyticsKey).catch((e) => 
-        logger.warn(LOG_TAG, `Could not sync flags: ${e.message}`)
-      );
-    }
-
-    // Start periodic flush
-    const interval = this.config.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
-    this.flushTimer = setInterval(() => this.flush(), interval);
-
-    // Flush on app background
-    this.appStateSubscription = AppState.addEventListener(
-      'change',
-      (state) => {
-        if (state === 'background' || state === 'inactive') {
-          this.flush();
-        }
-      }
-    );
-
-    // Track session start
-    this.track('session_start', {
-      device: Platform.OS,
-      os: String(Platform.Version),
-      sdk_version: SDK_VERSION,
-    });
-
-    logger.info(LOG_TAG, `Started (session: ${this.sessionId})`);
-  }
-
-  /** Stop the telemetry service (call on unmount) */
-  async stop(): Promise<void> {
-    if (!this.isEnabled()) return;
-
-    // Track session end
-    this.track('session_end', {
-      events_count: this.queue.length,
-    });
-
-    // Final flush
-    await this.flush();
-
-    // Cleanup
-    if (this.flushTimer) {
-      clearInterval(this.flushTimer);
-      this.flushTimer = null;
-    }
-    if (this.appStateSubscription) {
-      this.appStateSubscription.remove();
-      this.appStateSubscription = null;
-    }
-
-    logger.info(LOG_TAG, 'Stopped');
-  }
-
-  // ─── Public API ─────────────────────────────────────────────
-
-  /** Track an event (auto or custom) */
-  track(type: string, data: Record<string, unknown> = {}): void {
-    if (!this.isEnabled()) return;
-
-    // Sanitize any string values in the data payload to remove PII
-    const sanitizedData = Object.fromEntries(
-      Object.entries(data).map(([k, v]) => [
-        k,
-        typeof v === 'string' ? scrubPII(v) : v,
-      ])
-    );
-
-    // Auto-append active feature flags
-    sanitizedData.$flags = this.flags.getAllFlags();
-
-    const event: TelemetryEvent = {
-      type,
-      data: sanitizedData,
-      timestamp: new Date().toISOString(),
-      screen: this.currentScreen,
-      sessionId: this.sessionId,
-    };
-
-    this.queue.push(event);
-
-    if (this.config.debug) {
-      logger.debug(LOG_TAG, `→ ${type}`, data);
-    }
-
-    // Auto-flush if batch is full
-    const maxSize = this.config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
-    if (this.queue.length >= maxSize) {
-      this.flush();
-    }
-  }
-
-  /** Update current screen (called by AIAgent on navigation) */
-  setScreen(screenName: string): void {
-    if (this.currentScreen !== screenName) {
-      const prevScreen = this.currentScreen;
-      this.currentScreen = screenName;
-      this.screenFlow.push(screenName);
-
-      this.track('screen_view', {
-        screen: screenName,
-        prev_screen: prevScreen,
-      });
-    }
-  }
-
-  // ─── Flush ──────────────────────────────────────────────────
-
-  /** Send queued events to the cloud API */
-  async flush(): Promise<void> {
-    if (!this.isEnabled() || this.queue.length === 0 || this.isFlushing) return;
-
-    this.isFlushing = true;
-    const eventsToSend = [...this.queue];
-    this.queue = [];
-
-    try {
-      const url = this.config.analyticsProxyUrl ?? CLOUD_API_URL;
-      const headers: Record<string, string> = {
-        'Content-Type': 'application/json',
-        ...(this.config.analyticsProxyHeaders ?? {}),
-      };
-
-      const batch: TelemetryBatch = {
-        analyticsKey: this.config.analyticsKey ?? '',
-        appId: Platform.OS, // Consumer can override via config later
-        deviceId: getDeviceId() ?? 'unknown',
-        sdkVersion: SDK_VERSION,
-        events: eventsToSend,
-      };
-
-      const response = await fetch(url, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify(batch),
-      });
-
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}`);
-      }
-
-      logger.info(LOG_TAG, `Flushed ${eventsToSend.length} events`);
-    } catch (error: any) {
-      // Re-queue failed events for retry
-      this.queue = [...eventsToSend, ...this.queue];
-      await this.persistQueue();
-
-      logger.warn(LOG_TAG, `Flush failed (${eventsToSend.length} events re-queued): ${error.message}`);
-    } finally {
-      this.isFlushing = false;
-    }
-  }
-
-  // ─── Persistence (offline support) ──────────────────────────
-
-  /** Save queued events to AsyncStorage for crash/restart recovery */
-  private async persistQueue(): Promise<void> {
-    const storage = loadAsyncStorage();
-    if (!storage) return;
-    try {
-      await storage.setItem(STORAGE_KEY, JSON.stringify(this.queue));
-    } catch {
-      // AsyncStorage may not be available in all environments
-    }
-  }
-
-  /** Restore queued events from previous session */
-  private async restoreQueue(): Promise<void> {
-    const storage = loadAsyncStorage();
-    if (!storage) return;
-    try {
-      const stored = await storage.getItem(STORAGE_KEY);
-      if (stored) {
-        const events: TelemetryEvent[] = JSON.parse(stored);
-        this.queue = [...events, ...this.queue];
-        await storage.removeItem(STORAGE_KEY);
-        logger.info(LOG_TAG, `Restored ${events.length} events from previous session`);
-      }
-    } catch {
-      // Silently fail — telemetry is non-critical
-    }
-  }
-
-  // ─── Helpers ────────────────────────────────────────────────
-
-  /** Check if telemetry is configured */
-  private isEnabled(): boolean {
-    return !!(this.config.analyticsKey || this.config.analyticsProxyUrl);
-  }
-}

package/src/services/telemetry/TouchAutoCapture.ts

@@ -1,165 +0,0 @@
-/**
- * TouchAutoCapture — Extracts a human-readable label from a React Native
- * touch event target by walking up the native view hierarchy.
- *
- * Used by AIAgent to auto-track every tap in the app without
- * any developer code changes (zero-config analytics).
- *
- * Strategy:
- * 1. Read the touched element's accessibilityLabel (best signal).
- * 2. If none, use React Native's internal _children to find nested text.
- * 3. Fallback to the component's testID.
- * 4. Last resort: "Unknown Element".
- */
-
-// React Native imports not needed — we use Fiber internals directly
-import type { TelemetryService } from './TelemetryService';
-
-const recentTaps: { label: string; ts: number }[] = [];
-const RAGE_WINDOW_MS = 2000;
-const RAGE_THRESHOLD = 3;
-
-/**
- * Checks if the user is repeatedly tapping the same element in frustration.
- * If rage click detected, emits 'rage_click' event to telemetry.
- */
-export function checkRageClick(label: string, telemetry: TelemetryService): void {
-  const now = Date.now();
-  recentTaps.push({ label, ts: now });
-  
-  // Keep buffer unbounded size of 5
-  if (recentTaps.length > 5) recentTaps.shift();
-
-  const recent = recentTaps.filter(t => t.label === label && now - t.ts < RAGE_WINDOW_MS);
-  if (recent.length >= RAGE_THRESHOLD) {
-    telemetry.track('rage_click', { 
-      label, 
-      count: recent.length, 
-      screen: telemetry.screen 
-    });
-    recentTaps.length = 0; // reset buffer after emitting to avoid spam
-  }
-}
-
-/**
- * Extract a label from a GestureResponderEvent's native target.
- *
- * @param nativeEvent - The nativeEvent from onStartShouldSetResponderCapture
- * @param rootRef - The root View ref (to resolve relative positions)
- * @returns A descriptive label string for the tapped element
- */
-export function extractTouchLabel(nativeEvent: any): string {
-  // Try accessible properties first (most reliable)
-  const target = nativeEvent?.target;
-
-  if (!target) return 'Unknown Element';
-
-  // React Native internal: _internalFiberInstanceHandleDEV or _nativeTag
-  // We can walk the Fiber tree from the target to find text
-  try {
-    // Strategy 1: Walk up the Fiber tree from the touched element
-    let fiber = getFiberFromNativeTag(target);
-    if (fiber) {
-      // Walk up looking for text content or accessibility labels
-      let current: any = fiber;
-      let depth = 0;
-      const MAX_DEPTH = 10;
-
-      while (current && depth < MAX_DEPTH) {
-        // Check for accessibilityLabel
-        if (current.memoizedProps?.accessibilityLabel) {
-          return current.memoizedProps.accessibilityLabel;
-        }
-
-        // Check for testID
-        if (current.memoizedProps?.testID) {
-          return current.memoizedProps.testID;
-        }
-
-        // Check for title (Button component)
-        if (current.memoizedProps?.title) {
-          return current.memoizedProps.title;
-        }
-
-        // Check for placeholder (TextInput)
-        if (current.memoizedProps?.placeholder) {
-          return `Input: ${current.memoizedProps.placeholder}`;
-        }
-
-        // Check if this is a Text node with children string
-        if (
-          typeof current.memoizedProps?.children === 'string' &&
-          current.memoizedProps.children.trim()
-        ) {
-          return current.memoizedProps.children.trim();
-        }
-
-        // Check for nested text in children array
-        if (Array.isArray(current.memoizedProps?.children)) {
-          const textChild = findTextInChildren(current.memoizedProps.children);
-          if (textChild) return textChild;
-        }
-
-        current = current.return;
-        depth++;
-      }
-    }
-  } catch {
-    // Fiber access failed — fall back gracefully
-  }
-
-  return 'Unknown Element';
-}
-
-/**
- * Find the first string text in a React children tree (recursive, max 3 levels).
- */
-function findTextInChildren(children: any[], depth = 0): string | null {
-  if (depth > 3) return null;
-
-  for (const child of children) {
-    if (typeof child === 'string' && child.trim()) {
-      return child.trim();
-    }
-    if (typeof child === 'number') {
-      return String(child);
-    }
-    // React element with props.children
-    if (child?.props?.children) {
-      if (typeof child.props.children === 'string' && child.props.children.trim()) {
-        return child.props.children.trim();
-      }
-      if (Array.isArray(child.props.children)) {
-        const found = findTextInChildren(child.props.children, depth + 1);
-        if (found) return found;
-      }
-    }
-  }
-
-  return null;
-}
-
-/**
- * Attempt to get the Fiber node from a native tag (React Native internal).
- * This uses the same technique as React DevTools and testing libraries.
- */
-function getFiberFromNativeTag(nativeTag: number): any {
-  try {
-    // React Native stores a reference from native tag → Fiber
-    // via the __internalInstanceHandle on the native node
-    const instance = (globalThis as any).__REACT_DEVTOOLS_GLOBAL_HOOK__;
-    if (instance?.renderers) {
-      for (const [, renderer] of instance.renderers) {
-        if (renderer?.findFiberByHostInstance) {
-          // Try to find via the devtools hook
-          const fiber = renderer.findFiberByHostInstance(nativeTag);
-          if (fiber) return fiber;
-        }
-      }
-    }
-  } catch {
-    // DevTools hook not available — expected in production
-  }
-
-  return null;
-}

package/src/services/telemetry/device.ts

@@ -1,93 +0,0 @@
-/**
- * Persistent device ID — a UUID generated on first launch and stored in AsyncStorage.
- * Unique per app install, survives across sessions.
- *
- * AsyncStorage is an optional peer dependency — if not installed, the ID
- * persists only in memory for the current session.
- */
-
-const STORAGE_KEY = '@mobileai:device_id';
-
-let _cachedId: string | null = null;
-let _storageLoaded = false;
-let _storage: any = null;
-
-function loadStorage(): any {
-  if (_storageLoaded) return _storage;
-  _storageLoaded = true;
-  try {
-    // Suppress the RN red box that AsyncStorage triggers when its native module
-    // isn't linked ("NativeModule: AsyncStorage is null").
-    const origError = console.error;
-    console.error = (...args: unknown[]) => {
-      const msg = args[0];
-      if (typeof msg === 'string' && msg.includes('AsyncStorage')) return;
-      origError.apply(console, args);
-    };
-    try {
-      const mod = require('@react-native-async-storage/async-storage');
-      const candidate = mod.default ?? mod;
-      if (candidate && typeof candidate.getItem === 'function') {
-        _storage = candidate;
-      }
-    } finally {
-      console.error = origError;
-    }
-  } catch {
-    // Not installed — device ID won't persist across restarts
-  }
-  return _storage;
-}
-
-function generateUUID(): string {
-  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-    return crypto.randomUUID();
-  }
-  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);
-  });
-}
-
-/**
- * Returns the persistent device ID synchronously (from cache).
- * Returns null if not yet initialized.
- */
-export function getDeviceId(): string | null {
-  return _cachedId;
-}
-
-/**
- * Initializes or retrieves the persistent device ID.
- * Call once on app startup. Subsequent getDeviceId() calls are synchronous.
- */
-export async function initDeviceId(): Promise<string> {
-  if (_cachedId) return _cachedId;
-
-  const storage = loadStorage();
-  if (storage) {
-    try {
-      const stored: string | null = await storage.getItem(STORAGE_KEY);
-      if (stored) {
-        _cachedId = stored;
-        return stored;
-      }
-    } catch {
-      // Storage read failed — continue with new ID
-    }
-  }
-
-  const newId = generateUUID();
-  _cachedId = newId;
-
-  if (storage) {
-    try {
-      await storage.setItem(STORAGE_KEY, newId);
-    } catch {
-      // Storage write failed — ID works for this session only
-    }
-  }
-
-  return newId;
-}

package/src/services/telemetry/deviceMetadata.ts

@@ -1,13 +0,0 @@
-import { Platform } from 'react-native';
-
-export interface DeviceMetadata {
-  platform: string;
-  osVersion: string;
-}
-
-export function getDeviceMetadata(): DeviceMetadata {
-  return {
-    platform: Platform.OS === 'ios' ? 'iOS' : Platform.OS === 'android' ? 'Android' : Platform.OS,
-    osVersion: String(Platform.Version),
-  };
-}

package/src/services/telemetry/index.ts

@@ -1,13 +0,0 @@
-/**
- * Telemetry module barrel export.
- */
-
-export { TelemetryService } from './TelemetryService';
-export { MobileAI, bindTelemetryService } from './MobileAI';
-export type {
-  TelemetryEvent,
-  TelemetryBatch,
-  TelemetryConfig,
-  AutoEventType,
-  EventType,
-} from './types';

package/src/services/telemetry/types.ts

@@ -1,75 +0,0 @@
-/**
- * Telemetry types for the MobileAI analytics module.
- *
- * Events are split into two categories:
- * 1. Auto-captured: SDK captures these without consumer code
- * 2. Consumer-tracked: via MobileAI.track() API
- */
-
-// ─── Event Types ──────────────────────────────────────────────
-
-/** Auto-captured event types */
-export type AutoEventType =
-  | 'screen_view'
-  | 'user_action'
-  | 'scroll_depth'
-  | 'idle_detected'
-  | 'session_start'
-  | 'session_end'
-  | 'agent_request'
-  | 'agent_step'
-  | 'agent_complete'
-  | 'escalation'
-  | 'knowledge_query'
-  | 'knowledge_miss'
-  | 'csat_response';
-
-/** All event types (auto + custom) */
-export type EventType = AutoEventType | string;
-
-// ─── Event Payload ────────────────────────────────────────────
-
-export interface TelemetryEvent {
-  /** Event type identifier */
-  type: EventType;
-  /** Event-specific data */
-  data: Record<string, unknown>;
-  /** ISO 8601 timestamp (auto-set by SDK) */
-  timestamp: string;
-  /** Current screen name (auto-attached) */
-  screen: string;
-  /** Session ID (auto-generated per app lifecycle) */
-  sessionId: string;
-}
-
-// ─── Batch Payload (sent to cloud) ────────────────────────────
-
-export interface TelemetryBatch {
-  /** Publishable analytics key */
-  analyticsKey: string;
-  /** App identifier (bundle ID / package name) */
-  appId: string;
-  /** Hashed user/device identifier */
-  deviceId: string;
-  /** SDK version */
-  sdkVersion: string;
-  /** Batch of events */
-  events: TelemetryEvent[];
-}
-
-// ─── Configuration ────────────────────────────────────────────
-
-export interface TelemetryConfig {
-  /** Publishable analytics key (mobileai_pub_xxx) */
-  analyticsKey?: string;
-  /** Proxy URL for enterprise customers (replaces direct cloud API) */
-  analyticsProxyUrl?: string;
-  /** Custom headers for proxy requests */
-  analyticsProxyHeaders?: Record<string, string>;
-  /** Flush interval in ms (default: 30000) */
-  flushIntervalMs?: number;
-  /** Max events before auto-flush (default: 50) */
-  maxBatchSize?: number;
-  /** Enable debug logging for telemetry (default: false) */
-  debug?: boolean;
-}