@runanywhere/core 0.16.0

package/src/Foundation/Logging/Services/LoggingManager.ts

@@ -0,0 +1,407 @@
+/**
+ * LoggingManager.ts
+ *
+ * Centralized logging manager with multiple destination support.
+ * Routes logs to multiple destinations (Console, Sentry, etc.) based on configuration.
+ *
+ * Matches iOS: sdk/runanywhere-swift/Sources/RunAnywhere/Infrastructure/Logging/SDKLogger.swift
+ *              (Logging class - central service)
+ *
+ * Usage:
+ *   // Configure for environment
+ *   LoggingManager.shared.configure({ environment: SDKEnvironment.Production });
+ *
+ *   // Add Sentry destination
+ *   LoggingManager.shared.addDestination(new SentryDestination(Sentry));
+ *
+ *   // Subscribe to log events (for custom handling)
+ *   const unsubscribe = LoggingManager.shared.onLog((entry) => {
+ *     // Forward to your analytics, etc.
+ *   });
+ */
+
+import { LogLevel } from '../Models/LogLevel';
+import {
+  type LoggingConfiguration,
+  SDKEnvironment,
+  getConfigurationForEnvironment,
+} from '../Models/LoggingConfiguration';
+
+// ============================================================================
+// Log Entry
+// ============================================================================
+
+/**
+ * Log entry structure
+ * Matches iOS: LogEntry
+ */
+export interface LogEntry {
+  /** Log level */
+  level: LogLevel;
+  /** Category/subsystem */
+  category: string;
+  /** Log message */
+  message: string;
+  /** Optional metadata */
+  metadata?: Record<string, unknown>;
+  /** Timestamp */
+  timestamp: Date;
+}
+
+// ============================================================================
+// Log Destination Protocol
+// ============================================================================
+
+/**
+ * Log destination interface
+ * Matches iOS: LogDestination protocol
+ */
+export interface LogDestination {
+  /** Unique identifier for this destination */
+  identifier: string;
+  /** Human-readable name */
+  name: string;
+  /** Whether destination is available */
+  isAvailable: boolean;
+  /** Write a log entry */
+  write(entry: LogEntry): void;
+  /** Flush pending writes */
+  flush(): void;
+}
+
+// ============================================================================
+// Console Destination
+// ============================================================================
+
+/**
+ * Console log destination (default)
+ */
+export class ConsoleLogDestination implements LogDestination {
+  readonly identifier = 'console';
+  readonly name = 'Console';
+  readonly isAvailable = true;
+
+  write(entry: LogEntry): void {
+    const timestamp = entry.timestamp.toISOString();
+    const levelStr = getLogLevelDescription(entry.level);
+    const logMessage = `[${timestamp}] [${levelStr}] [${entry.category}] ${entry.message}`;
+
+    switch (entry.level) {
+      case LogLevel.Debug:
+        // eslint-disable-next-line no-console
+        console.debug(logMessage, entry.metadata ?? '');
+        break;
+      case LogLevel.Info:
+        // eslint-disable-next-line no-console
+        console.info(logMessage, entry.metadata ?? '');
+        break;
+      case LogLevel.Warning:
+        // eslint-disable-next-line no-console
+        console.warn(logMessage, entry.metadata ?? '');
+        break;
+      case LogLevel.Error:
+      case LogLevel.Fault:
+        // eslint-disable-next-line no-console
+        console.error(logMessage, entry.metadata ?? '');
+        break;
+    }
+  }
+
+  flush(): void {
+    // Console doesn't need flushing
+  }
+}
+
+// ============================================================================
+// Event Destination (for public exposure)
+// ============================================================================
+
+/**
+ * Log event callback type
+ */
+export type LogEventCallback = (entry: LogEntry) => void;
+
+/**
+ * Event-based log destination for public log exposure
+ * Allows external consumers to subscribe to log events
+ */
+export class EventLogDestination implements LogDestination {
+  readonly identifier = 'event';
+  readonly name = 'Event Emitter';
+  readonly isAvailable = true;
+
+  private callbacks: Set<LogEventCallback> = new Set();
+
+  /**
+   * Subscribe to log events
+   * @returns Unsubscribe function
+   */
+  subscribe(callback: LogEventCallback): () => void {
+    this.callbacks.add(callback);
+    return () => {
+      this.callbacks.delete(callback);
+    };
+  }
+
+  write(entry: LogEntry): void {
+    for (const callback of this.callbacks) {
+      try {
+        callback(entry);
+      } catch {
+        // Ignore callback errors
+      }
+    }
+  }
+
+  flush(): void {
+    // No buffering
+  }
+}
+
+// ============================================================================
+// Logging Manager
+// ============================================================================
+
+/**
+ * Centralized logging manager with multiple destination support.
+ * Matches iOS: Logging class (central service)
+ */
+export class LoggingManager {
+  private static sharedInstance: LoggingManager | null = null;
+  private destinations: Map<string, LogDestination> = new Map();
+
+  // Configuration
+  private config: LoggingConfiguration;
+
+  // Default destinations
+  private readonly consoleDestination = new ConsoleLogDestination();
+  private readonly eventDestination = new EventLogDestination();
+
+  private constructor() {
+    // Initialize with default development config
+    this.config = getConfigurationForEnvironment(SDKEnvironment.Development);
+
+    // Add default console destination
+    this.addDestination(this.consoleDestination);
+    // Add event destination for public log exposure
+    this.addDestination(this.eventDestination);
+  }
+
+  // ============================================================================
+  // Configuration (matches iOS Logging.configure)
+  // ============================================================================
+
+  /**
+   * Get current configuration
+   */
+  public get configuration(): LoggingConfiguration {
+    return { ...this.config };
+  }
+
+  /**
+   * Configure the logging system.
+   * Matches iOS: Logging.configure(_ config: LoggingConfiguration)
+   *
+   * @param config - Partial configuration to apply
+   */
+  public configure(config: Partial<LoggingConfiguration>): void {
+    // If environment is specified, get defaults for that environment
+    if (config.environment && !config.minLogLevel) {
+      const envConfig = getConfigurationForEnvironment(config.environment);
+      this.config = { ...envConfig, ...config };
+    } else {
+      this.config = { ...this.config, ...config };
+    }
+
+    // Update console destination based on enableLocalLogging
+    if (!this.config.enableLocalLogging) {
+      this.removeDestination(this.consoleDestination.identifier);
+    } else if (!this.hasDestination(this.consoleDestination.identifier)) {
+      this.addDestination(this.consoleDestination);
+    }
+  }
+
+  /**
+   * Apply configuration for a specific environment.
+   * Matches iOS: Logging.applyEnvironmentConfiguration(_ environment:)
+   *
+   * @param environment - SDK environment
+   */
+  public applyEnvironmentConfiguration(environment: SDKEnvironment): void {
+    const envConfig = getConfigurationForEnvironment(environment);
+    this.configure(envConfig);
+  }
+
+  /**
+   * Set local logging enabled.
+   * Matches iOS: Logging.setLocalLoggingEnabled(_ enabled:)
+   */
+  public setLocalLoggingEnabled(enabled: boolean): void {
+    this.config.enableLocalLogging = enabled;
+    if (!enabled) {
+      this.removeDestination(this.consoleDestination.identifier);
+    } else if (!this.hasDestination(this.consoleDestination.identifier)) {
+      this.addDestination(this.consoleDestination);
+    }
+  }
+
+  /**
+   * Set minimum log level.
+   * Matches iOS: Logging.setMinLogLevel(_ level:)
+   */
+  public setMinLogLevel(level: LogLevel): void {
+    this.config.minLogLevel = level;
+  }
+
+  /**
+   * Set include device metadata.
+   * Matches iOS: Logging.setIncludeDeviceMetadata(_ include:)
+   */
+  public setIncludeDeviceMetadata(include: boolean): void {
+    this.config.includeDeviceMetadata = include;
+  }
+
+  /**
+   * Get shared instance
+   */
+  public static get shared(): LoggingManager {
+    if (!LoggingManager.sharedInstance) {
+      LoggingManager.sharedInstance = new LoggingManager();
+    }
+    return LoggingManager.sharedInstance;
+  }
+
+  /**
+   * Get current log level
+   * @deprecated Use configuration.minLogLevel instead
+   */
+  public getLogLevel(): LogLevel {
+    return this.config.minLogLevel;
+  }
+
+  // ============================================================================
+  // Destination Management (matches iOS)
+  // ============================================================================
+
+  /**
+   * Add a log destination
+   * Matches iOS: addDestination(_ destination: LogDestination)
+   */
+  public addDestination(destination: LogDestination): void {
+    this.destinations.set(destination.identifier, destination);
+  }
+
+  /**
+   * Remove a log destination
+   * Matches iOS: removeDestination(_ identifier: String)
+   */
+  public removeDestination(identifier: string): void {
+    this.destinations.delete(identifier);
+  }
+
+  /**
+   * Get all registered destinations
+   */
+  public getDestinations(): LogDestination[] {
+    return Array.from(this.destinations.values());
+  }
+
+  /**
+   * Check if a destination is registered
+   */
+  public hasDestination(identifier: string): boolean {
+    return this.destinations.has(identifier);
+  }
+
+  // ============================================================================
+  // Public Log Event Subscription
+  // ============================================================================
+
+  /**
+   * Subscribe to all log events (for public exposure)
+   * This allows consumers to receive log events for their own logging infrastructure.
+   * Matches iOS pattern of exposing log events.
+   *
+   * @param callback - Function called for each log entry
+   * @returns Unsubscribe function
+   */
+  public onLog(callback: LogEventCallback): () => void {
+    return this.eventDestination.subscribe(callback);
+  }
+
+  // ============================================================================
+  // Logging Operations
+  // ============================================================================
+
+  /**
+   * Log a message.
+   * Matches iOS: Logging.log(level:category:message:metadata:)
+   */
+  public log(
+    level: LogLevel,
+    category: string,
+    message: string,
+    metadata?: Record<string, unknown>
+  ): void {
+    // Filter by minimum log level
+    if (level < this.config.minLogLevel) {
+      return;
+    }
+
+    // Check if logging is enabled at all
+    if (!this.config.enableLocalLogging && this.destinations.size <= 1) {
+      // Only event destination, check if there are subscribers
+      return;
+    }
+
+    const entry: LogEntry = {
+      level,
+      category,
+      message,
+      metadata,
+      timestamp: new Date(),
+    };
+
+    // Write to all available destinations
+    for (const destination of this.destinations.values()) {
+      if (destination.isAvailable) {
+        try {
+          destination.write(entry);
+        } catch {
+          // Silently ignore destination errors
+        }
+      }
+    }
+  }
+
+  /**
+   * Flush all destinations
+   */
+  public flush(): void {
+    for (const destination of this.destinations.values()) {
+      try {
+        destination.flush();
+      } catch {
+        // Silently ignore flush errors
+      }
+    }
+  }
+}
+
+/**
+ * Get log level description
+ */
+function getLogLevelDescription(level: LogLevel): string {
+  switch (level) {
+    case LogLevel.Debug:
+      return 'DEBUG';
+    case LogLevel.Info:
+      return 'INFO';
+    case LogLevel.Warning:
+      return 'WARN';
+    case LogLevel.Error:
+      return 'ERROR';
+    case LogLevel.Fault:
+      return 'FAULT';
+  }
+}

package/src/Foundation/Logging/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Logging Module
+ *
+ * Centralized logging infrastructure with multiple destination support.
+ * Supports environment-based configuration and multiple log destinations (Console, Sentry, etc.)
+ *
+ * Matches iOS: sdk/runanywhere-swift/Sources/RunAnywhere/Infrastructure/Logging/
+ *
+ * Usage:
+ *   import { SDKLogger, LoggingManager, SDKEnvironment, SentryDestination } from '@runanywhere/core';
+ *
+ *   // Configure for production
+ *   LoggingManager.shared.applyEnvironmentConfiguration(SDKEnvironment.Production);
+ *
+ *   // Add Sentry destination (optional)
+ *   LoggingManager.shared.addDestination(new SentryDestination(Sentry));
+ *
+ *   // Use loggers
+ *   SDKLogger.llm.info('Model loaded', { modelId: 'llama-3.2' });
+ */
+
+// Logger
+export { SDKLogger } from './Logger/SDKLogger';
+
+// Log levels
+export { LogLevel, getLogLevelDescription } from './Models/LogLevel';
+
+// Configuration
+export {
+  type LoggingConfiguration,
+  SDKEnvironment,
+  developmentConfig,
+  stagingConfig,
+  productionConfig,
+  getConfigurationForEnvironment,
+  createLoggingConfiguration,
+} from './Models/LoggingConfiguration';
+
+// Logging manager with destinations
+export {
+  LoggingManager,
+  ConsoleLogDestination,
+  EventLogDestination,
+  type LogDestination,
+  type LogEntry,
+  type LogEventCallback,
+} from './Services/LoggingManager';
+
+// Sentry destination
+export {
+  SentryDestination,
+  type SentryInterface,
+} from './Destinations/SentryDestination';
+
+// Native log bridge (for receiving logs from iOS/Android)
+export {
+  NativeLogBridge,
+  type NativeLogEntryData,
+} from './Destinations/NativeLogBridge';

package/src/Foundation/Security/DeviceIdentity.ts

@@ -0,0 +1,92 @@
+/**
+ * DeviceIdentity.ts
+ *
+ * Simple utility for device identity management (UUID persistence)
+ *
+ * Provides persistent UUID that survives app reinstalls by storing in:
+ * - iOS: Keychain
+ * - Android: Keystore/EncryptedSharedPreferences
+ *
+ * Reference: sdk/runanywhere-swift/Sources/RunAnywhere/Infrastructure/Device/Services/DeviceIdentity.swift
+ */
+
+import { requireNativeModule } from '../../native';
+import { SDKLogger } from '../Logging/Logger/SDKLogger';
+
+const logger = new SDKLogger('DeviceIdentity');
+
+/**
+ * Cached UUID (matches Swift pattern - avoid repeated native calls)
+ */
+let cachedUUID: string | null = null;
+
+/**
+ * DeviceIdentity - Persistent device UUID management
+ *
+ * Matches Swift's DeviceIdentity enum pattern:
+ * - Uses keychain/keystore for persistence (survives reinstalls)
+ * - Caches result after first access
+ * - Falls back to UUID generation if needed
+ */
+export const DeviceIdentity = {
+  /**
+   * Get a persistent device UUID that survives app reinstalls
+   *
+   * Strategy (matches Swift):
+   * 1. Return cached value if available (fast path)
+   * 2. Try to get from keychain (native call)
+   * 3. If not found, native will generate and store
+   *
+   * @returns Promise<string> Persistent device UUID
+   */
+  async getPersistentUUID(): Promise<string> {
+    // Fast path: return cached value
+    if (cachedUUID) {
+      return cachedUUID;
+    }
+
+    try {
+      const native = requireNativeModule();
+      const uuid = await native.getPersistentDeviceUUID();
+
+      if (uuid && uuid.length > 0) {
+        cachedUUID = uuid;
+        logger.debug('Got persistent device UUID from native');
+        return uuid;
+      }
+
+      throw new Error('Native returned empty UUID');
+    } catch (error) {
+      logger.error('Failed to get persistent device UUID', { error });
+      throw error;
+    }
+  },
+
+  /**
+   * Get the cached UUID if available (synchronous)
+   *
+   * @returns Cached UUID or null if not yet loaded
+   */
+  getCachedUUID(): string | null {
+    return cachedUUID;
+  },
+
+  /**
+   * Clear the cached UUID (for testing)
+   */
+  clearCache(): void {
+    cachedUUID = null;
+  },
+
+  /**
+   * Validate if a device UUID is properly formatted
+   *
+   * @param uuid UUID string to validate
+   * @returns true if valid UUID format
+   */
+  validateUUID(uuid: string): boolean {
+    // UUID format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx (36 chars)
+    return uuid.length === 36 && uuid.includes('-');
+  },
+};
+

package/src/Foundation/Security/SecureStorageError.ts

@@ -0,0 +1,132 @@
+/**
+ * SecureStorageError.ts
+ *
+ * Errors for secure storage operations
+ *
+ * Reference: sdk/runanywhere-swift/Sources/RunAnywhere/Foundation/Security/KeychainManager.swift
+ */
+
+/**
+ * Error codes for secure storage operations
+ */
+export enum SecureStorageErrorCode {
+  EncodingError = 'SECURE_STORAGE_ENCODING_ERROR',
+  DecodingError = 'SECURE_STORAGE_DECODING_ERROR',
+  ItemNotFound = 'SECURE_STORAGE_ITEM_NOT_FOUND',
+  StorageError = 'SECURE_STORAGE_STORAGE_ERROR',
+  RetrievalError = 'SECURE_STORAGE_RETRIEVAL_ERROR',
+  DeletionError = 'SECURE_STORAGE_DELETION_ERROR',
+  UnavailableError = 'SECURE_STORAGE_UNAVAILABLE',
+}
+
+/**
+ * Secure storage error
+ *
+ * Matches iOS KeychainError enum.
+ */
+export class SecureStorageError extends Error {
+  readonly code: SecureStorageErrorCode;
+  readonly underlyingError?: Error;
+
+  constructor(
+    code: SecureStorageErrorCode,
+    message?: string,
+    underlyingError?: Error
+  ) {
+    const msg = message ?? SecureStorageError.defaultMessage(code);
+    super(msg);
+    this.name = 'SecureStorageError';
+    this.code = code;
+    this.underlyingError = underlyingError;
+  }
+
+  private static defaultMessage(code: SecureStorageErrorCode): string {
+    switch (code) {
+      case SecureStorageErrorCode.EncodingError:
+        return 'Failed to encode data for secure storage';
+      case SecureStorageErrorCode.DecodingError:
+        return 'Failed to decode data from secure storage';
+      case SecureStorageErrorCode.ItemNotFound:
+        return 'Item not found in secure storage';
+      case SecureStorageErrorCode.StorageError:
+        return 'Failed to store item in secure storage';
+      case SecureStorageErrorCode.RetrievalError:
+        return 'Failed to retrieve item from secure storage';
+      case SecureStorageErrorCode.DeletionError:
+        return 'Failed to delete item from secure storage';
+      case SecureStorageErrorCode.UnavailableError:
+        return 'Secure storage is not available';
+    }
+  }
+
+  // Factory methods
+  static encodingError(underlyingError?: Error): SecureStorageError {
+    return new SecureStorageError(
+      SecureStorageErrorCode.EncodingError,
+      undefined,
+      underlyingError
+    );
+  }
+
+  static decodingError(underlyingError?: Error): SecureStorageError {
+    return new SecureStorageError(
+      SecureStorageErrorCode.DecodingError,
+      undefined,
+      underlyingError
+    );
+  }
+
+  static itemNotFound(key: string): SecureStorageError {
+    return new SecureStorageError(
+      SecureStorageErrorCode.ItemNotFound,
+      `Item not found in secure storage: ${key}`
+    );
+  }
+
+  static storageError(underlyingError?: Error): SecureStorageError {
+    return new SecureStorageError(
+      SecureStorageErrorCode.StorageError,
+      undefined,
+      underlyingError
+    );
+  }
+
+  static retrievalError(underlyingError?: Error): SecureStorageError {
+    return new SecureStorageError(
+      SecureStorageErrorCode.RetrievalError,
+      undefined,
+      underlyingError
+    );
+  }
+
+  static deletionError(underlyingError?: Error): SecureStorageError {
+    return new SecureStorageError(
+      SecureStorageErrorCode.DeletionError,
+      undefined,
+      underlyingError
+    );
+  }
+
+  static unavailable(): SecureStorageError {
+    return new SecureStorageError(SecureStorageErrorCode.UnavailableError);
+  }
+}
+
+/**
+ * Type guard to check if an error is a SecureStorageError
+ */
+export function isSecureStorageError(
+  error: unknown
+): error is SecureStorageError {
+  return error instanceof SecureStorageError;
+}
+
+/**
+ * Type guard to check if error is "item not found" specifically
+ */
+export function isItemNotFoundError(error: unknown): boolean {
+  return (
+    isSecureStorageError(error) &&
+    error.code === SecureStorageErrorCode.ItemNotFound
+  );
+}