@runanywhere/core 0.16.0

package/src/Foundation/ErrorTypes/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Foundation/ErrorTypes
+ *
+ * Unified error handling system for the SDK.
+ * Matches iOS SDK: Foundation/ErrorTypes/
+ */
+
+// Error codes
+export { ErrorCode, getErrorCodeMessage } from './ErrorCodes';
+
+// Error categories
+export {
+  ErrorCategory,
+  allErrorCategories,
+  getCategoryFromCode,
+  inferCategoryFromError,
+} from './ErrorCategory';
+
+// Error context - Type exports
+export type { ErrorContext } from './ErrorContext';
+
+// Error context - Value exports
+export {
+  createErrorContext,
+  formatStackTrace,
+  formatLocation,
+  formatContext,
+  ContextualError,
+  withContext,
+  getErrorContext,
+  getUnderlyingError,
+} from './ErrorContext';
+
+// SDK Error - Type exports
+export type { SDKErrorProtocol } from './SDKError';
+
+// SDK Error - Value exports
+export {
+  // Legacy enum (backwards compatibility)
+  SDKErrorCode,
+  // Class
+  SDKError,
+  // Utility functions
+  asSDKError,
+  isSDKError,
+  captureAndThrow,
+  // Convenience factory functions
+  notInitializedError,
+  alreadyInitializedError,
+  invalidInputError,
+  modelNotFoundError,
+  modelLoadError,
+  networkError,
+  authenticationError,
+  generationError,
+  storageError,
+} from './SDKError';

package/src/Foundation/Initialization/InitializationPhase.ts

@@ -0,0 +1,85 @@
+/**
+ * Initialization Phase
+ *
+ * Represents the two-phase initialization pattern matching iOS SDK.
+ *
+ * Reference: sdk/runanywhere-swift/Sources/RunAnywhere/Public/RunAnywhere.swift
+ *
+ * Phase 1 (Core): Synchronous, fast (~1-5ms)
+ *   - Validate configuration
+ *   - Setup logging
+ *   - Store parameters
+ *   - No network calls
+ *
+ * Phase 2 (Services): Asynchronous (~100-500ms)
+ *   - Initialize network services
+ *   - Setup authentication
+ *   - Load models
+ *   - Register device
+ */
+
+/**
+ * The current initialization phase of the SDK
+ */
+export enum InitializationPhase {
+  /**
+   * SDK has not been initialized
+   */
+  NotInitialized = 'notInitialized',
+
+  /**
+   * Phase 1 complete: Core initialized (sync)
+   * - Configuration validated
+   * - Logging setup
+   * - Parameters stored
+   * - SDK is usable for basic operations
+   */
+  CoreInitialized = 'coreInitialized',
+
+  /**
+   * Phase 2 in progress: Services initializing (async)
+   * - Network services starting
+   * - Authentication in progress
+   * - Models loading
+   */
+  ServicesInitializing = 'servicesInitializing',
+
+  /**
+   * Phase 2 complete: All services ready
+   * - Network ready
+   * - Authenticated (if required)
+   * - Models loaded
+   * - Device registered
+   */
+  FullyInitialized = 'fullyInitialized',
+
+  /**
+   * Initialization failed
+   */
+  Failed = 'failed',
+}
+
+/**
+ * Check if a phase indicates the SDK is usable
+ */
+export function isSDKUsable(phase: InitializationPhase): boolean {
+  return (
+    phase === InitializationPhase.CoreInitialized ||
+    phase === InitializationPhase.ServicesInitializing ||
+    phase === InitializationPhase.FullyInitialized
+  );
+}
+
+/**
+ * Check if a phase indicates services are ready
+ */
+export function areServicesReady(phase: InitializationPhase): boolean {
+  return phase === InitializationPhase.FullyInitialized;
+}
+
+/**
+ * Check if initialization is in progress
+ */
+export function isInitializing(phase: InitializationPhase): boolean {
+  return phase === InitializationPhase.ServicesInitializing;
+}

package/src/Foundation/Initialization/InitializationState.ts

@@ -0,0 +1,168 @@
+/**
+ * Initialization State
+ *
+ * Tracks the complete initialization state of the SDK.
+ * Matches iOS SDK state tracking pattern.
+ *
+ * Reference: sdk/runanywhere-swift/Sources/RunAnywhere/Public/RunAnywhere.swift
+ */
+
+import { InitializationPhase } from './InitializationPhase';
+import type { SDKEnvironment } from '../../types';
+
+/**
+ * Parameters passed to SDK initialization
+ * Matches iOS SDKInitParams
+ */
+export interface SDKInitParams {
+  /**
+   * API key for backend authentication
+   */
+  apiKey?: string;
+
+  /**
+   * Base URL for API calls
+   */
+  baseURL?: string;
+
+  /**
+   * SDK environment (development, staging, production)
+   */
+  environment: SDKEnvironment;
+}
+
+/**
+ * Complete initialization state of the SDK
+ */
+export interface InitializationState {
+  /**
+   * Current initialization phase
+   */
+  phase: InitializationPhase;
+
+  /**
+   * Whether Phase 1 (core) initialization is complete
+   * Equivalent to iOS: isInitialized
+   */
+  isCoreInitialized: boolean;
+
+  /**
+   * Whether Phase 2 (services) initialization is complete
+   * Equivalent to iOS: hasCompletedServicesInit
+   */
+  hasCompletedServicesInit: boolean;
+
+  /**
+   * Current SDK environment
+   */
+  environment: SDKEnvironment | null;
+
+  /**
+   * Stored initialization parameters
+   */
+  initParams: SDKInitParams | null;
+
+  /**
+   * Backend type in use (e.g., 'llamacpp', 'onnx')
+   */
+  backendType: string | null;
+
+  /**
+   * Error if initialization failed
+   */
+  error: Error | null;
+
+  /**
+   * Timestamp when Phase 1 completed
+   */
+  coreInitTimestamp: number | null;
+
+  /**
+   * Timestamp when Phase 2 completed
+   */
+  servicesInitTimestamp: number | null;
+}
+
+/**
+ * Create initial (not initialized) state
+ */
+export function createInitialState(): InitializationState {
+  return {
+    phase: InitializationPhase.NotInitialized,
+    isCoreInitialized: false,
+    hasCompletedServicesInit: false,
+    environment: null,
+    initParams: null,
+    backendType: null,
+    error: null,
+    coreInitTimestamp: null,
+    servicesInitTimestamp: null,
+  };
+}
+
+/**
+ * Update state to Phase 1 complete
+ */
+export function markCoreInitialized(
+  state: InitializationState,
+  params: SDKInitParams,
+  backendType: string | null
+): InitializationState {
+  return {
+    ...state,
+    phase: InitializationPhase.CoreInitialized,
+    isCoreInitialized: true,
+    environment: params.environment,
+    initParams: params,
+    backendType,
+    coreInitTimestamp: Date.now(),
+    error: null,
+  };
+}
+
+/**
+ * Update state to Phase 2 in progress
+ */
+export function markServicesInitializing(
+  state: InitializationState
+): InitializationState {
+  return {
+    ...state,
+    phase: InitializationPhase.ServicesInitializing,
+  };
+}
+
+/**
+ * Update state to Phase 2 complete
+ */
+export function markServicesInitialized(
+  state: InitializationState
+): InitializationState {
+  return {
+    ...state,
+    phase: InitializationPhase.FullyInitialized,
+    hasCompletedServicesInit: true,
+    servicesInitTimestamp: Date.now(),
+  };
+}
+
+/**
+ * Update state to failed
+ */
+export function markInitializationFailed(
+  state: InitializationState,
+  error: Error
+): InitializationState {
+  return {
+    ...state,
+    phase: InitializationPhase.Failed,
+    error,
+  };
+}
+
+/**
+ * Reset state to initial
+ */
+export function resetState(): InitializationState {
+  return createInitialState();
+}

package/src/Foundation/Initialization/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Initialization Module
+ *
+ * Types and utilities for SDK two-phase initialization.
+ * Matches iOS SDK pattern.
+ */
+
+export {
+  InitializationPhase,
+  isSDKUsable,
+  areServicesReady,
+  isInitializing,
+} from './InitializationPhase';
+
+// Type exports
+export type { SDKInitParams, InitializationState } from './InitializationState';
+
+// Value exports
+export {
+  createInitialState,
+  markCoreInitialized,
+  markServicesInitializing,
+  markServicesInitialized,
+  markInitializationFailed,
+  resetState,
+} from './InitializationState';

package/src/Foundation/Logging/Destinations/NativeLogBridge.ts

@@ -0,0 +1,147 @@
+/**
+ * NativeLogBridge.ts
+ *
+ * Bridge for receiving native logs (iOS/Android) in TypeScript.
+ * Native SDKLoggers forward logs through this bridge to the TypeScript LoggingManager.
+ *
+ * This enables:
+ * - Unified log handling across native and TypeScript
+ * - All native logs flowing through TypeScript destinations (Sentry, etc.)
+ * - Centralized log configuration
+ *
+ * Usage:
+ *   import { NativeLogBridge } from '@runanywhere/core';
+ *
+ *   // Initialize bridge (call once at app startup)
+ *   NativeLogBridge.initialize();
+ *
+ *   // Native logs will now flow to TypeScript LoggingManager
+ *   // and all registered destinations (Console, Sentry, etc.)
+ */
+
+import { LoggingManager, type LogEntry } from '../Services/LoggingManager';
+import { LogLevel } from '../Models/LogLevel';
+
+// ============================================================================
+// Native Log Entry Interface
+// ============================================================================
+
+/**
+ * Native log entry structure (from iOS/Android)
+ * Matches NativeLogEntry in iOS/Android SDKLogger
+ */
+export interface NativeLogEntryData {
+  level: number;
+  category: string;
+  message: string;
+  metadata?: Record<string, unknown>;
+  timestamp: string; // ISO8601 string
+}
+
+// ============================================================================
+// Native Log Bridge
+// ============================================================================
+
+/**
+ * Bridge for receiving native logs in TypeScript.
+ * Registers as a forwarder on native SDKLoggers.
+ */
+export class NativeLogBridge {
+  private static initialized = false;
+  private static nativeLogsEnabled = true;
+
+  /**
+   * Initialize the native log bridge.
+   * Call this once at app startup to start receiving native logs.
+   */
+  static initialize(): void {
+    if (this.initialized) {
+      return;
+    }
+
+    // The actual native bridge registration happens automatically
+    // when native code calls the forwarder. This is a marker that
+    // TypeScript is ready to receive logs.
+    this.initialized = true;
+  }
+
+  /**
+   * Enable or disable native log forwarding to TypeScript
+   */
+  static setEnabled(enabled: boolean): void {
+    this.nativeLogsEnabled = enabled;
+  }
+
+  /**
+   * Check if native log forwarding is enabled
+   */
+  static isEnabled(): boolean {
+    return this.nativeLogsEnabled;
+  }
+
+  /**
+   * Handle a log entry from native code.
+   * Called by the native bridge when a log is received.
+   *
+   * @param entryData - Native log entry data
+   */
+  static handleNativeLog(entryData: NativeLogEntryData): void {
+    if (!this.nativeLogsEnabled) {
+      return;
+    }
+
+    // Convert to TypeScript LogEntry
+    const entry: LogEntry = {
+      level: entryData.level as LogLevel,
+      category: `Native.${entryData.category}`,
+      message: entryData.message,
+      metadata: entryData.metadata,
+      timestamp: new Date(entryData.timestamp),
+    };
+
+    // Forward to LoggingManager destinations (except console, since native already logged)
+    // We use a special method that skips console but sends to other destinations
+    this.forwardToDestinations(entry);
+  }
+
+  /**
+   * Forward a log entry to non-console destinations.
+   * This avoids duplicate console logging (native already logged to console).
+   */
+  private static forwardToDestinations(entry: LogEntry): void {
+    const manager = LoggingManager.shared;
+    const destinations = manager.getDestinations();
+
+    for (const destination of destinations) {
+      // Skip console destination (native already logged)
+      if (destination.identifier === 'console') {
+        continue;
+      }
+
+      if (destination.isAvailable) {
+        try {
+          destination.write(entry);
+        } catch {
+          // Silently ignore destination errors
+        }
+      }
+    }
+  }
+}
+
+// ============================================================================
+// Global handler for native bridge
+// ============================================================================
+
+/**
+ * Global function that native code can call to forward logs.
+ * This is registered as a callback that native code invokes.
+ *
+ * @param entryJson - JSON string of NativeLogEntryData
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(global as any).__runanywhereHandleNativeLog = (
+  entryData: NativeLogEntryData
+): void => {
+  NativeLogBridge.handleNativeLog(entryData);
+};

package/src/Foundation/Logging/Destinations/SentryDestination.ts

@@ -0,0 +1,209 @@
+/**
+ * SentryDestination.ts
+ *
+ * Log destination that sends logs to Sentry for error tracking.
+ *
+ * Matches iOS: sdk/runanywhere-swift/Sources/RunAnywhere/Infrastructure/Logging/SentryDestination.swift
+ *
+ * Usage:
+ *   import * as Sentry from '@sentry/react-native';
+ *   import { SentryDestination, LoggingManager } from '@runanywhere/core';
+ *
+ *   // Initialize Sentry first
+ *   Sentry.init({ dsn: 'your-dsn-here' });
+ *
+ *   // Add Sentry destination
+ *   const sentryDest = new SentryDestination(Sentry);
+ *   LoggingManager.shared.addDestination(sentryDest);
+ */
+
+import { LogLevel } from '../Models/LogLevel';
+import type { LogDestination, LogEntry } from '../Services/LoggingManager';
+
+// ============================================================================
+// Sentry Types (minimal interface to avoid hard dependency)
+// ============================================================================
+
+/**
+ * Minimal Sentry interface for logging
+ * This allows apps to pass their own Sentry instance
+ */
+export interface SentryInterface {
+  addBreadcrumb(breadcrumb: {
+    message?: string;
+    category?: string;
+    level?: 'fatal' | 'error' | 'warning' | 'info' | 'debug';
+    data?: Record<string, unknown>;
+    timestamp?: number;
+  }): void;
+
+  captureMessage(
+    message: string,
+    level?: 'fatal' | 'error' | 'warning' | 'info' | 'debug'
+  ): string;
+
+  captureException(exception: Error, hint?: { extra?: Record<string, unknown> }): string;
+
+  setExtra(key: string, extra: unknown): void;
+  setTag(key: string, value: string): void;
+
+  flush(timeout?: number): Promise<boolean>;
+}
+
+// ============================================================================
+// Sentry Destination
+// ============================================================================
+
+/**
+ * Log destination that sends warning+ logs to Sentry.
+ * Matches iOS: SentryDestination
+ */
+export class SentryDestination implements LogDestination {
+  static readonly DESTINATION_ID = 'com.runanywhere.logging.sentry';
+
+  readonly identifier = SentryDestination.DESTINATION_ID;
+  readonly name = 'Sentry';
+
+  private sentry: SentryInterface | null = null;
+  private initialized = false;
+
+  /** Minimum level to send to Sentry (warning and above) */
+  private readonly minSentryLevel: LogLevel = LogLevel.Warning;
+
+  constructor(sentry?: SentryInterface) {
+    if (sentry) {
+      this.initialize(sentry);
+    }
+  }
+
+  // ==========================================================================
+  // Initialization
+  // ==========================================================================
+
+  /**
+   * Initialize with a Sentry instance
+   * @param sentry - Sentry SDK instance
+   */
+  initialize(sentry: SentryInterface): void {
+    this.sentry = sentry;
+    this.initialized = true;
+  }
+
+  /**
+   * Check if Sentry is available
+   */
+  get isAvailable(): boolean {
+    return this.initialized && this.sentry !== null;
+  }
+
+  // ==========================================================================
+  // LogDestination Implementation
+  // ==========================================================================
+
+  /**
+   * Write a log entry to Sentry
+   * Matches iOS: write(_ entry: LogEntry)
+   */
+  write(entry: LogEntry): void {
+    if (!this.isAvailable || !this.sentry) return;
+    if (entry.level < this.minSentryLevel) return;
+
+    // Add breadcrumb for context trail
+    this.addBreadcrumb(entry);
+
+    // For error and fault levels, capture as Sentry event
+    if (entry.level >= LogLevel.Error) {
+      this.captureEvent(entry);
+    }
+  }
+
+  /**
+   * Flush pending Sentry events
+   */
+  flush(): void {
+    if (!this.isAvailable || !this.sentry) return;
+    // Fire and forget - Sentry.flush returns a promise but we don't wait
+    void this.sentry.flush(2000);
+  }
+
+  // ==========================================================================
+  // Private Helpers
+  // ==========================================================================
+
+  /**
+   * Add a breadcrumb for the log entry
+   */
+  private addBreadcrumb(entry: LogEntry): void {
+    if (!this.sentry) return;
+
+    this.sentry.addBreadcrumb({
+      message: entry.message,
+      category: entry.category,
+      level: this.convertToSentryLevel(entry.level),
+      data: entry.metadata as Record<string, unknown>,
+      timestamp: entry.timestamp.getTime() / 1000, // Sentry uses seconds
+    });
+  }
+
+  /**
+   * Capture an event for error/fault level logs
+   */
+  private captureEvent(entry: LogEntry): void {
+    if (!this.sentry) return;
+
+    // Set tags
+    this.sentry.setTag('category', entry.category);
+    this.sentry.setTag('log_level', this.getLogLevelDescription(entry.level));
+
+    // Set extras
+    if (entry.metadata) {
+      for (const [key, value] of Object.entries(entry.metadata)) {
+        this.sentry.setExtra(key, value);
+      }
+    }
+
+    // Capture the message
+    this.sentry.captureMessage(
+      `[${entry.category}] ${entry.message}`,
+      this.convertToSentryLevel(entry.level)
+    );
+  }
+
+  /**
+   * Convert LogLevel to Sentry severity level
+   */
+  private convertToSentryLevel(
+    level: LogLevel
+  ): 'fatal' | 'error' | 'warning' | 'info' | 'debug' {
+    switch (level) {
+      case LogLevel.Debug:
+        return 'debug';
+      case LogLevel.Info:
+        return 'info';
+      case LogLevel.Warning:
+        return 'warning';
+      case LogLevel.Error:
+        return 'error';
+      case LogLevel.Fault:
+        return 'fatal';
+    }
+  }
+
+  /**
+   * Get log level description
+   */
+  private getLogLevelDescription(level: LogLevel): string {
+    switch (level) {
+      case LogLevel.Debug:
+        return 'debug';
+      case LogLevel.Info:
+        return 'info';
+      case LogLevel.Warning:
+        return 'warning';
+      case LogLevel.Error:
+        return 'error';
+      case LogLevel.Fault:
+        return 'fault';
+    }
+  }
+}