@oxyhq/core 1.0.0

package/dist/cjs/utils/cache.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Centralized cache utility with TTL support
+ *
+ * This is a production-ready cache implementation used across the codebase
+ * for consistent caching behavior and performance optimization.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TTLCache = void 0;
+exports.createCache = createCache;
+exports.registerCacheForCleanup = registerCacheForCleanup;
+exports.unregisterCacheFromCleanup = unregisterCacheFromCleanup;
+exports.stopAllCleanupIntervals = stopAllCleanupIntervals;
+/**
+ * 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 {
+    /**
+     * 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;
+    }
+}
+exports.TTLCache = TTLCache;
+/**
+ * Create a TTL cache instance (convenience function)
+ *
+ * @example
+ * ```typescript
+ * const cache = createCache<string>(5 * 60 * 1000);
+ * ```
+ */
+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();
+}

package/dist/cjs/utils/deviceManager.js

@@ -0,0 +1,205 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceManager = void 0;
+/**
+ * Client-side device management utility
+ * Handles persistent device identification across app sessions
+ */
+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 Promise.resolve().then(() => __importStar(require('@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';
+    }
+}
+exports.DeviceManager = DeviceManager;
+DeviceManager.DEVICE_KEY = 'oxy_device_info';

package/dist/cjs/utils/errorUtils.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCodes = void 0;
+exports.createApiError = createApiError;
+exports.handleHttpError = handleHttpError;
+exports.getErrorCodeFromStatus = getErrorCodeFromStatus;
+exports.validateRequiredFields = validateRequiredFields;
+exports.logError = logError;
+const loggerUtils_1 = require("./loggerUtils");
+/**
+ * Error handling utilities for consistent error processing
+ */
+/**
+ * Common error codes
+ */
+exports.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'
+};
+/**
+ * Create a standardized API error
+ */
+function createApiError(message, code = exports.ErrorCodes.INTERNAL_ERROR, status = 500, details) {
+    return {
+        message,
+        code,
+        status,
+        details
+    };
+}
+/**
+ * Handle common HTTP errors and convert to ApiError
+ */
+function handleHttpError(error) {
+    // 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;
+        // 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', exports.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', exports.ErrorCodes.NETWORK_ERROR, 0);
+        }
+        return createApiError(error.message || 'Network error occurred', exports.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;
+        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', exports.ErrorCodes.TIMEOUT, 0);
+        }
+        if (error.message.includes('network') || error.message.includes('fetch')) {
+            return createApiError(error.message || 'Network error occurred', exports.ErrorCodes.NETWORK_ERROR, 0);
+        }
+        return createApiError(error.message || 'Unknown error occurred', exports.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, exports.ErrorCodes.INTERNAL_ERROR, 500);
+}
+/**
+ * Get error code from HTTP status
+ * Exported for use in other modules
+ */
+function getErrorCodeFromStatus(status) {
+    switch (status) {
+        case 400:
+            return exports.ErrorCodes.BAD_REQUEST;
+        case 401:
+            return exports.ErrorCodes.UNAUTHORIZED;
+        case 403:
+            return exports.ErrorCodes.FORBIDDEN;
+        case 404:
+            return exports.ErrorCodes.NOT_FOUND;
+        case 409:
+            return exports.ErrorCodes.CONFLICT;
+        case 422:
+            return exports.ErrorCodes.VALIDATION_ERROR;
+        case 500:
+            return exports.ErrorCodes.INTERNAL_ERROR;
+        case 503:
+            return exports.ErrorCodes.SERVICE_UNAVAILABLE;
+        default:
+            return exports.ErrorCodes.INTERNAL_ERROR;
+    }
+}
+/**
+ * Validate required fields and throw error if missing
+ */
+function validateRequiredFields(data, fields) {
+    const missing = fields.filter(field => !data[field]);
+    if (missing.length > 0) {
+        throw createApiError(`Missing required fields: ${missing.join(', ')}`, exports.ErrorCodes.MISSING_PARAMETER, 400);
+    }
+}
+/**
+ * Safe error logging with context
+ */
+function logError(error, context) {
+    if (error instanceof Error) {
+        loggerUtils_1.logger.error(error.message, {
+            component: context || 'errorUtils',
+            method: 'logError',
+            stack: error.stack,
+        });
+    }
+    else {
+        loggerUtils_1.logger.error(String(error), {
+            component: context || 'errorUtils',
+            method: 'logError',
+        });
+    }
+}

package/dist/cjs/utils/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionsArraysEqual = exports.sessionsEqual = exports.mergeSessions = exports.normalizeAndSortSessions = exports.deduplicateSessionsByUserId = exports.deduplicateSessions = exports.sortSessions = exports.normalizeSession = exports.unregisterCacheFromCleanup = exports.registerCacheForCleanup = exports.createCache = exports.TTLCache = exports.SimpleLogger = exports.RequestQueue = exports.RequestDeduplicator = exports.DeviceManager = void 0;
+var deviceManager_1 = require("./deviceManager");
+Object.defineProperty(exports, "DeviceManager", { enumerable: true, get: function () { return deviceManager_1.DeviceManager; } });
+// Request utilities
+var requestUtils_1 = require("./requestUtils");
+Object.defineProperty(exports, "RequestDeduplicator", { enumerable: true, get: function () { return requestUtils_1.RequestDeduplicator; } });
+Object.defineProperty(exports, "RequestQueue", { enumerable: true, get: function () { return requestUtils_1.RequestQueue; } });
+Object.defineProperty(exports, "SimpleLogger", { enumerable: true, get: function () { return requestUtils_1.SimpleLogger; } });
+// Cache utilities
+var cache_1 = require("./cache");
+Object.defineProperty(exports, "TTLCache", { enumerable: true, get: function () { return cache_1.TTLCache; } });
+Object.defineProperty(exports, "createCache", { enumerable: true, get: function () { return cache_1.createCache; } });
+Object.defineProperty(exports, "registerCacheForCleanup", { enumerable: true, get: function () { return cache_1.registerCacheForCleanup; } });
+Object.defineProperty(exports, "unregisterCacheFromCleanup", { enumerable: true, get: function () { return cache_1.unregisterCacheFromCleanup; } });
+// Session utilities
+var sessionUtils_1 = require("./sessionUtils");
+Object.defineProperty(exports, "normalizeSession", { enumerable: true, get: function () { return sessionUtils_1.normalizeSession; } });
+Object.defineProperty(exports, "sortSessions", { enumerable: true, get: function () { return sessionUtils_1.sortSessions; } });
+Object.defineProperty(exports, "deduplicateSessions", { enumerable: true, get: function () { return sessionUtils_1.deduplicateSessions; } });
+Object.defineProperty(exports, "deduplicateSessionsByUserId", { enumerable: true, get: function () { return sessionUtils_1.deduplicateSessionsByUserId; } });
+Object.defineProperty(exports, "normalizeAndSortSessions", { enumerable: true, get: function () { return sessionUtils_1.normalizeAndSortSessions; } });
+Object.defineProperty(exports, "mergeSessions", { enumerable: true, get: function () { return sessionUtils_1.mergeSessions; } });
+Object.defineProperty(exports, "sessionsEqual", { enumerable: true, get: function () { return sessionUtils_1.sessionsEqual; } });
+Object.defineProperty(exports, "sessionsArraysEqual", { enumerable: true, get: function () { return sessionUtils_1.sessionsArraysEqual; } });