@mobana/react-native-sdk 0.2.10

package/src/storage.ts

@@ -0,0 +1,262 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { Attribution, CachedAttributionResult, ConversionEvent, CachedFlow } from './types';
+
+const KEYS = {
+  INSTALL_ID: '@mobana:install_id',
+  ATTRIBUTION: '@mobana:attribution',
+  CONVERSION_QUEUE: '@mobana:conversion_queue',
+  LOCAL_DATA: '@mobana:local_data',
+} as const;
+
+const FLOW_CACHE_PREFIX = '@mobana:flow:';
+
+/**
+ * Get or create a stable install ID (UUID)
+ * Generated once on first launch and persisted locally
+ */
+export async function getInstallId(): Promise<string> {
+  try {
+    let installId = await AsyncStorage.getItem(KEYS.INSTALL_ID);
+    
+    if (!installId) {
+      // Generate UUID v4
+      installId = generateUUID();
+      await AsyncStorage.setItem(KEYS.INSTALL_ID, installId);
+    }
+    
+    return installId;
+  } catch {
+    // If storage fails, generate a new UUID each time
+    // This is suboptimal but ensures the SDK doesn't crash
+    return generateUUID();
+  }
+}
+
+/**
+ * Get cached attribution result (includes matched: false responses)
+ */
+export async function getCachedResult<T = Record<string, unknown>>(): Promise<CachedAttributionResult<T> | null> {
+  try {
+    const data = await AsyncStorage.getItem(KEYS.ATTRIBUTION);
+    if (data) {
+      return JSON.parse(data) as CachedAttributionResult<T>;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store attribution result in cache (stores both matched and unmatched responses)
+ */
+export async function setCachedResult<T = Record<string, unknown>>(
+  matched: boolean,
+  attribution?: Attribution<T>
+): Promise<void> {
+  try {
+    const result: CachedAttributionResult<T> = {
+      matched,
+      attribution,
+      checkedAt: Date.now(),
+    };
+    await AsyncStorage.setItem(KEYS.ATTRIBUTION, JSON.stringify(result));
+  } catch {
+    // Silently fail - caching is not critical
+  }
+}
+
+/**
+ * Clear all stored attribution data (for testing/reset)
+ */
+export async function clearAttribution(): Promise<void> {
+  try {
+    await AsyncStorage.multiRemove([KEYS.ATTRIBUTION, KEYS.INSTALL_ID]);
+  } catch {
+    // Silently fail
+  }
+}
+
+/**
+ * Queue a conversion event for later sending (offline support)
+ */
+export async function queueConversion(event: ConversionEvent): Promise<void> {
+  try {
+    const queue = await getConversionQueue();
+    queue.push(event);
+    await AsyncStorage.setItem(KEYS.CONVERSION_QUEUE, JSON.stringify(queue));
+  } catch {
+    // Silently fail - we tried our best
+  }
+}
+
+/**
+ * Get all queued conversion events
+ */
+export async function getConversionQueue(): Promise<ConversionEvent[]> {
+  try {
+    const data = await AsyncStorage.getItem(KEYS.CONVERSION_QUEUE);
+    if (data) {
+      return JSON.parse(data) as ConversionEvent[];
+    }
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Clear the conversion queue after successful send
+ */
+export async function clearConversionQueue(): Promise<void> {
+  try {
+    await AsyncStorage.removeItem(KEYS.CONVERSION_QUEUE);
+  } catch {
+    // Silently fail
+  }
+}
+
+/**
+ * Generate a UUID v4
+ * Uses crypto.getRandomValues when available (Hermes 0.73+), falls back to Math.random
+ */
+export function generateUUID(): string {
+  // Check if crypto.getRandomValues is available (Hermes 0.73+, modern RN)
+  const cryptoObj = typeof globalThis !== 'undefined' && (globalThis as typeof globalThis & { crypto?: { getRandomValues: (array: Uint8Array) => Uint8Array } }).crypto;
+  if (cryptoObj && typeof cryptoObj.getRandomValues === 'function') {
+    try {
+      const bytes = new Uint8Array(16);
+      cryptoObj.getRandomValues(bytes);
+      bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+      bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 1
+      const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+      return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    } catch {
+      // Fall through to Math.random fallback
+    }
+  }
+  // Fallback for environments without crypto.getRandomValues
+  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);
+  });
+}
+
+// ============================================
+// Flow Caching
+// ============================================
+
+/**
+ * Get cached flow content by slug
+ */
+export async function getCachedFlow(slug: string): Promise<CachedFlow | null> {
+  try {
+    const key = `${FLOW_CACHE_PREFIX}${slug}`;
+    const data = await AsyncStorage.getItem(key);
+    if (data) {
+      return JSON.parse(data) as CachedFlow;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Cache flow content
+ */
+export async function setCachedFlow(slug: string, flow: Omit<CachedFlow, 'cachedAt'>): Promise<void> {
+  try {
+    const key = `${FLOW_CACHE_PREFIX}${slug}`;
+    const cached: CachedFlow = {
+      ...flow,
+      cachedAt: Date.now(),
+    };
+    await AsyncStorage.setItem(key, JSON.stringify(cached));
+  } catch {
+    // Silently fail - caching is not critical
+  }
+}
+
+/**
+ * Clear cached flow by slug
+ */
+export async function clearCachedFlow(slug: string): Promise<void> {
+  try {
+    const key = `${FLOW_CACHE_PREFIX}${slug}`;
+    await AsyncStorage.removeItem(key);
+  } catch {
+    // Silently fail
+  }
+}
+
+/**
+ * Clear all cached flows
+ */
+export async function clearAllCachedFlows(): Promise<void> {
+  try {
+    const allKeys = await AsyncStorage.getAllKeys();
+    const flowKeys = allKeys.filter(key => key.startsWith(FLOW_CACHE_PREFIX));
+    if (flowKeys.length > 0) {
+      await AsyncStorage.multiRemove(flowKeys);
+    }
+  } catch {
+    // Silently fail
+  }
+}
+
+// ============================================
+// Local Data (for flow bridge)
+// ============================================
+
+/**
+ * Get all local data
+ */
+export async function getAllLocalData(): Promise<Record<string, unknown>> {
+  try {
+    const data = await AsyncStorage.getItem(KEYS.LOCAL_DATA);
+    if (data) {
+      return JSON.parse(data) as Record<string, unknown>;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Store data locally on device (persists across app sessions)
+ */
+export async function setLocalData(key: string, value: unknown): Promise<void> {
+  try {
+    const data = await getAllLocalData();
+    data[key] = value;
+    await AsyncStorage.setItem(KEYS.LOCAL_DATA, JSON.stringify(data));
+  } catch {
+    // Silently fail
+  }
+}
+
+/**
+ * Retrieve locally stored data
+ */
+export async function getLocalData(key: string): Promise<unknown> {
+  try {
+    const data = await getAllLocalData();
+    return data[key];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Clear all local data
+ */
+export async function clearLocalData(): Promise<void> {
+  try {
+    await AsyncStorage.removeItem(KEYS.LOCAL_DATA);
+  } catch {
+    // Silently fail
+  }
+}

package/src/types.ts

@@ -0,0 +1,362 @@
+/**
+ * Configuration options for Mobana SDK
+ */
+export interface MobanaConfig {
+  /**
+   * Your Mobana app ID from the dashboard (e.g., 'a1b2c3d4')
+   * Required.
+   */
+  appId: string;
+
+  /**
+   * Your Mobana app key from the dashboard. Sent as X-App-Key header.
+   * Required. Regenerate from dashboard if leaked.
+   */
+  appKey: string;
+
+  /**
+   * Custom endpoint URL for attribution API
+   * Optional. Use this if proxying through your own domain (e.g., 'https://myapp.com/d')
+   * If not set, defaults to https://{appId}.mobana.ai
+   */
+  endpoint?: string;
+
+  /**
+   * Enable or disable the SDK (default: true)
+   * Set to false to disable all attribution tracking (e.g., for GDPR opt-out)
+   */
+  enabled?: boolean;
+
+  /**
+   * Enable debug logging (default: false)
+   * When true, logs SDK operations to console
+   */
+  debug?: boolean;
+}
+
+// ============================================
+// Flow Types
+// ============================================
+
+/**
+ * Flow content returned from the API
+ */
+export interface FlowConfig {
+  /** Unique version identifier (immutable) */
+  versionId: string;
+  /** HTML content of the flow */
+  html: string;
+  /** CSS styles (may be embedded in HTML) */
+  css?: string;
+  /** JavaScript code (may be embedded in HTML) */
+  js?: string;
+}
+
+/**
+ * Result returned from startFlow()
+ */
+export interface FlowResult {
+  /** Whether the flow was completed (user called Mobana.complete()) */
+  completed: boolean;
+  /** Whether the flow was dismissed (user called Mobana.dismiss()) */
+  dismissed: boolean;
+  /** Error code if flow couldn't be shown */
+  error?: FlowError;
+  /** Custom data passed to Mobana.complete(data) */
+  data?: Record<string, unknown>;
+  /** Session ID for this flow presentation (use with trackConversion's flowSessionId) */
+  sessionId?: string;
+  /**
+   * Track a custom event for this flow session after the flow has closed.
+   * Useful for tracking events that happen after the flow (e.g., purchase after onboarding).
+   * 
+   * @param event - Event name (e.g., 'purchase_completed', 'feature_used')
+   * @param data - Optional event data (will be stored as JSON)
+   * @returns Promise resolving to true if event was tracked successfully
+   * 
+   * @example
+   * ```typescript
+   * const result = await Mobana.startFlow('pre-purchase');
+   * // ... user makes purchase via Adapty ...
+   * await result.trackEvent('purchase_initiated');
+   * ```
+   */
+  trackEvent?: (event: string, data?: Record<string, unknown>) => Promise<boolean>;
+}
+
+/**
+ * Possible flow error codes
+ */
+export type FlowError =
+  | 'NOT_FOUND'           // Flow doesn't exist or is disabled
+  | 'PLAN_REQUIRED'       // App's plan doesn't include flows
+  | 'FLOW_LIMIT_EXCEEDED' // Flow view quota exceeded (free plan hard limit)
+  | 'NETWORK_ERROR'       // Network request failed
+  | 'SERVER_ERROR'        // Server returned an error
+  | 'PROVIDER_NOT_MOUNTED' // MobanaProvider not in component tree
+  | 'SDK_NOT_CONFIGURED'; // SDK.init() not called
+
+/**
+ * Options for startFlow()
+ */
+export interface FlowOptions {
+  /**
+   * Custom parameters available in the flow via Mobana.getParams()
+   * Use this to pass context to your flow (e.g., user name, feature flags)
+   */
+  params?: Record<string, unknown>;
+  
+  /**
+   * Callback when flow emits custom events via Mobana.trackEvent()
+   * Useful for analytics integration
+   */
+  onEvent?: (event: string) => void;
+
+  /**
+   * Async callback invoked when the flow calls Mobana.requestCallback(data).
+   * Allows the flow to request the app to perform an action (e.g., trigger a purchase,
+   * validate a promo code) and await the result — without closing the flow.
+   * 
+   * @param data - Arbitrary data sent from the flow
+   * @returns Promise resolving to arbitrary data returned to the flow
+   * 
+   * @example
+   * ```typescript
+   * const result = await Mobana.startFlow('paywall', {
+   *   onCallback: async (data) => {
+   *     if (data.action === 'purchase') {
+   *       const purchase = await purchaseManager.buy(data.planId);
+   *       return { success: purchase.success, receipt: purchase.receipt };
+   *     }
+   *     return { error: 'Unknown action' };
+   *   },
+   * });
+   * ```
+   */
+  onCallback?: (data: Record<string, unknown>) => Promise<Record<string, unknown>>;
+}
+
+/**
+ * Cached flow content (stored in AsyncStorage)
+ */
+export interface CachedFlow {
+  versionId: string;
+  html: string;
+  css?: string;
+  js?: string;
+  cachedAt: number;
+}
+
+/**
+ * API response from GET /api/flows/[slug]
+ */
+export interface FlowFetchResponse {
+  /** True if client's cached version is still current */
+  cached?: boolean;
+  /** Version ID (always present if not an error) */
+  versionId?: string;
+  /** HTML content (present if not cached) */
+  html?: string;
+  /** CSS content (present if not cached) */
+  css?: string;
+  /** JS content (present if not cached) */
+  js?: string;
+  /** Error code if flow unavailable */
+  error?: string;
+}
+
+/**
+ * Flow event to send to the server
+ */
+export interface FlowEvent {
+  installId: string;
+  versionId: string;
+  sessionId: string;
+  event: string;
+  step?: number;
+  data?: unknown;
+}
+
+// ============================================
+// Bridge Types (for WebView communication)
+// ============================================
+
+/**
+ * Haptic feedback styles
+ */
+export type HapticStyle = 
+  | 'light' 
+  | 'medium' 
+  | 'heavy' 
+  | 'success' 
+  | 'warning' 
+  | 'error'
+  | 'selection';
+
+/**
+ * Location permission status
+ */
+export type LocationPermissionStatus = 
+  | 'granted'
+  | 'denied' 
+  | 'blocked'
+  | 'unavailable'
+  | 'limited';
+
+/**
+ * ATT (App Tracking Transparency) status (iOS only)
+ */
+export type ATTStatus = 
+  | 'authorized'
+  | 'denied'
+  | 'not-determined'
+  | 'restricted';
+
+/**
+ * Device color scheme (light/dark mode)
+ */
+export type ColorScheme = 'light' | 'dark';
+
+/**
+ * Location coordinates
+ */
+export interface LocationCoordinates {
+  latitude: number;
+  longitude: number;
+  accuracy: number;
+  altitude: number | null;
+  altitudeAccuracy: number | null;
+  heading: number | null;
+  speed: number | null;
+  timestamp: number;
+}
+
+/**
+ * Message from WebView to native
+ */
+export interface BridgeMessage {
+  type: string;
+  requestId?: number;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  payload?: any;
+}
+
+/**
+ * Options for getAttribution call
+ */
+export interface GetAttributionOptions {
+  /**
+   * Timeout in milliseconds for the attribution request (default: 10000)
+   */
+  timeout?: number;
+}
+
+/**
+ * Attribution data returned from the API
+ */
+export interface Attribution<T = Record<string, unknown>> {
+  /**
+   * Traffic source (e.g., 'facebook', 'google', 'tiktok')
+   */
+  utm_source?: string;
+
+  /**
+   * Marketing medium (e.g., 'cpc', 'social', 'email')
+   */
+  utm_medium?: string;
+
+  /**
+   * Campaign name
+   */
+  utm_campaign?: string;
+
+  /**
+   * Ad content identifier
+   */
+  utm_content?: string;
+
+  /**
+   * Search keywords
+   */
+  utm_term?: string;
+
+  /**
+   * Referring domain that sent the user to the tracking link (e.g., 'facebook.com')
+   * Only the domain is stored (not the full URL) for privacy.
+   */
+  referrer_domain?: string;
+
+  /**
+   * Custom deeplink data passed through the attribution flow
+   * Use generics for type-safe access: getAttribution<MyDataType>()
+   */
+  data?: T;
+
+  /**
+   * Match confidence score (0.0 - 1.0)
+   * - 1.0 = Deterministic match via Android Install Referrer
+   * - < 1.0 = Probabilistic match
+   */
+  confidence: number;
+}
+
+/**
+ * Internal: API response from /find endpoint
+ */
+export interface FindResponse<T = Record<string, unknown>> {
+  matched: boolean;
+  attribution?: Attribution<T>;
+  confidence?: number;
+}
+
+/**
+ * Internal: Cached attribution result (includes matched: false responses)
+ */
+export interface CachedAttributionResult<T = Record<string, unknown>> {
+  matched: boolean;
+  attribution?: Attribution<T>;
+  checkedAt: number;
+}
+
+/**
+ * Internal: Conversion event to be sent or queued
+ */
+export interface ConversionEvent {
+  installId: string;
+  name: string;
+  value?: number;
+  timestamp: number;
+  /** Optional flow session ID to link conversion to a specific flow presentation */
+  flowSessionId?: string;
+}
+
+/**
+ * Internal: Device info collected for attribution matching
+ */
+export interface DeviceInfo {
+  platform: 'ios' | 'android';
+  timezone?: string;
+  screenWidth?: number;
+  screenHeight?: number;
+  language?: string;
+}
+
+/**
+ * Safe area insets for the device screen
+ * Represents the areas of the screen that may be obscured by system UI
+ * (status bar, notch/dynamic island, home indicator, etc.)
+ */
+export interface SafeArea {
+  /** Inset from top (status bar, notch, dynamic island) in points */
+  top: number;
+  /** Inset from bottom (home indicator, navigation bar) in points */
+  bottom: number;
+  /** Inset from left (typically 0, but can be non-zero in landscape) in points */
+  left: number;
+  /** Inset from right (typically 0, but can be non-zero in landscape) in points */
+  right: number;
+  /** Full screen width in points */
+  width: number;
+  /** Full screen height in points */
+  height: number;
+}