@oxyhq/services 5.16.23 → 5.16.24

package/lib/commonjs/utils/apiUtils.js

@@ -0,0 +1,79 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.buildPaginationParams = buildPaginationParams;
+exports.buildSearchParams = buildSearchParams;
+exports.buildUrl = buildUrl;
+exports.safeJsonParse = safeJsonParse;
+/**
+ * Utility functions for common API patterns
+ */
+
+/**
+ * Build URL search parameters from an object
+ * @param params Object with parameter key-value pairs
+ * @returns URLSearchParams instance
+ */
+function buildSearchParams(params) {
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null) {
+      searchParams.append(key, value.toString());
+    }
+  }
+  return searchParams;
+}
+
+/**
+ * Build URL with search parameters
+ * @param baseUrl Base URL
+ * @param params Object with parameter key-value pairs
+ * @returns Complete URL with search parameters
+ */
+function buildUrl(baseUrl, params) {
+  if (!params) return baseUrl;
+  const searchParams = buildSearchParams(params);
+  const queryString = searchParams.toString();
+  return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+}
+
+/**
+ * Common pagination parameters
+ */
+
+/**
+ * Build pagination search parameters
+ * @param params Pagination parameters
+ * @returns URLSearchParams with pagination
+ */
+function buildPaginationParams(params) {
+  return buildSearchParams(params);
+}
+
+/**
+ * Common API response wrapper
+ */
+
+/**
+ * Common error response wrapper
+ */
+
+/**
+ * Safe JSON parsing with error handling
+ * @param data Data to parse
+ * @param fallback Fallback value if parsing fails
+ * @returns Parsed data or fallback
+ */
+function safeJsonParse(data, fallback) {
+  if (typeof data === 'string') {
+    try {
+      return JSON.parse(data);
+    } catch {
+      return fallback;
+    }
+  }
+  return data;
+}
+//# sourceMappingURL=apiUtils.js.map

package/lib/commonjs/utils/apiUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["buildSearchParams","params","searchParams","URLSearchParams","key","value","Object","entries","undefined","append","toString","buildUrl","baseUrl","queryString","buildPaginationParams","safeJsonParse","data","fallback","JSON","parse"],"sourceRoot":"../../../src","sources":["utils/apiUtils.ts"],"mappings":";;;;;;;;;AAAA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACA;AACO,SAASA,iBAAiBA,CAACC,MAA2B,EAAmB;EAC9E,MAAMC,YAAY,GAAG,IAAIC,eAAe,CAAC,CAAC;EAE1C,KAAK,MAAM,CAACC,GAAG,EAAEC,KAAK,CAAC,IAAIC,MAAM,CAACC,OAAO,CAACN,MAAM,CAAC,EAAE;IACjD,IAAII,KAAK,KAAKG,SAAS,IAAIH,KAAK,KAAK,IAAI,EAAE;MACzCH,YAAY,CAACO,MAAM,CAACL,GAAG,EAAEC,KAAK,CAACK,QAAQ,CAAC,CAAC,CAAC;IAC5C;EACF;EAEA,OAAOR,YAAY;AACrB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACO,SAASS,QAAQA,CAACC,OAAe,EAAEX,MAA4B,EAAU;EAC9E,IAAI,CAACA,MAAM,EAAE,OAAOW,OAAO;EAE3B,MAAMV,YAAY,GAAGF,iBAAiB,CAACC,MAAM,CAAC;EAC9C,MAAMY,WAAW,GAAGX,YAAY,CAACQ,QAAQ,CAAC,CAAC;EAE3C,OAAOG,WAAW,GAAG,GAAGD,OAAO,IAAIC,WAAW,EAAE,GAAGD,OAAO;AAC5D;;AAEA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACO,SAASE,qBAAqBA,CAACb,MAAwB,EAAmB;EAC/E,OAAOD,iBAAiB,CAACC,MAAM,CAAC;AAClC;;AAEA;AACA;AACA;;AAOA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACO,SAASc,aAAaA,CAAIC,IAAS,EAAEC,QAAW,EAAK;EAC1D,IAAI,OAAOD,IAAI,KAAK,QAAQ,EAAE;IAC5B,IAAI;MACF,OAAOE,IAAI,CAACC,KAAK,CAACH,IAAI,CAAC;IACzB,CAAC,CAAC,MAAM;MACN,OAAOC,QAAQ;IACjB;EACF;EACA,OAAOD,IAAI;AACb","ignoreList":[]}

package/lib/commonjs/utils/asyncUtils.js

@@ -0,0 +1,207 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.batchAsync = batchAsync;
+exports.createCancellableAsync = createCancellableAsync;
+exports.debounceAsync = debounceAsync;
+exports.delay = void 0;
+exports.parallelWithErrorHandling = parallelWithErrorHandling;
+exports.retryAsync = retryAsync;
+exports.retryOnError = retryOnError;
+exports.sequentialWithProgress = sequentialWithProgress;
+exports.throttleAsync = throttleAsync;
+exports.withErrorHandling = withErrorHandling;
+exports.withLoadingState = withLoadingState;
+exports.withTimeout = withTimeout;
+var _loggerUtils = require("./loggerUtils");
+/**
+ * Async utilities for common asynchronous patterns and error handling
+ */
+
+/**
+ * Wrapper for async operations with automatic error handling
+ * Returns null on error instead of throwing
+ */
+async function withErrorHandling(operation, errorHandler, context) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (errorHandler) {
+      errorHandler(error);
+    } else {
+      _loggerUtils.logger.error(`Error in ${context || 'operation'}`, error instanceof Error ? error : new Error(String(error)), {
+        component: 'asyncUtils',
+        method: 'withErrorHandling'
+      });
+    }
+    return null;
+  }
+}
+
+/**
+ * Execute multiple async operations in parallel with error handling
+ */
+async function parallelWithErrorHandling(operations, errorHandler) {
+  const results = await Promise.allSettled(operations.map((op, index) => withErrorHandling(op, error => errorHandler?.(error, index))));
+  return results.map(result => result.status === 'fulfilled' ? result.value : null);
+}
+
+/**
+ * Retry an async operation with exponential backoff
+ * 
+ * By default, does not retry on 4xx errors (client errors).
+ * Use shouldRetry callback to customize retry behavior.
+ */
+async function retryAsync(operation, maxRetries = 3, baseDelay = 1000, shouldRetry) {
+  let lastError;
+
+  // Default shouldRetry: don't retry on 4xx errors
+  const defaultShouldRetry = error => {
+    // Don't retry on 4xx errors (client errors)
+    if (error?.response?.status >= 400 && error?.response?.status < 500) {
+      return false;
+    }
+    return true;
+  };
+  const retryCheck = shouldRetry || defaultShouldRetry;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      if (attempt === maxRetries) {
+        break;
+      }
+      if (!retryCheck(error)) {
+        break;
+      }
+
+      // Calculate delay with exponential backoff and jitter
+      const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * Debounce async function calls
+ */
+function debounceAsync(func, delay) {
+  let timeoutId;
+  const lastPromise = null;
+  return (...args) => {
+    return new Promise((resolve, reject) => {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(async () => {
+        try {
+          const result = await func(...args);
+          resolve(result);
+        } catch (error) {
+          reject(error);
+        }
+      }, delay);
+    });
+  };
+}
+
+/**
+ * Throttle async function calls
+ */
+function throttleAsync(func, limit, interval) {
+  let inThrottle = false;
+  let lastPromise = null;
+  return (...args) => {
+    if (inThrottle) {
+      return lastPromise;
+    }
+    inThrottle = true;
+    lastPromise = func(...args);
+    setTimeout(() => {
+      inThrottle = false;
+    }, interval);
+    return lastPromise;
+  };
+}
+
+/**
+ * Execute async operations sequentially with progress tracking
+ */
+async function sequentialWithProgress(operations, onProgress) {
+  const results = [];
+  for (let i = 0; i < operations.length; i++) {
+    const result = await operations[i]();
+    results.push(result);
+    onProgress?.(i + 1, operations.length);
+  }
+  return results;
+}
+
+/**
+ * Batch async operations
+ */
+async function batchAsync(items, batchSize, processor) {
+  for (let i = 0; i < items.length; i += batchSize) {
+    const batch = items.slice(i, i + batchSize);
+    await processor(batch);
+  }
+}
+
+/**
+ * Create a cancellable async operation
+ */
+function createCancellableAsync(operation) {
+  let abortController = null;
+  return {
+    execute: async () => {
+      abortController = new AbortController();
+      return await operation(abortController.signal);
+    },
+    cancel: () => {
+      abortController?.abort();
+    }
+  };
+}
+
+/**
+ * Timeout wrapper for async operations
+ */
+async function withTimeout(operation, timeoutMs, timeoutMessage) {
+  const timeoutPromise = new Promise((_, reject) => {
+    setTimeout(() => {
+      reject(new Error(timeoutMessage || `Operation timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  return Promise.race([operation, timeoutPromise]);
+}
+
+/**
+ * Execute async operation with loading state
+ */
+async function withLoadingState(operation, setLoading) {
+  setLoading(true);
+  try {
+    return await operation();
+  } finally {
+    setLoading(false);
+  }
+}
+
+/**
+ * Create a promise that resolves after a delay
+ */
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Execute async operation with retry on specific errors
+ */
+exports.delay = delay;
+async function retryOnError(operation, retryableErrors, maxRetries = 3) {
+  return retryAsync(operation, maxRetries, 1000, error => {
+    const errorCode = error?.code || error?.status || error?.message;
+    return retryableErrors.includes(errorCode);
+  });
+}
+//# sourceMappingURL=asyncUtils.js.map

package/lib/commonjs/utils/asyncUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_loggerUtils","require","withErrorHandling","operation","errorHandler","context","error","logger","Error","String","component","method","parallelWithErrorHandling","operations","results","Promise","allSettled","map","op","index","result","status","value","retryAsync","maxRetries","baseDelay","shouldRetry","lastError","defaultShouldRetry","response","retryCheck","attempt","delay","Math","pow","random","resolve","setTimeout","debounceAsync","func","timeoutId","lastPromise","args","reject","clearTimeout","throttleAsync","limit","interval","inThrottle","sequentialWithProgress","onProgress","i","length","push","batchAsync","items","batchSize","processor","batch","slice","createCancellableAsync","abortController","execute","AbortController","signal","cancel","abort","withTimeout","timeoutMs","timeoutMessage","timeoutPromise","_","race","withLoadingState","setLoading","ms","exports","retryOnError","retryableErrors","errorCode","code","message","includes"],"sourceRoot":"../../../src","sources":["utils/asyncUtils.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/utils/cache.js

@@ -0,0 +1,259 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.TTLCache = void 0;
+exports.createCache = createCache;
+exports.registerCacheForCleanup = registerCacheForCleanup;
+exports.stopAllCleanupIntervals = stopAllCleanupIntervals;
+exports.unregisterCacheFromCleanup = unregisterCacheFromCleanup;
+/**
+ * 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
+ */
+
+/**
+ * Cache statistics
+ */
+
+/**
+ * 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();
+ * ```
+ */
+class TTLCache {
+  cache = new Map();
+  hits = 0;
+  misses = 0;
+
+  /**
+   * Create a new TTL cache
+   * @param defaultTTL Default TTL in milliseconds (default: 5 minutes)
+   */
+  constructor(defaultTTL = 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) {
+    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, data, ttl) {
+    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) {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all cache entries
+   */
+  clear() {
+    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) {
+    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() {
+    const now = Date.now();
+    const validKeys = [];
+    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() {
+    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() {
+    return this.cache.size;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats() {
+    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() {
+    this.hits = 0;
+    this.misses = 0;
+  }
+}
+
+/**
+ * Create a TTL cache instance (convenience function)
+ * 
+ * @example
+ * ```typescript
+ * const cache = createCache<string>(5 * 60 * 1000);
+ * ```
+ */
+exports.TTLCache = TTLCache;
+function createCache(ttl = 5 * 60 * 1000) {
+  return new TTLCache(ttl);
+}
+
+/**
+ * Global cache cleanup interval (runs every minute)
+ * This helps prevent memory leaks from expired cache entries
+ */
+let cleanupInterval = null;
+const activeCaches = new Set();
+
+/**
+ * Register a cache for automatic cleanup
+ * @param cache Cache instance to register
+ */
+function registerCacheForCleanup(cache) {
+  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
+ */
+function unregisterCacheFromCleanup(cache) {
+  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
+ */
+function stopAllCleanupIntervals() {
+  if (cleanupInterval) {
+    clearInterval(cleanupInterval);
+    cleanupInterval = null;
+  }
+  activeCaches.clear();
+}
+//# sourceMappingURL=cache.js.map

package/lib/commonjs/utils/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["TTLCache","cache","Map","hits","misses","constructor","defaultTTL","get","key","entry","now","Date","expiresAt","delete","data","set","ttl","timestamp","clear","has","keys","validKeys","entries","push","cleanup","removed","size","getStats","total","hitRate","resetStats","exports","createCache","cleanupInterval","activeCaches","Set","registerCacheForCleanup","add","setInterval","unregisterCacheFromCleanup","clearInterval","stopAllCleanupIntervals"],"sourceRoot":"../../../src","sources":["utils/cache.ts"],"mappings":"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","ignoreList":[]}