@runanywhere/core 0.16.0

package/src/Foundation/ErrorTypes/ErrorContext.ts

@@ -0,0 +1,201 @@
+/**
+ * ErrorContext.ts
+ *
+ * Captures detailed error context for debugging and logging.
+ * Matches iOS SDK: Foundation/ErrorTypes/ErrorContext.swift
+ */
+
+/**
+ * Contextual information captured when an error occurs.
+ */
+export interface ErrorContext {
+  /** Stack trace at error point */
+  readonly stackTrace: string[];
+  /** Source file where error occurred */
+  readonly file: string;
+  /** Line number */
+  readonly line: number;
+  /** Function name */
+  readonly function: string;
+  /** Error capture timestamp (ISO8601) */
+  readonly timestamp: string;
+  /** Thread info ("main" or "background") */
+  readonly threadInfo: string;
+}
+
+/**
+ * Create an error context from the current call site.
+ * Note: In JavaScript, we can only capture stack traces, not file/line/function directly.
+ */
+export function createErrorContext(error?: Error): ErrorContext {
+  const now = new Date().toISOString();
+  const stackTrace = parseStackTrace(error?.stack ?? new Error().stack ?? '');
+
+  // Extract location from first relevant stack frame
+  const location = extractLocationFromStack(stackTrace);
+
+  return {
+    stackTrace,
+    file: location.file,
+    line: location.line,
+    function: location.function,
+    timestamp: now,
+    threadInfo: 'main', // JS is single-threaded (main thread)
+  };
+}
+
+/**
+ * Parse a stack trace string into an array of frames.
+ */
+function parseStackTrace(stack: string): string[] {
+  const lines = stack.split('\n');
+
+  return lines
+    .slice(1) // Skip "Error: message" line
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .filter((line) => !isSystemFrame(line))
+    .slice(0, 15); // Limit to 15 frames like iOS
+}
+
+/**
+ * Check if a stack frame is a system/internal frame that should be filtered.
+ */
+function isSystemFrame(frame: string): boolean {
+  const systemPatterns = [
+    'node_modules',
+    'internal/',
+    '__webpack',
+    'regenerator',
+    'asyncToGenerator',
+    'createErrorContext', // Filter ourselves out
+    'parseStackTrace',
+  ];
+
+  return systemPatterns.some((pattern) => frame.includes(pattern));
+}
+
+/**
+ * Extract file, line, and function from the first relevant stack frame.
+ */
+function extractLocationFromStack(stackTrace: string[]): {
+  file: string;
+  line: number;
+  function: string;
+} {
+  if (stackTrace.length === 0) {
+    return { file: 'unknown', line: 0, function: 'unknown' };
+  }
+
+  const firstFrame = stackTrace[0];
+
+  // Try to parse "at functionName (file:line:column)" format
+  const atMatch = firstFrame.match(/at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)/);
+  if (atMatch) {
+    return {
+      function: atMatch[1],
+      file: atMatch[2],
+      line: parseInt(atMatch[3], 10),
+    };
+  }
+
+  // Try to parse "at file:line:column" format (anonymous function)
+  const atFileMatch = firstFrame.match(/at\s+(.+?):(\d+):(\d+)/);
+  if (atFileMatch) {
+    return {
+      function: 'anonymous',
+      file: atFileMatch[1],
+      line: parseInt(atFileMatch[2], 10),
+    };
+  }
+
+  // Try to parse "functionName@file:line:column" format (Safari/Firefox)
+  const atSignMatch = firstFrame.match(/(.+?)@(.+?):(\d+):(\d+)/);
+  if (atSignMatch) {
+    return {
+      function: atSignMatch[1] || 'anonymous',
+      file: atSignMatch[2],
+      line: parseInt(atSignMatch[3], 10),
+    };
+  }
+
+  return { file: 'unknown', line: 0, function: 'unknown' };
+}
+
+/**
+ * Format the stack trace as a readable string.
+ */
+export function formatStackTrace(context: ErrorContext): string {
+  if (context.stackTrace.length === 0) {
+    return 'No stack trace available';
+  }
+  return context.stackTrace.join('\n');
+}
+
+/**
+ * Get a formatted location string (file:line in function).
+ */
+export function formatLocation(context: ErrorContext): string {
+  return `${context.file}:${context.line} in ${context.function}`;
+}
+
+/**
+ * Get a complete formatted context string for logging.
+ */
+export function formatContext(context: ErrorContext): string {
+  return [
+    `Time: ${context.timestamp}`,
+    `Thread: ${context.threadInfo}`,
+    `Location: ${formatLocation(context)}`,
+    `Stack Trace:`,
+    formatStackTrace(context),
+  ].join('\n');
+}
+
+/**
+ * An error wrapper that includes context information.
+ */
+export class ContextualError extends Error {
+  readonly context: ErrorContext;
+  readonly originalError: Error;
+
+  constructor(error: Error, context?: ErrorContext) {
+    super(error.message);
+    this.name = 'ContextualError';
+    this.originalError = error;
+    this.context = context ?? createErrorContext(error);
+
+    // Maintain proper prototype chain
+    Object.setPrototypeOf(this, ContextualError.prototype);
+  }
+}
+
+/**
+ * Wrap an error with context information.
+ */
+export function withContext(error: Error): ContextualError {
+  if (error instanceof ContextualError) {
+    return error; // Already has context
+  }
+  return new ContextualError(error);
+}
+
+/**
+ * Extract error context from an error if available.
+ */
+export function getErrorContext(error: Error): ErrorContext | undefined {
+  if (error instanceof ContextualError) {
+    return error.context;
+  }
+  return undefined;
+}
+
+/**
+ * Get the underlying error value, unwrapping ContextualError if needed.
+ */
+export function getUnderlyingError(error: Error): Error {
+  if (error instanceof ContextualError) {
+    return error.originalError;
+  }
+  return error;
+}

package/src/Foundation/ErrorTypes/SDKError.ts

@@ -0,0 +1,507 @@
+/**
+ * SDKError.ts
+ *
+ * Base SDK error class matching iOS SDKErrorProtocol.
+ * Matches iOS SDK: Foundation/ErrorTypes/SDKErrorProtocol.swift
+ */
+
+import { ErrorCode, getErrorCodeMessage } from './ErrorCodes';
+import {
+  ErrorCategory,
+  getCategoryFromCode,
+  inferCategoryFromError,
+} from './ErrorCategory';
+import type { ErrorContext } from './ErrorContext';
+import {
+  createErrorContext,
+  formatContext,
+  formatLocation,
+} from './ErrorContext';
+import { SDKLogger, LogLevel } from '../Logging';
+
+/**
+ * Legacy SDK error code enum (string-based).
+ * @deprecated Prefer using ErrorCode (numeric) for new code.
+ */
+export enum SDKErrorCode {
+  NotInitialized = 'notInitialized',
+  NotImplemented = 'notImplemented',
+  InvalidAPIKey = 'invalidAPIKey',
+  ModelNotFound = 'modelNotFound',
+  LoadingFailed = 'loadingFailed',
+  ModelLoadFailed = 'modelLoadFailed',
+  GenerationFailed = 'generationFailed',
+  GenerationTimeout = 'generationTimeout',
+  FrameworkNotAvailable = 'frameworkNotAvailable',
+  FeatureNotAvailable = 'featureNotAvailable',
+  DownloadFailed = 'downloadFailed',
+  ValidationFailed = 'validationFailed',
+  RoutingFailed = 'routingFailed',
+  DatabaseInitializationFailed = 'databaseInitializationFailed',
+  UnsupportedModality = 'unsupportedModality',
+  InvalidResponse = 'invalidResponse',
+  AuthenticationFailed = 'authenticationFailed',
+  NetworkError = 'networkError',
+  InvalidState = 'invalidState',
+  ComponentNotInitialized = 'componentNotInitialized',
+  ComponentNotReady = 'componentNotReady',
+  CleanupFailed = 'cleanupFailed',
+  ProcessingFailed = 'processingFailed',
+  Timeout = 'timeout',
+  ServerError = 'serverError',
+  StorageError = 'storageError',
+  InvalidConfiguration = 'invalidConfiguration',
+}
+
+/**
+ * Map legacy string-based SDKErrorCode to numeric ErrorCode
+ */
+function mapLegacyCodeToErrorCode(code: SDKErrorCode): ErrorCode {
+  switch (code) {
+    case SDKErrorCode.NotInitialized:
+      return ErrorCode.NotInitialized;
+    case SDKErrorCode.NotImplemented:
+      return ErrorCode.Unknown;
+    case SDKErrorCode.InvalidAPIKey:
+      return ErrorCode.ApiKeyInvalid;
+    case SDKErrorCode.ModelNotFound:
+      return ErrorCode.ModelNotFound;
+    case SDKErrorCode.LoadingFailed:
+    case SDKErrorCode.ModelLoadFailed:
+      return ErrorCode.ModelLoadFailed;
+    case SDKErrorCode.GenerationFailed:
+      return ErrorCode.GenerationFailed;
+    case SDKErrorCode.GenerationTimeout:
+      return ErrorCode.GenerationTimeout;
+    case SDKErrorCode.FrameworkNotAvailable:
+    case SDKErrorCode.FeatureNotAvailable:
+      return ErrorCode.HardwareUnavailable;
+    case SDKErrorCode.DownloadFailed:
+      return ErrorCode.DownloadFailed;
+    case SDKErrorCode.ValidationFailed:
+    case SDKErrorCode.InvalidConfiguration:
+      return ErrorCode.InvalidInput;
+    case SDKErrorCode.RoutingFailed:
+      return ErrorCode.Unknown;
+    case SDKErrorCode.DatabaseInitializationFailed:
+      return ErrorCode.Unknown;
+    case SDKErrorCode.UnsupportedModality:
+      return ErrorCode.InvalidInput;
+    case SDKErrorCode.InvalidResponse:
+      return ErrorCode.ApiError;
+    case SDKErrorCode.AuthenticationFailed:
+      return ErrorCode.AuthenticationFailed;
+    case SDKErrorCode.NetworkError:
+      return ErrorCode.NetworkUnavailable;
+    case SDKErrorCode.InvalidState:
+    case SDKErrorCode.ComponentNotInitialized:
+    case SDKErrorCode.ComponentNotReady:
+      return ErrorCode.NotInitialized;
+    case SDKErrorCode.CleanupFailed:
+      return ErrorCode.Unknown;
+    case SDKErrorCode.ProcessingFailed:
+      return ErrorCode.GenerationFailed;
+    case SDKErrorCode.Timeout:
+      return ErrorCode.NetworkTimeout;
+    case SDKErrorCode.ServerError:
+      return ErrorCode.ApiError;
+    case SDKErrorCode.StorageError:
+      return ErrorCode.FileAccessDenied;
+    default:
+      return ErrorCode.Unknown;
+  }
+}
+
+/**
+ * Base SDK error interface matching iOS SDKErrorProtocol.
+ */
+export interface SDKErrorProtocol {
+  /** Machine-readable error code */
+  readonly code: ErrorCode;
+  /** Error category for filtering/analytics */
+  readonly category: ErrorCategory;
+  /** Original error that caused this error */
+  readonly underlyingError?: Error;
+  /** Error context with stack trace and location */
+  readonly context: ErrorContext;
+}
+
+/**
+ * Unified SDK error class.
+ *
+ * Supports both legacy string-based codes (SDKErrorCode) and
+ * new numeric codes (ErrorCode) for backwards compatibility.
+ *
+ * @example
+ * // Legacy usage (still works):
+ * throw new SDKError(SDKErrorCode.NotInitialized, 'SDK not ready');
+ *
+ * // New recommended usage:
+ * throw new SDKError(ErrorCode.NotInitialized, 'SDK not ready');
+ */
+export class SDKError extends Error implements SDKErrorProtocol {
+  readonly code: ErrorCode;
+  readonly legacyCode?: SDKErrorCode;
+  readonly category: ErrorCategory;
+  readonly underlyingError?: Error;
+  readonly context: ErrorContext;
+  readonly details?: Record<string, unknown>;
+
+  constructor(
+    code: ErrorCode | SDKErrorCode,
+    message?: string,
+    options?: {
+      underlyingError?: Error;
+      category?: ErrorCategory;
+      details?: Record<string, unknown>;
+    }
+  ) {
+    // Determine if we're using legacy string code or new numeric code
+    const isLegacyCode = typeof code === 'string';
+    const numericCode = isLegacyCode
+      ? mapLegacyCodeToErrorCode(code as SDKErrorCode)
+      : (code as ErrorCode);
+    const errorMessage = message ?? getErrorCodeMessage(numericCode);
+
+    super(errorMessage);
+
+    this.name = 'SDKError';
+    this.code = numericCode;
+    this.legacyCode = isLegacyCode ? (code as SDKErrorCode) : undefined;
+    this.category = options?.category ?? getCategoryFromCode(numericCode);
+    this.underlyingError = options?.underlyingError;
+    this.context = createErrorContext(options?.underlyingError ?? this);
+    this.details = options?.details;
+
+    // Maintain proper prototype chain
+    Object.setPrototypeOf(this, SDKError.prototype);
+  }
+
+  /**
+   * Convert error to analytics data for event tracking.
+   */
+  toAnalyticsData(): Record<string, unknown> {
+    return {
+      error_code: this.code,
+      error_code_name: ErrorCode[this.code],
+      legacy_code: this.legacyCode,
+      error_category: this.category,
+      error_message: this.message,
+      error_location: formatLocation(this.context),
+      error_timestamp: this.context.timestamp,
+      has_underlying_error: this.underlyingError !== undefined,
+      underlying_error_name: this.underlyingError?.name,
+      underlying_error_message: this.underlyingError?.message,
+      ...this.details,
+    };
+  }
+
+  /**
+   * Log error with full context using SDKLogger.
+   */
+  logError(): void {
+    const logger = new SDKLogger('SDKError');
+    const metadata: Record<string, unknown> = {
+      error_code: this.code,
+      error_code_name: ErrorCode[this.code],
+      category: this.category,
+      context: formatContext(this.context),
+    };
+
+    if (this.underlyingError) {
+      metadata.underlying_error = this.underlyingError.message;
+      metadata.underlying_stack = this.underlyingError.stack;
+    }
+
+    logger.log(LogLevel.Error, `${ErrorCode[this.code]}: ${this.message}`, metadata);
+  }
+}
+
+/**
+ * Convert any error to an SDKError.
+ * If already an SDKError, returns as-is.
+ * Otherwise, wraps with appropriate categorization.
+ */
+export function asSDKError(error: Error): SDKError {
+  if (error instanceof SDKError) {
+    return error;
+  }
+
+  const category = inferCategoryFromError(error);
+  const code = mapCategoryToCode(category);
+
+  return new SDKError(code, error.message, {
+    underlyingError: error,
+    category,
+  });
+}
+
+/**
+ * Map an error category to a default error code.
+ */
+function mapCategoryToCode(category: ErrorCategory): ErrorCode {
+  switch (category) {
+    case ErrorCategory.Initialization:
+      return ErrorCode.NotInitialized;
+    case ErrorCategory.Model:
+      return ErrorCode.ModelLoadFailed;
+    case ErrorCategory.Generation:
+      return ErrorCode.GenerationFailed;
+    case ErrorCategory.Network:
+      return ErrorCode.NetworkUnavailable;
+    case ErrorCategory.Storage:
+      return ErrorCode.FileNotFound;
+    case ErrorCategory.Memory:
+      return ErrorCode.HardwareUnavailable;
+    case ErrorCategory.Hardware:
+      return ErrorCode.HardwareUnsupported;
+    case ErrorCategory.Validation:
+      return ErrorCode.InvalidInput;
+    case ErrorCategory.Authentication:
+      return ErrorCode.AuthenticationFailed;
+    case ErrorCategory.Component:
+      return ErrorCode.Unknown;
+    case ErrorCategory.Framework:
+      return ErrorCode.Unknown;
+    case ErrorCategory.Unknown:
+    default:
+      return ErrorCode.Unknown;
+  }
+}
+
+/**
+ * Type guard to check if an error is an SDKError.
+ */
+export function isSDKError(error: unknown): error is SDKError {
+  return error instanceof SDKError;
+}
+
+/**
+ * Create and throw an SDKError, capturing context at the call site.
+ * Useful for wrapping errors with automatic context capture.
+ */
+export function captureAndThrow(
+  code: ErrorCode,
+  message?: string,
+  underlyingError?: Error
+): never {
+  throw new SDKError(code, message, { underlyingError });
+}
+
+// Convenience factory functions for common error types
+
+export function notInitializedError(component?: string): SDKError {
+  const message = component
+    ? `${component} not initialized`
+    : 'SDK not initialized';
+  return new SDKError(ErrorCode.NotInitialized, message);
+}
+
+export function alreadyInitializedError(component?: string): SDKError {
+  const message = component
+    ? `${component} already initialized`
+    : 'SDK already initialized';
+  return new SDKError(ErrorCode.AlreadyInitialized, message);
+}
+
+export function invalidInputError(details?: string): SDKError {
+  const message = details ? `Invalid input: ${details}` : 'Invalid input';
+  return new SDKError(ErrorCode.InvalidInput, message);
+}
+
+export function modelNotFoundError(modelId?: string): SDKError {
+  const message = modelId ? `Model not found: ${modelId}` : 'Model not found';
+  return new SDKError(ErrorCode.ModelNotFound, message);
+}
+
+export function modelLoadError(modelId?: string, cause?: Error): SDKError {
+  const message = modelId
+    ? `Failed to load model: ${modelId}`
+    : 'Failed to load model';
+  return new SDKError(ErrorCode.ModelLoadFailed, message, {
+    underlyingError: cause,
+  });
+}
+
+export function networkError(details?: string, cause?: Error): SDKError {
+  const message = details ?? 'Network error';
+  return new SDKError(ErrorCode.NetworkUnavailable, message, {
+    underlyingError: cause,
+  });
+}
+
+export function authenticationError(details?: string): SDKError {
+  const message = details ?? 'Authentication failed';
+  return new SDKError(ErrorCode.AuthenticationFailed, message);
+}
+
+export function generationError(details?: string, cause?: Error): SDKError {
+  const message = details ?? 'Generation failed';
+  return new SDKError(ErrorCode.GenerationFailed, message, {
+    underlyingError: cause,
+  });
+}
+
+export function storageError(details?: string, cause?: Error): SDKError {
+  const message = details ?? 'Storage error';
+  return new SDKError(ErrorCode.FileNotFound, message, {
+    underlyingError: cause,
+  });
+}
+
+// ============================================================================
+// Native Error Wrapping
+// ============================================================================
+
+/**
+ * Native error structure from Nitro/React Native bridge.
+ * Native modules typically return errors as JSON with these fields.
+ */
+export interface NativeErrorData {
+  /** Error code (may be string or number) */
+  code?: string | number;
+  /** Error message */
+  message?: string;
+  /** Domain (iOS) or exception type (Android) */
+  domain?: string;
+  /** User info dictionary (iOS) */
+  userInfo?: Record<string, unknown>;
+  /** Native stack trace */
+  nativeStackTrace?: string;
+  /** Additional details */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Parse and wrap a native error from JSON-based error data.
+ *
+ * Native modules (via Nitro) often return errors as JSON strings or objects.
+ * This function converts them to proper SDKError instances with full context.
+ *
+ * Matches iOS pattern where native errors are wrapped with proper categorization.
+ *
+ * @param nativeError - Native error data (string, object, or Error)
+ * @returns SDKError with proper wrapping
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const result = await nativeModule.someMethod();
+ * } catch (error) {
+ *   throw fromNativeError(error);
+ * }
+ * ```
+ */
+export function fromNativeError(nativeError: unknown): SDKError {
+  // Already an SDKError - return as-is
+  if (nativeError instanceof SDKError) {
+    return nativeError;
+  }
+
+  // Standard Error - wrap it
+  if (nativeError instanceof Error) {
+    return asSDKError(nativeError);
+  }
+
+  // Try to parse as JSON string
+  if (typeof nativeError === 'string') {
+    try {
+      const parsed = JSON.parse(nativeError);
+      return parseNativeErrorData(parsed);
+    } catch {
+      // Not JSON, treat as error message
+      return new SDKError(ErrorCode.Unknown, nativeError);
+    }
+  }
+
+  // Object with error data
+  if (typeof nativeError === 'object' && nativeError !== null) {
+    return parseNativeErrorData(nativeError as NativeErrorData);
+  }
+
+  // Unknown type - create generic error
+  return new SDKError(ErrorCode.Unknown, String(nativeError));
+}
+
+/**
+ * Parse native error data object into SDKError.
+ */
+function parseNativeErrorData(data: NativeErrorData): SDKError {
+  // Extract error code
+  let code = ErrorCode.Unknown;
+  if (typeof data.code === 'number') {
+    code = data.code in ErrorCode ? data.code : ErrorCode.Unknown;
+  } else if (typeof data.code === 'string') {
+    // Try to map string code to ErrorCode
+    code = mapNativeCodeString(data.code);
+  }
+
+  // Build message
+  const message = data.message ?? 'Native error';
+
+  // Create underlying error with native stack trace
+  let underlyingError: Error | undefined;
+  if (data.nativeStackTrace) {
+    const nativeErr = new Error(message);
+    nativeErr.stack = data.nativeStackTrace;
+    nativeErr.name = data.domain ?? 'NativeError';
+    underlyingError = nativeErr;
+  }
+
+  return new SDKError(code, message, {
+    underlyingError,
+    details: {
+      nativeDomain: data.domain,
+      nativeUserInfo: data.userInfo,
+      ...data.details,
+    },
+  });
+}
+
+/**
+ * Map native code strings to ErrorCode.
+ * Native modules may use various string identifiers.
+ */
+function mapNativeCodeString(codeString: string): ErrorCode {
+  const normalized = codeString.toLowerCase().replace(/[_-]/g, '');
+
+  // Common native error patterns
+  if (normalized.includes('notinitialized') || normalized.includes('notinit')) {
+    return ErrorCode.NotInitialized;
+  }
+  if (normalized.includes('modelload') || normalized.includes('loadfail')) {
+    return ErrorCode.ModelLoadFailed;
+  }
+  if (normalized.includes('modelnotfound')) {
+    return ErrorCode.ModelNotFound;
+  }
+  if (normalized.includes('generation') || normalized.includes('inference')) {
+    return ErrorCode.GenerationFailed;
+  }
+  if (normalized.includes('network') || normalized.includes('connection')) {
+    return ErrorCode.NetworkUnavailable;
+  }
+  if (normalized.includes('auth') || normalized.includes('unauthorized')) {
+    return ErrorCode.AuthenticationFailed;
+  }
+  if (normalized.includes('timeout')) {
+    return ErrorCode.NetworkTimeout;
+  }
+  if (normalized.includes('memory') || normalized.includes('oom')) {
+    return ErrorCode.HardwareUnavailable;
+  }
+  if (normalized.includes('file') || normalized.includes('storage')) {
+    return ErrorCode.FileNotFound;
+  }
+  if (normalized.includes('invalid') || normalized.includes('validation')) {
+    return ErrorCode.InvalidInput;
+  }
+  if (normalized.includes('download')) {
+    return ErrorCode.DownloadFailed;
+  }
+  if (normalized.includes('cancelled') || normalized.includes('canceled')) {
+    return ErrorCode.OperationCancelled;
+  }
+
+  return ErrorCode.Unknown;
+}