@runanywhere/core 0.16.0

package/src/Foundation/Security/SecureStorageKeys.ts

@@ -0,0 +1,35 @@
+/**
+ * SecureStorageKeys.ts
+ *
+ * Keychain/secure storage key constants
+ *
+ * Reference: sdk/runanywhere-swift/Sources/RunAnywhere/Foundation/Security/KeychainManager.swift
+ */
+
+/**
+ * Keys for secure storage (keychain on iOS, keystore on Android)
+ *
+ * These match the iOS KeychainKey enum values exactly.
+ */
+export const SecureStorageKeys = {
+  // SDK Core
+  apiKey: 'com.runanywhere.sdk.apiKey',
+  baseURL: 'com.runanywhere.sdk.baseURL',
+  environment: 'com.runanywhere.sdk.environment',
+
+  // Device Identity
+  deviceUUID: 'com.runanywhere.sdk.device.uuid',
+
+  // Authentication Tokens
+  accessToken: 'com.runanywhere.sdk.accessToken',
+  refreshToken: 'com.runanywhere.sdk.refreshToken',
+  tokenExpiresAt: 'com.runanywhere.sdk.tokenExpiresAt',
+
+  // User/Org Identity
+  deviceId: 'com.runanywhere.sdk.deviceId',
+  userId: 'com.runanywhere.sdk.userId',
+  organizationId: 'com.runanywhere.sdk.organizationId',
+} as const;
+
+export type SecureStorageKey =
+  (typeof SecureStorageKeys)[keyof typeof SecureStorageKeys];

package/src/Foundation/Security/SecureStorageService.ts

@@ -0,0 +1,449 @@
+/**
+ * SecureStorageService.ts
+ *
+ * Secure storage abstraction for React Native
+ *
+ * This service provides secure key-value storage that uses:
+ * - iOS: Keychain (via native module)
+ * - Android: Keystore (via native module)
+ *
+ * In React Native, actual secure storage is delegated to the native layer.
+ * This TS layer provides type-safe APIs and caching.
+ *
+ * Reference: sdk/runanywhere-swift/Sources/RunAnywhere/Foundation/Security/KeychainManager.swift
+ */
+
+import { requireNativeModule } from '../../native';
+import { SDKLogger } from '../Logging/Logger/SDKLogger';
+import { SecureStorageError, isItemNotFoundError } from './SecureStorageError';
+import { SecureStorageKeys, type SecureStorageKey } from './SecureStorageKeys';
+import type { SDKInitParams } from '../Initialization';
+import type { SDKEnvironment } from '../../types';
+
+/**
+ * Extended native module type for secure storage methods
+ * These methods are optional and may not be available on all platforms
+ */
+interface SecureStorageNativeModule {
+  secureStorageIsAvailable?: () => Promise<boolean>;
+  secureStorageStore?: (key: string, value: string) => Promise<void>;
+  secureStorageRetrieve?: (key: string) => Promise<string | null>;
+  secureStorageDelete?: (key: string) => Promise<void>;
+  secureStorageExists?: (key: string) => Promise<boolean>;
+}
+
+/**
+ * Secure storage service
+ *
+ * Provides secure key-value storage matching iOS KeychainManager.
+ * All actual storage is delegated to the native layer.
+ */
+class SecureStorageServiceImpl {
+  private readonly logger = new SDKLogger('SecureStorageService');
+
+  // In-memory cache for frequently accessed values
+  private cache: Map<string, string> = new Map();
+
+  // Flag to track if native storage is available
+  private _isAvailable: boolean | null = null;
+
+  /**
+   * Check if secure storage is available
+   *
+   * Secure storage uses platform-native storage:
+   * - iOS: Keychain (always available)
+   * - Android: Keystore/EncryptedSharedPreferences (always available)
+   */
+  async isAvailable(): Promise<boolean> {
+    if (this._isAvailable !== null) {
+      return this._isAvailable;
+    }
+
+    try {
+      const native = requireNativeModule();
+      // Verify native module is available by checking for secure storage methods
+      // The methods are implemented in C++ and use platform callbacks
+      this._isAvailable =
+        typeof native.secureStorageSet === 'function' &&
+        typeof native.secureStorageGet === 'function';
+      return this._isAvailable;
+    } catch {
+      this._isAvailable = false;
+      return false;
+    }
+  }
+
+  // ============================================================
+  // Generic Storage Methods
+  // ============================================================
+
+  /**
+   * Store a string value securely
+   *
+   * Uses native secure storage:
+   * - iOS: Keychain
+   * - Android: Keystore/EncryptedSharedPreferences
+   *
+   * @param value - String value to store
+   * @param key - Storage key
+   */
+  async store(value: string, key: SecureStorageKey | string): Promise<void> {
+    try {
+      const native = requireNativeModule() as unknown as SecureStorageNativeModule;
+
+      // Use the new native method
+      const success = await native.secureStorageSet(key, value);
+
+      if (!success) {
+        throw new Error(`Native secureStorageSet returned false for key: ${key}`);
+      }
+
+      // Update cache
+      this.cache.set(key, value);
+      this.logger.debug(`Stored value for key: ${key}`);
+    } catch (error) {
+      this.logger.error(`Failed to store value for key: ${key}`, { error });
+      throw SecureStorageError.storageError(
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Retrieve a string value from secure storage
+   *
+   * Uses native secure storage:
+   * - iOS: Keychain
+   * - Android: Keystore/EncryptedSharedPreferences
+   *
+   * @param key - Storage key
+   * @returns Stored value or null if not found
+   */
+  async retrieve(key: SecureStorageKey | string): Promise<string | null> {
+    // Check cache first
+    const cached = this.cache.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    try {
+      const native = requireNativeModule() as unknown as SecureStorageNativeModule;
+
+      // Use the new native method
+      const value = await native.secureStorageGet(key);
+
+      if (value !== null && value !== undefined) {
+        this.cache.set(key, value);
+      }
+      return value ?? null;
+    } catch (error) {
+      // Item not found is not an error - just return null
+      if (isItemNotFoundError(error)) {
+        return null;
+      }
+
+      this.logger.error(`Failed to retrieve value for key: ${key}`, { error });
+      throw SecureStorageError.retrievalError(
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Delete a value from secure storage
+   *
+   * Uses native secure storage:
+   * - iOS: Keychain
+   * - Android: Keystore/EncryptedSharedPreferences
+   *
+   * @param key - Storage key
+   */
+  async delete(key: SecureStorageKey | string): Promise<void> {
+    try {
+      const native = requireNativeModule() as unknown as SecureStorageNativeModule;
+
+      // Use the new native method
+      await native.secureStorageDelete(key);
+
+      // Remove from cache
+      this.cache.delete(key);
+      this.logger.debug(`Deleted value for key: ${key}`);
+    } catch (error) {
+      // Ignore "not found" errors on delete
+      if (!isItemNotFoundError(error)) {
+        this.logger.error(`Failed to delete value for key: ${key}`, { error });
+        throw SecureStorageError.deletionError(
+          error instanceof Error ? error : undefined
+        );
+      }
+    }
+  }
+
+  /**
+   * Check if a key exists in secure storage
+   *
+   * Uses native secure storage:
+   * - iOS: Keychain
+   * - Android: Keystore/EncryptedSharedPreferences
+   *
+   * @param key - Storage key
+   * @returns True if key exists
+   */
+  async exists(key: SecureStorageKey | string): Promise<boolean> {
+    // Check cache first
+    if (this.cache.has(key)) {
+      return true;
+    }
+
+    try {
+      const native = requireNativeModule() as unknown as SecureStorageNativeModule;
+
+      // Use the new native method
+      return await native.secureStorageExists(key);
+    } catch {
+      return false;
+    }
+  }
+
+  // ============================================================
+  // SDK Parameters Storage (matching iOS KeychainManager)
+  // ============================================================
+
+  /**
+   * Store SDK initialization parameters
+   *
+   * @param params - SDK init params
+   */
+  async storeSDKParams(params: SDKInitParams): Promise<void> {
+    const promises: Promise<void>[] = [];
+
+    if (params.apiKey) {
+      promises.push(this.store(params.apiKey, SecureStorageKeys.apiKey));
+    }
+    if (params.baseURL) {
+      promises.push(this.store(params.baseURL, SecureStorageKeys.baseURL));
+    }
+    promises.push(this.store(params.environment, SecureStorageKeys.environment));
+
+    await Promise.all(promises);
+    this.logger.info('SDK parameters stored securely');
+  }
+
+  /**
+   * Retrieve stored SDK parameters
+   *
+   * @returns Stored SDK params or null if not found
+   */
+  async retrieveSDKParams(): Promise<SDKInitParams | null> {
+    const [apiKey, baseURL, environment] = await Promise.all([
+      this.retrieve(SecureStorageKeys.apiKey),
+      this.retrieve(SecureStorageKeys.baseURL),
+      this.retrieve(SecureStorageKeys.environment),
+    ]);
+
+    if (!apiKey || !baseURL || !environment) {
+      this.logger.debug('No stored SDK parameters found');
+      return null;
+    }
+
+    this.logger.debug('Retrieved SDK parameters from secure storage');
+    return {
+      apiKey,
+      baseURL,
+      environment: environment as SDKEnvironment,
+    };
+  }
+
+  /**
+   * Clear stored SDK parameters
+   */
+  async clearSDKParams(): Promise<void> {
+    await Promise.all([
+      this.delete(SecureStorageKeys.apiKey),
+      this.delete(SecureStorageKeys.baseURL),
+      this.delete(SecureStorageKeys.environment),
+    ]);
+    this.logger.info('SDK parameters cleared from secure storage');
+  }
+
+  // ============================================================
+  // Device Identity Storage
+  // ============================================================
+
+  /**
+   * Store device UUID
+   *
+   * @param uuid - Device UUID
+   */
+  async storeDeviceUUID(uuid: string): Promise<void> {
+    await this.store(uuid, SecureStorageKeys.deviceUUID);
+    this.logger.debug('Device UUID stored');
+  }
+
+  /**
+   * Retrieve device UUID
+   *
+   * @returns Stored device UUID or null
+   */
+  async retrieveDeviceUUID(): Promise<string | null> {
+    return this.retrieve(SecureStorageKeys.deviceUUID);
+  }
+
+  // ============================================================
+  // Authentication Token Storage
+  // ============================================================
+
+  /**
+   * Store authentication tokens
+   *
+   * @param accessToken - Access token
+   * @param refreshToken - Refresh token
+   * @param expiresAt - Token expiration timestamp (Unix ms)
+   */
+  async storeAuthTokens(
+    accessToken: string,
+    refreshToken: string,
+    expiresAt: number
+  ): Promise<void> {
+    await Promise.all([
+      this.store(accessToken, SecureStorageKeys.accessToken),
+      this.store(refreshToken, SecureStorageKeys.refreshToken),
+      this.store(expiresAt.toString(), SecureStorageKeys.tokenExpiresAt),
+    ]);
+    this.logger.debug('Auth tokens stored');
+  }
+
+  /**
+   * Retrieve stored auth tokens
+   *
+   * @returns Stored tokens or null if not found
+   */
+  async retrieveAuthTokens(): Promise<{
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+  } | null> {
+    const [accessToken, refreshToken, expiresAtStr] = await Promise.all([
+      this.retrieve(SecureStorageKeys.accessToken),
+      this.retrieve(SecureStorageKeys.refreshToken),
+      this.retrieve(SecureStorageKeys.tokenExpiresAt),
+    ]);
+
+    if (!accessToken || !refreshToken) {
+      return null;
+    }
+
+    const expiresAt = expiresAtStr ? parseInt(expiresAtStr, 10) : 0;
+    return { accessToken, refreshToken, expiresAt };
+  }
+
+  /**
+   * Clear stored auth tokens
+   */
+  async clearAuthTokens(): Promise<void> {
+    await Promise.all([
+      this.delete(SecureStorageKeys.accessToken),
+      this.delete(SecureStorageKeys.refreshToken),
+      this.delete(SecureStorageKeys.tokenExpiresAt),
+    ]);
+    this.logger.debug('Auth tokens cleared');
+  }
+
+  // ============================================================
+  // Identity Storage
+  // ============================================================
+
+  /**
+   * Store identity information
+   *
+   * @param deviceId - Device ID from backend
+   * @param userId - User ID (optional)
+   * @param organizationId - Organization ID
+   */
+  async storeIdentity(
+    deviceId: string,
+    organizationId: string,
+    userId?: string
+  ): Promise<void> {
+    const promises = [
+      this.store(deviceId, SecureStorageKeys.deviceId),
+      this.store(organizationId, SecureStorageKeys.organizationId),
+    ];
+
+    if (userId) {
+      promises.push(this.store(userId, SecureStorageKeys.userId));
+    }
+
+    await Promise.all(promises);
+    this.logger.debug('Identity info stored');
+  }
+
+  /**
+   * Retrieve stored identity
+   *
+   * @returns Stored identity or null
+   */
+  async retrieveIdentity(): Promise<{
+    deviceId: string;
+    userId?: string;
+    organizationId: string;
+  } | null> {
+    const [deviceId, userId, organizationId] = await Promise.all([
+      this.retrieve(SecureStorageKeys.deviceId),
+      this.retrieve(SecureStorageKeys.userId),
+      this.retrieve(SecureStorageKeys.organizationId),
+    ]);
+
+    if (!deviceId || !organizationId) {
+      return null;
+    }
+
+    return {
+      deviceId,
+      userId: userId ?? undefined,
+      organizationId,
+    };
+  }
+
+  /**
+   * Clear all stored identity info
+   */
+  async clearIdentity(): Promise<void> {
+    await Promise.all([
+      this.delete(SecureStorageKeys.deviceId),
+      this.delete(SecureStorageKeys.userId),
+      this.delete(SecureStorageKeys.organizationId),
+    ]);
+    this.logger.debug('Identity info cleared');
+  }
+
+  // ============================================================
+  // Utility
+  // ============================================================
+
+  /**
+   * Clear all cached values
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Clear all stored data (for logout/reset)
+   */
+  async clearAll(): Promise<void> {
+    await Promise.all([
+      this.clearSDKParams(),
+      this.clearAuthTokens(),
+      this.clearIdentity(),
+      this.delete(SecureStorageKeys.deviceUUID),
+    ]);
+    this.clearCache();
+    this.logger.info('All secure storage cleared');
+  }
+}
+
+/**
+ * Singleton instance
+ */
+export const SecureStorageService = new SecureStorageServiceImpl();

package/src/Foundation/Security/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Security Module
+ *
+ * Secure storage and credential management
+ *
+ * Reference: sdk/runanywhere-swift/Sources/RunAnywhere/Foundation/Security/
+ */
+
+export { SecureStorageService } from './SecureStorageService';
+export { SecureStorageKeys, type SecureStorageKey } from './SecureStorageKeys';
+export {
+  SecureStorageError,
+  SecureStorageErrorCode,
+  isSecureStorageError,
+  isItemNotFoundError,
+} from './SecureStorageError';
+export { DeviceIdentity } from './DeviceIdentity';

package/src/Foundation/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Foundation Module
+ *
+ * Core infrastructure for the SDK.
+ * Matches iOS SDK: Foundation/
+ */
+
+// Constants
+export { SDKConstants } from './Constants';
+
+// Error Types
+export * from './ErrorTypes';
+
+// Initialization
+export * from './Initialization';
+
+// Security
+export * from './Security';
+
+// Dependency Injection
+export * from './DependencyInjection';
+
+// Logging
+export { SDKLogger } from './Logging/Logger/SDKLogger';
+export { LogLevel } from './Logging/Models/LogLevel';
+export { LoggingManager } from './Logging/Services/LoggingManager';

package/src/Infrastructure/Events/EventPublisher.ts

@@ -0,0 +1,165 @@
+/**
+ * EventPublisher
+ *
+ * Single entry point for all SDK event tracking.
+ * Routes events to EventBus for public consumption.
+ * Analytics/telemetry is now handled by native commons.
+ *
+ * Reference: sdk/runanywhere-swift/Sources/RunAnywhere/Infrastructure/Events/EventPublisher.swift
+ */
+
+import { EventDestination, type SDKEvent } from './SDKEvent';
+import { EventBus } from '../../Public/Events/EventBus';
+import type { AnySDKEvent } from '../../types/events';
+import { SDKLogger } from '../../Foundation/Logging/Logger/SDKLogger';
+
+const logger = new SDKLogger('EventPublisher');
+
+// ============================================================================
+// EventPublisher Class
+// ============================================================================
+
+/**
+ * Central event publisher that routes SDK events to appropriate destinations.
+ *
+ * Design:
+ * - Single entry point for all event tracking in the SDK
+ * - Routes to EventBus for public events
+ * - Analytics/telemetry is handled by native commons
+ *
+ * Usage:
+ * ```typescript
+ * // Track an event
+ * EventPublisher.shared.track(myEvent);
+ * ```
+ */
+class EventPublisherImpl {
+  private isInitialized = false;
+
+  /**
+   * Initialize the publisher.
+   * Should be called during SDK startup.
+   */
+  initialize(): void {
+    this.isInitialized = true;
+    logger.debug('EventPublisher initialized');
+  }
+
+  /**
+   * Check if the publisher is initialized.
+   */
+  get initialized(): boolean {
+    return this.isInitialized;
+  }
+
+  /**
+   * Track an event synchronously.
+   * Routes to EventBus based on event.destination.
+   *
+   * @param event - The SDK event to track
+   */
+  track(event: SDKEvent): void {
+    const destination = event.destination;
+
+    // Route to EventBus (public) - unless analyticsOnly
+    if (destination !== EventDestination.AnalyticsOnly) {
+      this.publishToEventBus(event);
+    }
+
+    // Analytics events are now handled by native commons via
+    // the rac_* API - no JS-side analytics queue needed
+  }
+
+  /**
+   * Track an event asynchronously.
+   * Use this in async contexts.
+   *
+   * @param event - The SDK event to track
+   */
+  async trackAsync(event: SDKEvent): Promise<void> {
+    this.track(event);
+  }
+
+  /**
+   * Track multiple events at once.
+   *
+   * @param events - Array of SDK events to track
+   */
+  trackBatch(events: SDKEvent[]): void {
+    for (const event of events) {
+      this.track(event);
+    }
+  }
+
+  /**
+   * Publish an event to the EventBus for public consumption.
+   */
+  private publishToEventBus(event: SDKEvent): void {
+    // Map category to native event type for EventBus
+    const eventTypeMap: Record<string, string> = {
+      sdk: 'Initialization',
+      model: 'Model',
+      llm: 'Generation',
+      stt: 'Voice',
+      tts: 'Voice',
+      voice: 'Voice',
+      storage: 'Storage',
+      device: 'Device',
+      network: 'Network',
+      error: 'Initialization', // Errors go through initialization channel
+    };
+
+    const eventType = eventTypeMap[event.category] ?? 'Model';
+
+    // Create a simplified event object for EventBus
+    // EventBus expects events with { type: string, ...properties }
+    const busEvent = {
+      type: event.type,
+      timestamp: event.timestamp.toISOString(),
+      ...event.properties,
+    } as AnySDKEvent;
+
+    EventBus.publish(eventType, busEvent);
+  }
+
+  /**
+   * Flush all pending analytics events.
+   * No-op since analytics is now in native commons.
+   */
+  async flush(): Promise<void> {
+    // Analytics flushing is handled by native commons
+  }
+
+  /**
+   * Reset the publisher state.
+   * Primarily used for testing.
+   */
+  reset(): void {
+    this.isInitialized = false;
+  }
+}
+
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+
+/**
+ * Shared EventPublisher singleton.
+ *
+ * Usage:
+ * ```typescript
+ * import { EventPublisher } from './Infrastructure/Events';
+ *
+ * // Initialize once during SDK startup
+ * EventPublisher.shared.initialize();
+ *
+ * // Track events anywhere in the SDK
+ * EventPublisher.shared.track(myEvent);
+ * ```
+ */
+export const EventPublisher = {
+  /** Singleton instance */
+  shared: new EventPublisherImpl(),
+};
+
+export type { EventPublisherImpl };