@oxyhq/core 1.0.0

package/dist/esm/utils/apiUtils.js

@@ -0,0 +1,55 @@
+/**
+ * Utility functions for common API patterns
+ */
+/**
+ * Build URL search parameters from an object
+ * @param params Object with parameter key-value pairs
+ * @returns URLSearchParams instance
+ */
+export 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
+ */
+export function buildUrl(baseUrl, params) {
+    if (!params)
+        return baseUrl;
+    const searchParams = buildSearchParams(params);
+    const queryString = searchParams.toString();
+    return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+}
+/**
+ * Build pagination search parameters
+ * @param params Pagination parameters
+ * @returns URLSearchParams with pagination
+ */
+export function buildPaginationParams(params) {
+    return buildSearchParams(params);
+}
+/**
+ * Safe JSON parsing with error handling
+ * @param data Data to parse
+ * @param fallback Fallback value if parsing fails
+ * @returns Parsed data or fallback
+ */
+export function safeJsonParse(data, fallback) {
+    if (typeof data === 'string') {
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    return data;
+}

package/dist/esm/utils/asyncUtils.js

@@ -0,0 +1,179 @@
+/**
+ * Async utilities for common asynchronous patterns and error handling
+ */
+import { logger } from './loggerUtils';
+/**
+ * Wrapper for async operations with automatic error handling
+ * Returns null on error instead of throwing
+ */
+export async function withErrorHandling(operation, errorHandler, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (errorHandler) {
+            errorHandler(error);
+        }
+        else {
+            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
+ */
+export 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.
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export async function withLoadingState(operation, setLoading) {
+    setLoading(true);
+    try {
+        return await operation();
+    }
+    finally {
+        setLoading(false);
+    }
+}
+/**
+ * Create a promise that resolves after a delay
+ */
+export const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+/**
+ * Execute async operation with retry on specific errors
+ */
+export 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);
+    });
+}

package/dist/esm/utils/cache.js

@@ -0,0 +1,218 @@
+/**
+ * Centralized cache utility with TTL support
+ *
+ * This is a production-ready cache implementation used across the codebase
+ * for consistent caching behavior and performance optimization.
+ */
+/**
+ * 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 {
+    /**
+     * Create a new TTL cache
+     * @param defaultTTL Default TTL in milliseconds (default: 5 minutes)
+     */
+    constructor(defaultTTL = 5 * 60 * 1000) {
+        this.cache = new Map();
+        this.hits = 0;
+        this.misses = 0;
+        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);
+ * ```
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export function stopAllCleanupIntervals() {
+    if (cleanupInterval) {
+        clearInterval(cleanupInterval);
+        cleanupInterval = null;
+    }
+    activeCaches.clear();
+}

package/dist/esm/utils/deviceManager.js

@@ -0,0 +1,168 @@
+/**
+ * Client-side device management utility
+ * Handles persistent device identification across app sessions
+ */
+export class DeviceManager {
+    /**
+     * Check if we're in React Native environment
+     */
+    static isReactNative() {
+        return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+    }
+    /**
+     * Get appropriate storage for the platform
+     */
+    static async getStorage() {
+        if (this.isReactNative()) {
+            try {
+                const asyncStorageModule = await import('@react-native-async-storage/async-storage');
+                const storage = asyncStorageModule.default;
+                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) => localStorage.getItem(key),
+                setItem: async (key, value) => localStorage.setItem(key, value),
+                removeItem: async (key) => localStorage.removeItem(key)
+            };
+        }
+    }
+    /**
+     * Get or create device fingerprint for current device
+     */
+    static getDeviceFingerprint() {
+        const fingerprint = {
+            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() {
+        try {
+            const storage = await this.getStorage();
+            const stored = await storage.getItem(this.DEVICE_KEY);
+            if (stored) {
+                const deviceInfo = 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() {
+        const deviceInfo = {
+            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) {
+        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) {
+        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() {
+        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
+     */
+    static generateDeviceId() {
+        // 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() {
+        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';
+    }
+}
+DeviceManager.DEVICE_KEY = 'oxy_device_info';