@oxyhq/services 5.26.4 → 5.27.0

package/dist/web/types/ui/utils/userUtils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * User display name and date formatting utilities
+ */
+/**
+ * Formats a date string to a readable format (e.g., "Feb 21, 2025")
+ */
+export declare const formatDate: (dateString: string | undefined | null | Date) => string;
+/**
+ * Gets a display name from user data
+ */
+export declare const getDisplayName: (user: {
+    name?: {
+        full?: string;
+        first?: string;
+        last?: string;
+    };
+    username?: string;
+} | null | undefined) => string;
+/**
+ * Gets a short display name (first name or username)
+ */
+export declare const getShortDisplayName: (user: {
+    name?: {
+        first?: string;
+        full?: string;
+    };
+    username?: string;
+} | null | undefined) => string;

package/dist/web/types/utils/apiUtils.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 declare function buildSearchParams(params: Record<string, any>): URLSearchParams;
+/**
+ * Build URL with search parameters
+ * @param baseUrl Base URL
+ * @param params Object with parameter key-value pairs
+ * @returns Complete URL with search parameters
+ */
+export declare function buildUrl(baseUrl: string, params?: Record<string, any>): string;
+/**
+ * Common pagination parameters
+ */
+export interface PaginationParams {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Build pagination search parameters
+ * @param params Pagination parameters
+ * @returns URLSearchParams with pagination
+ */
+export declare function buildPaginationParams(params: PaginationParams): URLSearchParams;
+/**
+ * Common API response wrapper
+ */
+export interface ApiResponse<T = any> {
+    data: T;
+    message?: string;
+    success?: boolean;
+}
+/**
+ * Common error response wrapper
+ */
+export interface ErrorResponse {
+    message: string;
+    code: string;
+    status: number;
+    details?: any;
+}
+/**
+ * Safe JSON parsing with error handling
+ * @param data Data to parse
+ * @param fallback Fallback value if parsing fails
+ * @returns Parsed data or fallback
+ */
+export declare function safeJsonParse<T>(data: any, fallback: T): T;

package/dist/web/types/utils/asyncUtils.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Async utilities for common asynchronous patterns and error handling
+ */
+/**
+ * Wrapper for async operations with automatic error handling
+ * Returns null on error instead of throwing
+ */
+export declare function withErrorHandling<T>(operation: () => Promise<T>, errorHandler?: (error: any) => void, context?: string): Promise<T | null>;
+/**
+ * Execute multiple async operations in parallel with error handling
+ */
+export declare function parallelWithErrorHandling<T>(operations: (() => Promise<T>)[], errorHandler?: (error: any, index: number) => void): Promise<(T | 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 declare function retryAsync<T>(operation: () => Promise<T>, maxRetries?: number, baseDelay?: number, shouldRetry?: (error: any) => boolean): Promise<T>;
+/**
+ * Debounce async function calls
+ */
+export declare function debounceAsync<T extends (...args: any[]) => Promise<any>>(func: T, delay: number): (...args: Parameters<T>) => Promise<ReturnType<T>>;
+/**
+ * Throttle async function calls
+ */
+export declare function throttleAsync<T extends (...args: any[]) => Promise<any>>(func: T, limit: number, interval: number): (...args: Parameters<T>) => Promise<ReturnType<T>>;
+/**
+ * Execute async operations sequentially with progress tracking
+ */
+export declare function sequentialWithProgress<T>(operations: (() => Promise<T>)[], onProgress?: (completed: number, total: number) => void): Promise<T[]>;
+/**
+ * Batch async operations
+ */
+export declare function batchAsync<T>(items: T[], batchSize: number, processor: (batch: T[]) => Promise<void>): Promise<void>;
+/**
+ * Create a cancellable async operation
+ */
+export declare function createCancellableAsync<T>(operation: (signal: AbortSignal) => Promise<T>): {
+    execute: () => Promise<T>;
+    cancel: () => void;
+};
+/**
+ * Timeout wrapper for async operations
+ */
+export declare function withTimeout<T>(operation: Promise<T>, timeoutMs: number, timeoutMessage?: string): Promise<T>;
+/**
+ * Execute async operation with loading state
+ */
+export declare function withLoadingState<T>(operation: () => Promise<T>, setLoading: (loading: boolean) => void): Promise<T>;
+/**
+ * Create a promise that resolves after a delay
+ */
+export declare const delay: (ms: number) => Promise<void>;
+/**
+ * Execute async operation with retry on specific errors
+ */
+export declare function retryOnError<T>(operation: () => Promise<T>, retryableErrors: (string | number)[], maxRetries?: number): Promise<T>;

package/dist/web/types/utils/cache.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 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 declare class TTLCache<T> {
+    private cache;
+    private defaultTTL;
+    private hits;
+    private misses;
+    /**
+     * Create a new TTL cache
+     * @param defaultTTL Default TTL in milliseconds (default: 5 minutes)
+     */
+    constructor(defaultTTL?: number);
+    /**
+     * Get a value from cache
+     * @param key Cache key
+     * @returns Cached value or null if not found or expired
+     */
+    get(key: string): T | null;
+    /**
+     * 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;
+    /**
+     * Delete a specific cache entry
+     * @param key Cache key
+     * @returns true if entry was deleted, false if not found
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * 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;
+    /**
+     * Get all valid cache keys
+     * @returns Array of valid cache keys
+     */
+    keys(): string[];
+    /**
+     * Clean up expired entries
+     * @returns Number of entries removed
+     */
+    cleanup(): number;
+    /**
+     * Get cache size (number of entries)
+     */
+    size(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics (keeps cache entries)
+     */
+    resetStats(): void;
+}
+/**
+ * Create a TTL cache instance (convenience function)
+ *
+ * @example
+ * ```typescript
+ * const cache = createCache<string>(5 * 60 * 1000);
+ * ```
+ */
+export declare function createCache<T>(ttl?: number): TTLCache<T>;
+/**
+ * Register a cache for automatic cleanup
+ * @param cache Cache instance to register
+ */
+export declare function registerCacheForCleanup(cache: TTLCache<any>): void;
+/**
+ * Unregister a cache from automatic cleanup
+ * @param cache Cache instance to unregister
+ */
+export declare function unregisterCacheFromCleanup(cache: TTLCache<any>): void;
+/**
+ * Stop all cleanup intervals (useful for testing)
+ * This will clear the interval and unregister all caches
+ */
+export declare function stopAllCleanupIntervals(): void;

package/dist/web/types/utils/deviceManager.d.ts

@@ -0,0 +1,65 @@
+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 declare class DeviceManager {
+    private static DEVICE_KEY;
+    /**
+     * Check if we're in React Native environment
+     */
+    private static isReactNative;
+    /**
+     * Get appropriate storage for the platform
+     */
+    private static getStorage;
+    /**
+     * Get or create device fingerprint for current device
+     */
+    static getDeviceFingerprint(): DeviceFingerprint;
+    /**
+     * Get stored device info or create new one
+     */
+    static getDeviceInfo(): Promise<StoredDeviceInfo>;
+    /**
+     * Create new device info and store it
+     */
+    static createNewDeviceInfo(): Promise<StoredDeviceInfo>;
+    /**
+     * Save device info to storage
+     */
+    static saveDeviceInfo(deviceInfo: StoredDeviceInfo): Promise<void>;
+    /**
+     * Update device name
+     */
+    static updateDeviceName(deviceName: string): Promise<void>;
+    /**
+     * Clear stored device info (useful for testing or reset)
+     */
+    static clearDeviceInfo(): Promise<void>;
+    /**
+     * Generate a unique device ID
+     */
+    private static generateDeviceId;
+    /**
+     * Get a user-friendly device name based on platform
+     */
+    static getDefaultDeviceName(): string;
+}

package/dist/web/types/utils/errorUtils.d.ts

@@ -0,0 +1,46 @@
+import type { ApiError } from '../models/interfaces';
+/**
+ * Error handling utilities for consistent error processing
+ */
+/**
+ * Common error codes
+ */
+export declare const ErrorCodes: {
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly INVALID_TOKEN: "INVALID_TOKEN";
+    readonly MISSING_TOKEN: "MISSING_TOKEN";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly MISSING_PARAMETER: "MISSING_PARAMETER";
+    readonly INVALID_FORMAT: "INVALID_FORMAT";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly ALREADY_EXISTS: "ALREADY_EXISTS";
+    readonly CONFLICT: "CONFLICT";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly CONNECTION_FAILED: "CONNECTION_FAILED";
+};
+/**
+ * Create a standardized API error
+ */
+export declare function createApiError(message: string, code?: string, status?: number, details?: Record<string, unknown>): ApiError;
+/**
+ * Handle common HTTP errors and convert to ApiError
+ */
+export declare function handleHttpError(error: unknown): ApiError;
+/**
+ * Get error code from HTTP status
+ * Exported for use in other modules
+ */
+export declare function getErrorCodeFromStatus(status: number): string;
+/**
+ * Validate required fields and throw error if missing
+ */
+export declare function validateRequiredFields(data: Record<string, unknown>, fields: string[]): void;
+/**
+ * Safe error logging with context
+ */
+export declare function logError(error: unknown, context?: string): void;

package/dist/web/types/utils/hookUtils.d.ts

@@ -0,0 +1,101 @@
+/**
+ * React hook utilities for common patterns and state management
+ */
+/**
+ * Hook for managing async operations with loading, error, and data states
+ */
+export declare function useAsync<T>(asyncFn: () => Promise<T>, deps?: React.DependencyList): {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    execute: () => Promise<T>;
+};
+/**
+ * Hook for managing async operations that execute on mount
+ */
+export declare function useAsyncEffect<T>(asyncFn: () => Promise<T>, deps?: React.DependencyList): {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+};
+/**
+ * Hook for debounced values
+ */
+export declare function useDebounce<T>(value: T, delay: number): T;
+/**
+ * Hook for throttled values
+ */
+export declare function useThrottle<T>(value: T, delay: number): T;
+/**
+ * Hook for previous value
+ */
+export declare function usePrevious<T>(value: T): T | undefined;
+/**
+ * Hook for boolean state with toggle
+ */
+export declare function useToggle(initialValue?: boolean): {
+    value: boolean;
+    toggle: () => void;
+    setTrue: () => void;
+    setFalse: () => void;
+    setValue: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+};
+/**
+ * Hook for counter state
+ */
+export declare function useCounter(initialValue?: number): {
+    count: number;
+    increment: () => void;
+    decrement: () => void;
+    reset: () => void;
+    setValue: (value: number) => void;
+};
+/**
+ * Hook for local storage (platform-safe)
+ */
+export declare function useLocalStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void];
+/**
+ * Hook for session storage (platform-safe)
+ */
+export declare function useSessionStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void];
+/**
+ * Hook for window size (platform-safe)
+ */
+export declare function useWindowSize(): {
+    width: number;
+    height: number;
+};
+/**
+ * Hook for scroll position (platform-safe)
+ */
+export declare function useScrollPosition(): number;
+/**
+ * Hook for online/offline status (platform-safe)
+ */
+export declare function useOnlineStatus(): boolean;
+/**
+ * Hook for media queries (platform-safe)
+ */
+export declare function useMediaQuery(query: string): boolean;
+/**
+ * Hook for keyboard events (platform-safe)
+ */
+export declare function useKeyPress(targetKey: string): boolean;
+/**
+ * Hook for click outside detection (platform-safe)
+ */
+export declare function useClickOutside(ref: React.RefObject<HTMLElement>, handler: () => void): void;
+/**
+ * Hook for form validation
+ */
+export declare function useFormValidation<T extends Record<string, unknown>>(initialValues: T, validationSchema: (values: T) => Partial<Record<keyof T, string>>): {
+    values: T;
+    errors: Partial<Record<keyof T, string>>;
+    touched: Partial<Record<keyof T, boolean>>;
+    isValid: boolean;
+    setValue: (field: keyof T, value: T[keyof T]) => void;
+    setTouchedField: (field: keyof T) => void;
+    setValues: import("react").Dispatch<import("react").SetStateAction<T>>;
+    setErrors: import("react").Dispatch<import("react").SetStateAction<Partial<Record<keyof T, string>>>>;
+    setTouched: import("react").Dispatch<import("react").SetStateAction<Partial<Record<keyof T, boolean>>>>;
+};

package/dist/web/types/utils/index.d.ts

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

package/dist/web/types/utils/languageUtils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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;
+}
+export declare const SUPPORTED_LANGUAGES: LanguageMetadata[];
+/**
+ * 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 declare function getLanguageMetadata(languageCode: string | null | undefined): LanguageMetadata | 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 declare function getLanguageName(languageCode: string | null | undefined): string;
+/**
+ * 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 declare function getNativeLanguageName(languageCode: string | null | undefined): string;
+/**
+ * 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 declare function normalizeLanguageCode(lang?: string | null): string;

package/dist/web/types/utils/loggerUtils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Centralized logging utilities for consistent logging across the application
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+export interface LogContext {
+    component?: string;
+    method?: string;
+    userId?: string;
+    sessionId?: string;
+    requestId?: string;
+    [key: string]: unknown;
+}
+declare class Logger {
+    private level;
+    private isDevelopment;
+    setLevel(level: LogLevel): void;
+    private shouldLog;
+    private formatMessage;
+    debug(message: string, context?: LogContext, ...args: unknown[]): void;
+    info(message: string, context?: LogContext, ...args: unknown[]): void;
+    warn(message: string, context?: LogContext, ...args: unknown[]): void;
+    error(message: string, error?: Error | unknown, context?: LogContext, ...args: unknown[]): void;
+    auth(message: string, context?: LogContext, ...args: unknown[]): void;
+    api(message: string, context?: LogContext, ...args: unknown[]): void;
+    session(message: string, context?: LogContext, ...args: unknown[]): void;
+    user(message: string, context?: LogContext, ...args: unknown[]): void;
+    device(message: string, context?: LogContext, ...args: unknown[]): void;
+    payment(message: string, context?: LogContext, ...args: unknown[]): void;
+    performance(operation: string, duration: number, context?: LogContext): void;
+    errorWithStack(message: string, error: Error, context?: LogContext): void;
+    group(label: string, fn: () => void): void;
+}
+export declare const logger: Logger;
+export declare const logAuth: (message: string, context?: LogContext, ...args: unknown[]) => void;
+export declare const logApi: (message: string, context?: LogContext, ...args: unknown[]) => void;
+export declare const logSession: (message: string, context?: LogContext, ...args: unknown[]) => void;
+export declare const logUser: (message: string, context?: LogContext, ...args: unknown[]) => void;
+export declare const logDevice: (message: string, context?: LogContext, ...args: unknown[]) => void;
+export declare const logPayment: (message: string, context?: LogContext, ...args: unknown[]) => void;
+export declare const logError: (message: string, error?: Error | unknown, context?: LogContext, ...args: unknown[]) => void;
+export declare const logPerformance: (operation: string, duration: number, context?: LogContext) => void;
+export {};

package/dist/web/types/utils/platform.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Platform Detection Utility
+ *
+ * Provides platform detection WITHOUT importing from 'react-native'.
+ * This allows core modules to be used in web/Node.js environments
+ * without bundlers failing on react-native imports.
+ */
+export type PlatformOS = 'ios' | 'android' | 'web' | 'windows' | 'macos' | 'unknown';
+/**
+ * Get the current platform OS
+ * Safe to call from any environment (web, Node.js, React Native)
+ */
+export declare function getPlatformOS(): PlatformOS;
+/**
+ * Check if running on web platform (browser or Node.js)
+ */
+export declare function isWeb(): boolean;
+/**
+ * Check if running in a native app (iOS or Android)
+ */
+export declare function isNative(): boolean;
+/**
+ * Check if running on iOS
+ */
+export declare function isIOS(): boolean;
+/**
+ * Check if running on Android
+ */
+export declare function isAndroid(): boolean;
+/**
+ * Set the platform OS explicitly
+ * Called by React Native entry point to register the platform
+ * This allows lazy detection in environments where react-native is available
+ */
+export declare function setPlatformOS(os: PlatformOS): void;
+/**
+ * Try to initialize platform from react-native if available
+ * This is called lazily when needed, avoiding top-level imports
+ */
+export declare function initPlatformFromReactNative(): Promise<void>;

package/dist/web/types/utils/platformInit.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Platform Initialization - Web/Node.js Version
+ *
+ * This file is resolved by web bundlers (Vite, Webpack, etc.) and Node.js.
+ * It does NOT import from react-native.
+ *
+ * For React Native, Metro resolves platformInit.native.ts instead.
+ */