@oxyhq/services 5.13.0 → 5.13.2

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: NodeJS.Timeout | 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 cache cleanup intervals
+ * Useful for tests to prevent Jest from hanging
+ */
+export function stopAllCacheCleanup(): void {
+  if (cleanupInterval) {
+    clearInterval(cleanupInterval);
+    cleanupInterval = null;
+  }
+  activeCaches.clear();
+}
+

package/src/utils/index.ts

@@ -1,2 +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, stopAllCacheCleanup } from './cache';
+export type { CacheStats } from './cache';
+
+// Session utilities
+export { 
+  normalizeSession, 
+  sortSessions, 
+  deduplicateSessions,
+  deduplicateSessionsByUserId,
+  normalizeAndSortSessions, 
+  mergeSessions, 
+  sessionsEqual, 
+  sessionsArraysEqual 
+} from './sessionUtils';

package/src/utils/languageUtils.ts

@@ -0,0 +1,174 @@
+/**
+ * Language utilities for OxyServices
+ * Provides access to supported languages and language metadata
+ */
+
+export interface LanguageMetadata {
+  id: string;
+  name: string;
+  nativeName: string;
+  flag: string;
+  icon: string;
+  color: string;
+}
+
+// Supported languages with their metadata
+export const SUPPORTED_LANGUAGES: LanguageMetadata[] = [
+  {
+    id: 'en-US',
+    name: 'English',
+    nativeName: 'English',
+    flag: '🇺🇸',
+    icon: 'language-outline',
+    color: '#007AFF',
+  },
+  {
+    id: 'es-ES',
+    name: 'Spanish',
+    nativeName: 'Español',
+    flag: '🇪🇸',
+    icon: 'language-outline',
+    color: '#FF3B30',
+  },
+  {
+    id: 'ca-ES',
+    name: 'Catalan',
+    nativeName: 'Català',
+    flag: '🇪🇸',
+    icon: 'language-outline',
+    color: '#0CA678',
+  },
+  {
+    id: 'fr-FR',
+    name: 'French',
+    nativeName: 'Français',
+    flag: '🇫🇷',
+    icon: 'language-outline',
+    color: '#5856D6',
+  },
+  {
+    id: 'de-DE',
+    name: 'German',
+    nativeName: 'Deutsch',
+    flag: '🇩🇪',
+    icon: 'language-outline',
+    color: '#FF9500',
+  },
+  {
+    id: 'it-IT',
+    name: 'Italian',
+    nativeName: 'Italiano',
+    flag: '🇮🇹',
+    icon: 'language-outline',
+    color: '#34C759',
+  },
+  {
+    id: 'pt-PT',
+    name: 'Portuguese',
+    nativeName: 'Português',
+    flag: '🇵🇹',
+    icon: 'language-outline',
+    color: '#AF52DE',
+  },
+  {
+    id: 'ja-JP',
+    name: 'Japanese',
+    nativeName: '日本語',
+    flag: '🇯🇵',
+    icon: 'language-outline',
+    color: '#FF2D92',
+  },
+  {
+    id: 'ko-KR',
+    name: 'Korean',
+    nativeName: '한국어',
+    flag: '🇰🇷',
+    icon: 'language-outline',
+    color: '#32D74B',
+  },
+  {
+    id: 'zh-CN',
+    name: 'Chinese',
+    nativeName: '中文',
+    flag: '🇨🇳',
+    icon: 'language-outline',
+    color: '#FF9F0A',
+  },
+  {
+    id: 'ar-SA',
+    name: 'Arabic',
+    nativeName: 'العربية',
+    flag: '🇸🇦',
+    icon: 'language-outline',
+    color: '#30B0C7',
+  },
+];
+
+const FALLBACK_LANGUAGE = 'en-US';
+
+/**
+ * Get language metadata by language code
+ * @param languageCode - BCP-47 language code (e.g., 'en-US', 'es-ES')
+ * @returns Language metadata or null if not found
+ */
+export function getLanguageMetadata(languageCode: string | null | undefined): LanguageMetadata | null {
+  if (!languageCode) return null;
+  
+  // Direct match
+  const exactMatch = SUPPORTED_LANGUAGES.find(lang => lang.id === languageCode);
+  if (exactMatch) return exactMatch;
+  
+  // Try to match base language code (e.g., 'en' matches 'en-US')
+  const baseCode = languageCode.split('-')[0];
+  const baseMatch = SUPPORTED_LANGUAGES.find(lang => lang.id.startsWith(baseCode + '-'));
+  if (baseMatch) return baseMatch;
+  
+  return null;
+}
+
+/**
+ * Get language name by language code
+ * @param languageCode - BCP-47 language code (e.g., 'en-US', 'es-ES')
+ * @returns Language name (e.g., 'English') or the code if not found
+ */
+export function getLanguageName(languageCode: string | null | undefined): string {
+  const metadata = getLanguageMetadata(languageCode);
+  return metadata?.name || languageCode || FALLBACK_LANGUAGE;
+}
+
+/**
+ * Get native language name by language code
+ * @param languageCode - BCP-47 language code (e.g., 'en-US', 'es-ES')
+ * @returns Native language name (e.g., 'Español') or the code if not found
+ */
+export function getNativeLanguageName(languageCode: string | null | undefined): string {
+  const metadata = getLanguageMetadata(languageCode);
+  return metadata?.nativeName || languageCode || FALLBACK_LANGUAGE;
+}
+
+/**
+ * Normalize language code to BCP-47 format
+ * @param lang - Language code (may be short like 'en' or full like 'en-US')
+ * @returns Normalized BCP-47 language code
+ */
+export function normalizeLanguageCode(lang?: string | null): string {
+  if (!lang) return FALLBACK_LANGUAGE;
+  if (lang.includes('-')) return lang;
+  
+  const map: Record<string, string> = {
+    en: 'en-US',
+    es: 'es-ES',
+    ca: 'ca-ES',
+    fr: 'fr-FR',
+    de: 'de-DE',
+    it: 'it-IT',
+    pt: 'pt-PT',
+    ja: 'ja-JP',
+    ko: 'ko-KR',
+    zh: 'zh-CN',
+    ar: 'ar-SA',
+  };
+  
+  return map[lang] || lang;
+}
+

package/src/utils/requestUtils.ts

@@ -0,0 +1,234 @@
+/**
+ * Request utilities for HTTP clients
+ * 
+ * Provides reusable components for request deduplication, queuing, and logging
+ */
+
+/**
+ * Request deduplication - prevents duplicate concurrent requests
+ * 
+ * When multiple requests with the same key are made simultaneously,
+ * only one request is executed and all callers receive the same result.
+ * 
+ * @example
+ * ```typescript
+ * const deduplicator = new RequestDeduplicator();
+ * 
+ * // Multiple calls with same key will share the same promise
+ * const promise1 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
+ * const promise2 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
+ * // promise1 === promise2, only one API call is made
+ * ```
+ */
+export class RequestDeduplicator {
+  private pendingRequests = new Map<string, Promise<any>>();
+
+  /**
+   * Deduplicate a request by key
+   * @param key Unique key for the request
+   * @param requestFn Function that returns a promise
+   * @returns Promise that will be shared if key already exists
+   */
+  async deduplicate<T>(
+    key: string,
+    requestFn: () => Promise<T>
+  ): Promise<T> {
+    const existing = this.pendingRequests.get(key);
+    if (existing) {
+      return existing;
+    }
+
+    const promise = requestFn()
+      .finally(() => {
+        this.pendingRequests.delete(key);
+      });
+
+    this.pendingRequests.set(key, promise);
+    return promise;
+  }
+
+  /**
+   * Clear all pending requests
+   */
+  clear(): void {
+    this.pendingRequests.clear();
+  }
+
+  /**
+   * Get number of pending requests
+   */
+  size(): number {
+    return this.pendingRequests.size;
+  }
+}
+
+/**
+ * Request queue with concurrency control
+ * 
+ * Limits the number of concurrent requests and queues excess requests.
+ * Useful for rate limiting and preventing request flooding.
+ * 
+ * @example
+ * ```typescript
+ * const queue = new RequestQueue(5, 100); // Max 5 concurrent, queue up to 100
+ * 
+ * // All requests will be queued and processed with max 5 concurrent
+ * await queue.enqueue(() => fetchUser('1'));
+ * await queue.enqueue(() => fetchUser('2'));
+ * // ...
+ * ```
+ */
+export class RequestQueue {
+  private queue: Array<() => Promise<any>> = [];
+  private running = 0;
+  private maxConcurrent: number;
+  private maxQueueSize: number;
+
+  /**
+   * Create a new request queue
+   * @param maxConcurrent Maximum number of concurrent requests (default: 10)
+   * @param maxQueueSize Maximum queue size (default: 100)
+   */
+  constructor(maxConcurrent: number = 10, maxQueueSize: number = 100) {
+    this.maxConcurrent = maxConcurrent;
+    this.maxQueueSize = maxQueueSize;
+  }
+
+  /**
+   * Enqueue a request
+   * @param requestFn Function that returns a promise
+   * @returns Promise that resolves when request completes
+   */
+  async enqueue<T>(requestFn: () => Promise<T>): Promise<T> {
+    if (this.queue.length >= this.maxQueueSize) {
+      throw new Error('Request queue is full');
+    }
+
+    return new Promise<T>((resolve, reject) => {
+      this.queue.push(async () => {
+        try {
+          const result = await requestFn();
+          resolve(result);
+        } catch (error) {
+          reject(error);
+        }
+      });
+
+      this.process();
+    });
+  }
+
+  /**
+   * Process queued requests
+   */
+  private async process(): Promise<void> {
+    if (this.running >= this.maxConcurrent || this.queue.length === 0) {
+      return;
+    }
+
+    this.running++;
+    const requestFn = this.queue.shift();
+    if (requestFn) {
+      try {
+        await requestFn();
+      } finally {
+        this.running--;
+        this.process();
+      }
+    } else {
+      this.running--;
+    }
+  }
+
+  /**
+   * Clear all queued requests
+   */
+  clear(): void {
+    this.queue = [];
+  }
+
+  /**
+   * Get queue size
+   */
+  size(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * Get number of currently running requests
+   */
+  runningCount(): number {
+    return this.running;
+  }
+}
+
+/**
+ * Simple logger with level support
+ * 
+ * Lightweight logger for HTTP clients and utilities.
+ * For more advanced logging, use loggerUtils.ts
+ * 
+ * @example
+ * ```typescript
+ * const logger = new SimpleLogger(true, 'debug');
+ * logger.debug('Debug message');
+ * logger.info('Info message');
+ * logger.error('Error message');
+ * ```
+ */
+export class SimpleLogger {
+  private enabled: boolean;
+  private level: 'none' | 'error' | 'warn' | 'info' | 'debug';
+  private prefix: string;
+
+  /**
+   * Create a new simple logger
+   * @param enabled Whether logging is enabled
+   * @param level Minimum log level
+   * @param prefix Prefix for log messages (default: '')
+   */
+  constructor(
+    enabled: boolean = false,
+    level: string = 'error',
+    prefix: string = ''
+  ) {
+    this.enabled = enabled;
+    this.level = level as any;
+    this.prefix = prefix;
+  }
+
+  private shouldLog(level: string): boolean {
+    if (!this.enabled || this.level === 'none') return false;
+    const levels = ['none', 'error', 'warn', 'info', 'debug'];
+    return levels.indexOf(level) <= levels.indexOf(this.level);
+  }
+
+  private formatMessage(...args: any[]): any[] {
+    return this.prefix ? [`[${this.prefix}]`, ...args] : args;
+  }
+
+  error(...args: any[]): void {
+    if (this.shouldLog('error')) {
+      console.error(...this.formatMessage(...args));
+    }
+  }
+
+  warn(...args: any[]): void {
+    if (this.shouldLog('warn')) {
+      console.warn(...this.formatMessage(...args));
+    }
+  }
+
+  info(...args: any[]): void {
+    if (this.shouldLog('info')) {
+      console.info(...this.formatMessage(...args));
+    }
+  }
+
+  debug(...args: any[]): void {
+    if (this.shouldLog('debug')) {
+      console.log(...this.formatMessage(...args));
+    }
+  }
+}
+