@oxyhq/core 1.0.0

package/src/utils/cache.ts

@@ -0,0 +1,264 @@
+/**
+ * Centralized cache utility with TTL support
+ * 
+ * This is a production-ready cache implementation used across the codebase
+ * for consistent caching behavior and performance optimization.
+ */
+
+/**
+ * Cache entry with expiration tracking
+ */
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  expiresAt: number;
+}
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+  size: number;
+  hits: number;
+  misses: number;
+  hitRate: number;
+}
+
+/**
+ * TTL-based cache implementation
+ * 
+ * Features:
+ * - Automatic expiration based on TTL
+ * - Manual cleanup of expired entries
+ * - Statistics tracking (hits, misses, hit rate)
+ * - Type-safe generic interface
+ * 
+ * @example
+ * ```typescript
+ * const cache = new TTLCache<string>(5 * 60 * 1000); // 5 minutes
+ * 
+ * // Set with default TTL
+ * cache.set('key', 'value');
+ * 
+ * // Set with custom TTL
+ * cache.set('key', 'value', 10 * 60 * 1000); // 10 minutes
+ * 
+ * // Get value
+ * const value = cache.get('key');
+ * 
+ * // Get statistics
+ * const stats = cache.getStats();
+ * ```
+ */
+export class TTLCache<T> {
+  private cache = new Map<string, CacheEntry<T>>();
+  private defaultTTL: number;
+  private hits = 0;
+  private misses = 0;
+
+  /**
+   * Create a new TTL cache
+   * @param defaultTTL Default TTL in milliseconds (default: 5 minutes)
+   */
+  constructor(defaultTTL: number = 5 * 60 * 1000) {
+    this.defaultTTL = defaultTTL;
+  }
+
+  /**
+   * Get a value from cache
+   * @param key Cache key
+   * @returns Cached value or null if not found or expired
+   */
+  get(key: string): T | null {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      this.misses++;
+      return null;
+    }
+
+    const now = Date.now();
+    if (now > entry.expiresAt) {
+      this.cache.delete(key);
+      this.misses++;
+      return null;
+    }
+
+    this.hits++;
+    return entry.data;
+  }
+
+  /**
+   * Set a value in cache
+   * @param key Cache key
+   * @param data Data to cache
+   * @param ttl Optional TTL override (uses default if not provided)
+   */
+  set(key: string, data: T, ttl?: number): void {
+    const now = Date.now();
+    const expiresAt = now + (ttl || this.defaultTTL);
+    this.cache.set(key, { data, timestamp: now, expiresAt });
+  }
+
+  /**
+   * Delete a specific cache entry
+   * @param key Cache key
+   * @returns true if entry was deleted, false if not found
+   */
+  delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear(): void {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+  }
+
+  /**
+   * Check if a key exists and is not expired
+   * @param key Cache key
+   * @returns true if key exists and is valid
+   */
+  has(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get all valid cache keys
+   * @returns Array of valid cache keys
+   */
+  keys(): string[] {
+    const now = Date.now();
+    const validKeys: string[] = [];
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (now <= entry.expiresAt) {
+        validKeys.push(key);
+      } else {
+        this.cache.delete(key);
+      }
+    }
+
+    return validKeys;
+  }
+
+  /**
+   * Clean up expired entries
+   * @returns Number of entries removed
+   */
+  cleanup(): number {
+    const now = Date.now();
+    let removed = 0;
+
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiresAt) {
+        this.cache.delete(key);
+        removed++;
+      }
+    }
+
+    return removed;
+  }
+
+  /**
+   * Get cache size (number of entries)
+   */
+  size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): CacheStats {
+    const total = this.hits + this.misses;
+    return {
+      size: this.cache.size,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? this.hits / total : 0,
+    };
+  }
+
+  /**
+   * Reset statistics (keeps cache entries)
+   */
+  resetStats(): void {
+    this.hits = 0;
+    this.misses = 0;
+  }
+}
+
+/**
+ * Create a TTL cache instance (convenience function)
+ * 
+ * @example
+ * ```typescript
+ * const cache = createCache<string>(5 * 60 * 1000);
+ * ```
+ */
+export function createCache<T>(ttl: number = 5 * 60 * 1000): TTLCache<T> {
+  return new TTLCache<T>(ttl);
+}
+
+/**
+ * Global cache cleanup interval (runs every minute)
+ * This helps prevent memory leaks from expired cache entries
+ */
+let cleanupInterval: ReturnType<typeof setInterval> | null = null;
+const activeCaches = new Set<TTLCache<any>>();
+
+/**
+ * Register a cache for automatic cleanup
+ * @param cache Cache instance to register
+ */
+export function registerCacheForCleanup(cache: TTLCache<any>): void {
+  activeCaches.add(cache);
+
+  // Start cleanup interval if not already running
+  if (!cleanupInterval) {
+    cleanupInterval = setInterval(() => {
+      for (const cache of activeCaches) {
+        cache.cleanup();
+      }
+    }, 60000); // Every minute
+  }
+}
+
+/**
+ * Unregister a cache from automatic cleanup
+ * @param cache Cache instance to unregister
+ */
+export function unregisterCacheFromCleanup(cache: TTLCache<any>): void {
+  activeCaches.delete(cache);
+
+  // Stop cleanup interval if no caches are registered
+  if (activeCaches.size === 0 && cleanupInterval) {
+    clearInterval(cleanupInterval);
+    cleanupInterval = null;
+  }
+}
+
+/**
+ * Stop all cleanup intervals (useful for testing)
+ * This will clear the interval and unregister all caches
+ */
+export function stopAllCleanupIntervals(): void {
+  if (cleanupInterval) {
+    clearInterval(cleanupInterval);
+    cleanupInterval = null;
+  }
+  activeCaches.clear();
+}
+

package/src/utils/deviceManager.ts

@@ -0,0 +1,198 @@
+export interface DeviceFingerprint {
+  userAgent: string;
+  platform: string;
+  language?: string;
+  timezone?: string;
+  screen?: {
+    width: number;
+    height: number;
+    colorDepth: number;
+  };
+}
+
+export interface StoredDeviceInfo {
+  deviceId: string;
+  deviceName?: string;
+  fingerprint?: string;
+  createdAt: string;
+  lastUsed: string;
+}
+
+/**
+ * Client-side device management utility
+ * Handles persistent device identification across app sessions
+ */
+export class DeviceManager {
+  private static DEVICE_KEY = 'oxy_device_info';
+  
+  /**
+   * Check if we're in React Native environment
+   */
+  private static isReactNative(): boolean {
+    return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+  }
+  
+  /**
+   * Get appropriate storage for the platform
+   */
+  private static async getStorage(): Promise<{
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+  }> {
+    if (this.isReactNative()) {
+      try {
+        const asyncStorageModule = await import('@react-native-async-storage/async-storage');
+        const storage = (asyncStorageModule.default as unknown) as import('@react-native-async-storage/async-storage').AsyncStorageStatic;
+        return {
+          getItem: storage.getItem.bind(storage),
+          setItem: storage.setItem.bind(storage),
+          removeItem: storage.removeItem.bind(storage),
+        };
+      } catch (error) {
+        console.error('AsyncStorage not available in React Native:', error);
+        throw new Error('AsyncStorage is required in React Native environment');
+      }
+    } else {
+      // Use localStorage for web
+      return {
+        getItem: async (key: string) => localStorage.getItem(key),
+        setItem: async (key: string, value: string) => localStorage.setItem(key, value),
+        removeItem: async (key: string) => localStorage.removeItem(key)
+      };
+    }
+  }
+  
+  /**
+   * Get or create device fingerprint for current device
+   */
+  static getDeviceFingerprint(): DeviceFingerprint {
+    const fingerprint: DeviceFingerprint = {
+      userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'unknown',
+      platform: typeof navigator !== 'undefined' ? navigator.platform : 'unknown',
+      language: typeof navigator !== 'undefined' ? navigator.language : undefined,
+      timezone: typeof Intl !== 'undefined' ? Intl.DateTimeFormat().resolvedOptions().timeZone : undefined,
+    };
+
+    // Add screen info if available
+    if (typeof screen !== 'undefined') {
+      fingerprint.screen = {
+        width: screen.width,
+        height: screen.height,
+        colorDepth: screen.colorDepth
+      };
+    }
+
+    return fingerprint;
+  }
+
+  /**
+   * Get stored device info or create new one
+   */
+  static async getDeviceInfo(): Promise<StoredDeviceInfo> {
+    try {
+      const storage = await this.getStorage();
+      const stored = await storage.getItem(this.DEVICE_KEY);
+      
+      if (stored) {
+        const deviceInfo: StoredDeviceInfo = JSON.parse(stored);
+        
+        // Update last used timestamp
+        deviceInfo.lastUsed = new Date().toISOString();
+        await this.saveDeviceInfo(deviceInfo);
+        
+        return deviceInfo;
+      }
+      
+      // Create new device info
+      return await this.createNewDeviceInfo();
+    } catch (error) {
+      console.error('Error getting device info:', error);
+      return await this.createNewDeviceInfo();
+    }
+  }
+
+  /**
+   * Create new device info and store it
+   */
+  static async createNewDeviceInfo(): Promise<StoredDeviceInfo> {
+    const deviceInfo: StoredDeviceInfo = {
+      deviceId: this.generateDeviceId(),
+      fingerprint: JSON.stringify(this.getDeviceFingerprint()),
+      createdAt: new Date().toISOString(),
+      lastUsed: new Date().toISOString()
+    };
+
+    await this.saveDeviceInfo(deviceInfo);
+    return deviceInfo;
+  }
+
+  /**
+   * Save device info to storage
+   */
+  static async saveDeviceInfo(deviceInfo: StoredDeviceInfo): Promise<void> {
+    try {
+      const storage = await this.getStorage();
+      await storage.setItem(this.DEVICE_KEY, JSON.stringify(deviceInfo));
+    } catch (error) {
+      console.error('Error saving device info:', error);
+    }
+  }
+
+  /**
+   * Update device name
+   */
+  static async updateDeviceName(deviceName: string): Promise<void> {
+    try {
+      const deviceInfo = await this.getDeviceInfo();
+      deviceInfo.deviceName = deviceName;
+      await this.saveDeviceInfo(deviceInfo);
+    } catch (error) {
+      console.error('Error updating device name:', error);
+    }
+  }
+
+  /**
+   * Clear stored device info (useful for testing or reset)
+   */
+  static async clearDeviceInfo(): Promise<void> {
+    try {
+      const storage = await this.getStorage();
+      await storage.removeItem(this.DEVICE_KEY);
+    } catch (error) {
+      console.error('Error clearing device info:', error);
+    }
+  }
+
+  /**
+   * Generate a unique device ID
+   */
+  private static generateDeviceId(): string {
+    // Use crypto.getRandomValues if available, otherwise fallback to Math.random
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+      const array = new Uint8Array(32);
+      crypto.getRandomValues(array);
+      return Array.from(array, byte => byte.toString(16).padStart(2, '0')).join('');
+    } else {
+      // Fallback for environments without crypto.getRandomValues
+      return 'device_' + Date.now().toString(36) + Math.random().toString(36).substr(2);
+    }
+  }
+
+  /**
+   * Get a user-friendly device name based on platform
+   */
+  static getDefaultDeviceName(): string {
+    const fingerprint = this.getDeviceFingerprint();
+    const platform = (fingerprint.platform || '').toLowerCase();
+    
+    if (platform.includes('win')) return 'Windows Computer';
+    if (platform.includes('mac')) return 'Mac Computer';
+    if (platform.includes('linux')) return 'Linux Computer';
+    if (platform.includes('iphone')) return 'iPhone';
+    if (platform.includes('ipad')) return 'iPad';
+    if (platform.includes('android')) return 'Android Device';
+    
+    return 'Unknown Device';
+  }
+}

package/src/utils/errorUtils.ts

@@ -0,0 +1,216 @@
+import type { ApiError } from '../models/interfaces';
+import { logger } from './loggerUtils';
+
+/**
+ * Error handling utilities for consistent error processing
+ */
+
+/**
+ * Common error codes
+ */
+export const ErrorCodes = {
+  // Authentication errors
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  INVALID_TOKEN: 'INVALID_TOKEN',
+  MISSING_TOKEN: 'MISSING_TOKEN',
+  
+  // Validation errors
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  BAD_REQUEST: 'BAD_REQUEST',
+  MISSING_PARAMETER: 'MISSING_PARAMETER',
+  INVALID_FORMAT: 'INVALID_FORMAT',
+  
+  // Resource errors
+  NOT_FOUND: 'NOT_FOUND',
+  ALREADY_EXISTS: 'ALREADY_EXISTS',
+  CONFLICT: 'CONFLICT',
+  
+  // Server errors
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+  TIMEOUT: 'TIMEOUT',
+  
+  // Network errors
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  CONNECTION_FAILED: 'CONNECTION_FAILED'
+} as const;
+
+/**
+ * Create a standardized API error
+ */
+export function createApiError(
+  message: string,
+  code: string = ErrorCodes.INTERNAL_ERROR,
+  status = 500,
+  details?: Record<string, unknown>
+): ApiError {
+  return {
+    message,
+    code,
+    status,
+    details
+  };
+}
+
+/**
+ * Handle common HTTP errors and convert to ApiError
+ */
+export function handleHttpError(error: unknown): ApiError {
+  // If it's already an ApiError, ensure it has a non-empty message
+  if (error && typeof error === 'object' && 'code' in error && 'status' in error) {
+    const apiError = error as ApiError;
+    // Ensure message is not empty
+    if (!apiError.message || !apiError.message.trim()) {
+      return {
+        ...apiError,
+        message: apiError.message || 'An error occurred',
+      };
+    }
+    return apiError;
+  }
+
+  // Handle AbortError (timeout or cancelled requests)
+  if (error instanceof Error && error.name === 'AbortError') {
+    return createApiError(
+      'Request timeout or cancelled',
+      ErrorCodes.TIMEOUT,
+      0
+    );
+  }
+
+  // Handle TypeError (network failures, CORS, etc.)
+  if (error instanceof TypeError) {
+    // Check if it's a network-related TypeError
+    if (error.message.includes('fetch') || error.message.includes('network') || error.message.includes('Failed to fetch')) {
+      return createApiError(
+        'Network error - failed to connect to server',
+        ErrorCodes.NETWORK_ERROR,
+        0
+      );
+    }
+    return createApiError(
+      error.message || 'Network error occurred',
+      ErrorCodes.NETWORK_ERROR,
+      0
+    );
+  }
+
+  // Handle fetch Response errors - check if it has response property with status
+  if (error && typeof error === 'object' && 'response' in error) {
+    const fetchError = error as { 
+      response?: { 
+        status: number; 
+        statusText?: string;
+      };
+      status?: number;
+      message?: string;
+    };
+    
+    const status = fetchError.response?.status || fetchError.status;
+    if (status) {
+      return createApiError(
+        fetchError.message || `HTTP ${status} error`,
+        getErrorCodeFromStatus(status),
+        status
+      );
+    }
+  }
+
+  // Handle standard errors
+  if (error instanceof Error) {
+    // Check for common error patterns
+    if (error.message.includes('timeout') || error.message.includes('aborted')) {
+      return createApiError(
+        'Request timeout',
+        ErrorCodes.TIMEOUT,
+        0
+      );
+    }
+    
+    if (error.message.includes('network') || error.message.includes('fetch')) {
+      return createApiError(
+        error.message || 'Network error occurred',
+        ErrorCodes.NETWORK_ERROR,
+        0
+      );
+    }
+
+    return createApiError(
+      error.message || 'Unknown error occurred',
+      ErrorCodes.INTERNAL_ERROR,
+      500
+    );
+  }
+
+  // Handle other errors - ensure we always return a non-empty message
+  const errorString = error ? String(error) : '';
+  const message = errorString.trim() || 'Unknown error occurred';
+  return createApiError(
+    message,
+    ErrorCodes.INTERNAL_ERROR,
+    500
+  );
+}
+
+/**
+ * Get error code from HTTP status
+ * Exported for use in other modules
+ */
+export function getErrorCodeFromStatus(status: number): string {
+  switch (status) {
+    case 400:
+      return ErrorCodes.BAD_REQUEST;
+    case 401:
+      return ErrorCodes.UNAUTHORIZED;
+    case 403:
+      return ErrorCodes.FORBIDDEN;
+    case 404:
+      return ErrorCodes.NOT_FOUND;
+    case 409:
+      return ErrorCodes.CONFLICT;
+    case 422:
+      return ErrorCodes.VALIDATION_ERROR;
+    case 500:
+      return ErrorCodes.INTERNAL_ERROR;
+    case 503:
+      return ErrorCodes.SERVICE_UNAVAILABLE;
+    default:
+      return ErrorCodes.INTERNAL_ERROR;
+  }
+}
+
+/**
+ * Validate required fields and throw error if missing
+ */
+export function validateRequiredFields(data: Record<string, unknown>, fields: string[]): void {
+  const missing = fields.filter(field => !data[field]);
+  
+  if (missing.length > 0) {
+    throw createApiError(
+      `Missing required fields: ${missing.join(', ')}`,
+      ErrorCodes.MISSING_PARAMETER,
+      400
+    );
+  }
+}
+
+/**
+ * Safe error logging with context
+ */
+export function logError(error: unknown, context?: string): void {
+  if (error instanceof Error) {
+    logger.error(error.message, {
+      component: context || 'errorUtils',
+      method: 'logError',
+      stack: error.stack,
+    });
+  } else {
+    logger.error(String(error), {
+      component: context || 'errorUtils',
+      method: 'logError',
+    });
+  }
+}
+
+ 

package/src/utils/index.ts

@@ -0,0 +1,21 @@
+export { DeviceManager } from './deviceManager';
+export type { DeviceFingerprint, StoredDeviceInfo } from './deviceManager';
+
+// Request utilities
+export { RequestDeduplicator, RequestQueue, SimpleLogger } from './requestUtils';
+
+// Cache utilities
+export { TTLCache, createCache, registerCacheForCleanup, unregisterCacheFromCleanup } from './cache';
+export type { CacheStats } from './cache';
+
+// Session utilities
+export { 
+  normalizeSession, 
+  sortSessions, 
+  deduplicateSessions,
+  deduplicateSessionsByUserId,
+  normalizeAndSortSessions, 
+  mergeSessions, 
+  sessionsEqual, 
+  sessionsArraysEqual 
+} from './sessionUtils';