@oxyhq/core 1.0.0

package/src/shared/utils/themeUtils.ts

@@ -0,0 +1,115 @@
+/**
+ * Theme Utility Functions
+ *
+ * Consolidated theme utilities for normalizing and handling color schemes
+ * across the OxyServices ecosystem.
+ *
+ * @module shared/utils/themeUtils
+ */
+
+/**
+ * Valid theme values in the Oxy ecosystem.
+ */
+export type ThemeValue = 'light' | 'dark';
+
+/**
+ * Normalizes a theme value to ensure it's always 'light' or 'dark'.
+ *
+ * @param theme - Theme value (may be 'light' | 'dark' | string | undefined)
+ * @returns Normalized 'light' | 'dark' theme (defaults to 'light')
+ *
+ * @example
+ * ```ts
+ * normalizeTheme('dark');     // 'dark'
+ * normalizeTheme('light');    // 'light'
+ * normalizeTheme('unknown');  // 'light'
+ * normalizeTheme(undefined);  // 'light'
+ * normalizeTheme(null);       // 'light'
+ * ```
+ */
+export const normalizeTheme = (theme?: string | null): ThemeValue =>
+  theme === 'light' || theme === 'dark' ? theme : 'light';
+
+/**
+ * Normalizes a color scheme value with optional fallback chain.
+ *
+ * Handles null/undefined cases from React Native's useColorScheme() hook
+ * with a proper fallback chain.
+ *
+ * @param colorScheme - The color scheme from useColorScheme() hook (may be null/undefined)
+ * @param theme - Optional theme prop as fallback
+ * @returns Normalized 'light' | 'dark' color scheme
+ *
+ * @example
+ * ```ts
+ * // In a React Native component:
+ * const systemScheme = useColorScheme(); // might be null
+ * const colorScheme = normalizeColorScheme(systemScheme, props.theme);
+ *
+ * normalizeColorScheme('dark', 'light');      // 'dark'
+ * normalizeColorScheme(null, 'dark');         // 'dark'
+ * normalizeColorScheme(undefined, undefined); // 'light'
+ * ```
+ */
+export const normalizeColorScheme = (
+  colorScheme?: string | null,
+  theme?: string
+): ThemeValue => {
+  if (colorScheme === 'light' || colorScheme === 'dark') {
+    return colorScheme;
+  }
+
+  if (theme === 'light' || theme === 'dark') {
+    return theme;
+  }
+
+  return 'light';
+};
+
+/**
+ * Gets the opposite theme value.
+ *
+ * @param theme - Current theme value
+ * @returns The opposite theme ('light' → 'dark', 'dark' → 'light')
+ *
+ * @example
+ * ```ts
+ * getOppositeTheme('light'); // 'dark'
+ * getOppositeTheme('dark');  // 'light'
+ * ```
+ */
+export const getOppositeTheme = (theme: ThemeValue): ThemeValue =>
+  theme === 'light' ? 'dark' : 'light';
+
+/**
+ * Checks if the system prefers dark mode.
+ *
+ * This function only works in browser environments.
+ * Returns false in non-browser environments (Node.js, React Native).
+ *
+ * @returns true if system prefers dark mode, false otherwise
+ *
+ * @example
+ * ```ts
+ * if (systemPrefersDarkMode()) {
+ *   setTheme('dark');
+ * }
+ * ```
+ */
+export const systemPrefersDarkMode = (): boolean => {
+  if (typeof window === 'undefined') return false;
+  return window.matchMedia?.('(prefers-color-scheme: dark)').matches ?? false;
+};
+
+/**
+ * Gets the system's preferred color scheme.
+ *
+ * @returns 'dark' if system prefers dark mode, 'light' otherwise
+ *
+ * @example
+ * ```ts
+ * const theme = getSystemColorScheme();
+ * ```
+ */
+export const getSystemColorScheme = (): ThemeValue =>
+  systemPrefersDarkMode() ? 'dark' : 'light';

package/src/types/bip39.d.ts

@@ -0,0 +1,32 @@
+declare module 'bip39' {
+  export interface Wordlist {
+    [index: number]: string;
+    length: number;
+    getWord(index: number): string;
+    getWordIndex(word: string): number;
+  }
+
+  export const wordlists: {
+    english: string[];
+    chinese_simplified: string[];
+    chinese_traditional: string[];
+    french: string[];
+    italian: string[];
+    japanese: string[];
+    korean: string[];
+    spanish: string[];
+  };
+
+  // Use Uint8Array instead of Buffer for React Native compatibility
+  // In Node.js, Buffer extends Uint8Array so this is compatible
+  export function generateMnemonic(strength?: number, rng?: (size: number) => Uint8Array, wordlist?: string[]): string;
+  export function mnemonicToSeed(mnemonic: string, passphrase?: string): Promise<Uint8Array>;
+  export function mnemonicToSeedSync(mnemonic: string, passphrase?: string): Uint8Array;
+  export function mnemonicToEntropy(mnemonic: string, wordlist?: string[]): string;
+  export function entropyToMnemonic(entropy: string, wordlist?: string[]): string;
+  export function validateMnemonic(mnemonic: string, wordlist?: string[]): boolean;
+  export function mnemonicToSeedHex(mnemonic: string, passphrase?: string): Promise<string>;
+  export function mnemonicToSeedHexSync(mnemonic: string, passphrase?: string): string;
+}
+
+

package/src/types/buffer.d.ts

@@ -0,0 +1,97 @@
+declare module 'buffer' {
+  export class Buffer extends Uint8Array {
+    constructor(str: string, encoding?: string);
+    constructor(size: number);
+    constructor(array: Uint8Array);
+    constructor(arrayBuffer: ArrayBuffer);
+    constructor(array: ReadonlyArray<number>);
+    constructor(buffer: Buffer);
+    
+    static from(arrayBuffer: ArrayBuffer, byteOffset?: number, length?: number): Buffer;
+    static from(data: Uint8Array | ReadonlyArray<number>): Buffer;
+    static from(str: string, encoding?: BufferEncoding): Buffer;
+    static from(object: { valueOf(): string | object } | { [Symbol.toPrimitive](hint: 'string'): string }, offsetOrEncoding?: number | string, length?: number): Buffer;
+    
+    static alloc(size: number, fill?: string | Buffer | number, encoding?: BufferEncoding): Buffer;
+    static allocUnsafe(size: number): Buffer;
+    static allocUnsafeSlow(size: number): Buffer;
+    
+    static isBuffer(obj: unknown): obj is Buffer;
+    static isEncoding(encoding: string): encoding is BufferEncoding;
+    static byteLength(string: string | Buffer | ArrayBuffer | SharedArrayBuffer, encoding?: BufferEncoding): number;
+    static concat(list: ReadonlyArray<Uint8Array>, totalLength?: number): Buffer;
+    static compare(buf1: Uint8Array, buf2: Uint8Array): number;
+    
+    write(string: string, encoding?: BufferEncoding): number;
+    write(string: string, offset: number, encoding?: BufferEncoding): number;
+    write(string: string, offset: number, length: number, encoding?: BufferEncoding): number;
+    
+    toString(encoding?: BufferEncoding, start?: number, end?: number): string;
+    toJSON(): { type: 'Buffer'; data: number[] };
+    
+    equals(otherBuffer: Uint8Array): boolean;
+    compare(target: Uint8Array, targetStart?: number, targetEnd?: number, sourceStart?: number, sourceEnd?: number): number;
+    copy(target: Uint8Array, targetStart?: number, sourceStart?: number, sourceEnd?: number): number;
+    
+    slice(start?: number, end?: number): Buffer;
+    subarray(start?: number, end?: number): Buffer;
+    
+    readBigInt64BE(offset?: number): bigint;
+    readBigInt64LE(offset?: number): bigint;
+    readBigUInt64BE(offset?: number): bigint;
+    readBigUInt64LE(offset?: number): bigint;
+    readDoubleBE(offset?: number): number;
+    readDoubleLE(offset?: number): number;
+    readFloatBE(offset?: number): number;
+    readFloatLE(offset?: number): number;
+    readInt8(offset?: number): number;
+    readInt16BE(offset?: number): number;
+    readInt16LE(offset?: number): number;
+    readInt32BE(offset?: number): number;
+    readInt32LE(offset?: number): number;
+    readIntBE(offset: number, byteLength: number): number;
+    readIntLE(offset: number, byteLength: number): number;
+    readUInt8(offset?: number): number;
+    readUInt16BE(offset?: number): number;
+    readUInt16LE(offset?: number): number;
+    readUInt32BE(offset?: number): number;
+    readUInt32LE(offset?: number): number;
+    readUIntBE(offset: number, byteLength: number): number;
+    readUIntLE(offset: number, byteLength: number): number;
+    
+    swap16(): Buffer;
+    swap32(): Buffer;
+    swap64(): Buffer;
+    
+    writeBigInt64BE(value: bigint, offset?: number): number;
+    writeBigInt64LE(value: bigint, offset?: number): number;
+    writeBigUInt64BE(value: bigint, offset?: number): number;
+    writeBigUInt64LE(value: bigint, offset?: number): number;
+    writeDoubleBE(value: number, offset?: number): number;
+    writeDoubleLE(value: number, offset?: number): number;
+    writeFloatBE(value: number, offset?: number): number;
+    writeFloatLE(value: number, offset?: number): number;
+    writeInt8(value: number, offset?: number): number;
+    writeInt16BE(value: number, offset?: number): number;
+    writeInt16LE(value: number, offset?: number): number;
+    writeInt32BE(value: number, offset?: number): number;
+    writeInt32LE(value: number, offset?: number): number;
+    writeIntBE(value: number, offset: number, byteLength: number): number;
+    writeIntLE(value: number, offset: number, byteLength: number): number;
+    writeUInt8(value: number, offset?: number): number;
+    writeUInt16BE(value: number, offset?: number): number;
+    writeUInt16LE(value: number, offset?: number): number;
+    writeUInt32BE(value: number, offset?: number): number;
+    writeUInt32LE(value: number, offset?: number): number;
+    writeUIntBE(value: number, offset: number, byteLength: number): number;
+    writeUIntLE(value: number, offset: number, byteLength: number): number;
+    
+    fill(value: string | Uint8Array | number, offset?: number, end?: number, encoding?: BufferEncoding): this;
+    indexOf(value: string | number | Uint8Array, byteOffset?: number, encoding?: BufferEncoding): number;
+    lastIndexOf(value: string | number | Uint8Array, byteOffset?: number, encoding?: BufferEncoding): number;
+    includes(value: string | number | Buffer, byteOffset?: number, encoding?: BufferEncoding): boolean;
+  }
+
+  type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
+}
+

package/src/types/color.d.ts

@@ -0,0 +1,20 @@
+declare module 'color' {
+  interface Color {
+    (color: string | Color | undefined, model?: string): Color;
+    rgb(): Color;
+    rgba(): Color;
+    alpha(): number;
+    alpha(val: number): Color;
+    fade(val: number): Color;
+    lighten(val: number): Color;
+    darken(val: number): Color;
+    string(): string;
+    hex(): string;
+    toString(): string;
+  }
+
+  function color(color: string | Color | undefined, model?: string): Color;
+  export default color;
+}
+
+

package/src/types/elliptic.d.ts

@@ -0,0 +1,62 @@
+declare module 'elliptic' {
+  export interface KeyPair {
+    getPrivate(enc?: 'hex' | 'array' | 'bn'): string | number[] | any;
+    getPublic(enc?: 'hex'): string;
+    getPublic(enc?: 'array'): number[];
+    getPublic(compressed: boolean, enc?: 'hex'): string;
+    getPublic(compressed: boolean, enc?: 'array'): number[];
+    sign(msg: string | number[]): Signature;
+    verify(msg: string | number[], signature: Signature | string | { r: string | number[]; s: string | number[] }): boolean;
+  }
+
+  export interface Signature {
+    r: any;
+    s: any;
+    recoveryParam: number | null;
+    toDER(enc?: 'hex'): string;
+    toCompact(enc?: 'hex', param?: number): string;
+  }
+
+  export interface Curve {
+    n: any;
+    red: any;
+    g: Point;
+    decodePoint(bytes: string | number[], enc?: string): Point;
+  }
+
+  export interface Point {
+    x: any;
+    y: any;
+    inf: boolean;
+    getX(): any;
+    getY(): any;
+    encode(enc?: string, compressed?: boolean): string | number[];
+    add(p: Point): Point;
+    mul(k: any): Point;
+    eq(p: Point): boolean;
+  }
+
+  export class EC {
+    constructor(curve: string | Curve);
+    keyFromPrivate(priv: string | number[], enc?: string): KeyPair;
+    keyFromPublic(pub: string | number[] | Point, enc?: string): KeyPair;
+    genKeyPair(opts?: { entropy?: string | number[]; pers?: string | number[] }): KeyPair;
+    keyPair(opts?: { priv?: string | number[]; pub?: string | number[] | Point; privEnc?: string; pubEnc?: string }): KeyPair;
+    curve: Curve;
+    n: any;
+    nh: any;
+    g: Point;
+  }
+
+  export type ECKeyPair = KeyPair;
+
+  // ec can be called as a function or used as a constructor
+  export interface ECConstructor {
+    new (curve: string | Curve): EC;
+    (curve: string | Curve): EC;
+  }
+  
+  export const ec: ECConstructor;
+}
+
+

package/src/utils/apiUtils.ts

@@ -0,0 +1,88 @@
+/**
+ * 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: Record<string, any>): URLSearchParams {
+  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: string, params?: Record<string, any>): string {
+  if (!params) return baseUrl;
+  
+  const searchParams = buildSearchParams(params);
+  const queryString = searchParams.toString();
+  
+  return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+}
+
+/**
+ * Common pagination parameters
+ */
+export interface PaginationParams {
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Build pagination search parameters
+ * @param params Pagination parameters
+ * @returns URLSearchParams with pagination
+ */
+export function buildPaginationParams(params: PaginationParams): URLSearchParams {
+  return buildSearchParams(params);
+}
+
+/**
+ * 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 function safeJsonParse<T>(data: any, fallback: T): T {
+  if (typeof data === 'string') {
+    try {
+      return JSON.parse(data);
+    } catch {
+      return fallback;
+    }
+  }
+  return data as T;
+} 

package/src/utils/asyncUtils.ts

@@ -0,0 +1,252 @@
+/**
+ * Async utilities for common asynchronous patterns and error handling
+ */
+
+import { TTLCache, registerCacheForCleanup } from './cache';
+import { logger } from './loggerUtils';
+
+/**
+ * Wrapper for async operations with automatic error handling
+ * Returns null on error instead of throwing
+ */
+export async function withErrorHandling<T>(
+  operation: () => Promise<T>,
+  errorHandler?: (error: any) => void,
+  context?: string
+): Promise<T | null> {
+  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<T>(
+  operations: (() => Promise<T>)[],
+  errorHandler?: (error: any, index: number) => void
+): Promise<(T | null)[]> {
+  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<T>(
+  operation: () => Promise<T>,
+  maxRetries = 3,
+  baseDelay = 1000,
+  shouldRetry?: (error: any) => boolean
+): Promise<T> {
+  let lastError: any;
+  
+  // Default shouldRetry: don't retry on 4xx errors
+  const defaultShouldRetry = (error: any): boolean => {
+    // 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<T extends (...args: any[]) => Promise<any>>(
+  func: T,
+  delay: number
+): (...args: Parameters<T>) => Promise<ReturnType<T>> {
+  let timeoutId: ReturnType<typeof setTimeout>;
+  const lastPromise: Promise<ReturnType<T>> | null = null;
+  
+  return (...args: Parameters<T>): Promise<ReturnType<T>> => {
+    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<T extends (...args: any[]) => Promise<any>>(
+  func: T,
+  limit: number,
+  interval: number
+): (...args: Parameters<T>) => Promise<ReturnType<T>> {
+  let inThrottle = false;
+  let lastPromise: Promise<ReturnType<T>> | null = null;
+  
+  return (...args: Parameters<T>): Promise<ReturnType<T>> => {
+    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<T>(
+  operations: (() => Promise<T>)[],
+  onProgress?: (completed: number, total: number) => void
+): Promise<T[]> {
+  const results: T[] = [];
+  
+  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<T>(
+  items: T[],
+  batchSize: number,
+  processor: (batch: T[]) => Promise<void>
+): Promise<void> {
+  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<T>(
+  operation: (signal: AbortSignal) => Promise<T>
+): { execute: () => Promise<T>; cancel: () => void } {
+  let abortController: AbortController | null = null;
+  
+  return {
+    execute: async () => {
+      abortController = new AbortController();
+      return await operation(abortController.signal);
+    },
+    cancel: () => {
+      abortController?.abort();
+    }
+  };
+}
+
+/**
+ * Timeout wrapper for async operations
+ */
+export async function withTimeout<T>(
+  operation: Promise<T>,
+  timeoutMs: number,
+  timeoutMessage?: string
+): Promise<T> {
+  const timeoutPromise = new Promise<never>((_, 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<T>(
+  operation: () => Promise<T>,
+  setLoading: (loading: boolean) => void
+): Promise<T> {
+  setLoading(true);
+  try {
+    return await operation();
+  } finally {
+    setLoading(false);
+  }
+}
+
+/**
+ * Create a promise that resolves after a delay
+ */
+export const delay = (ms: number): Promise<void> => 
+  new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Execute async operation with retry on specific errors
+ */
+export async function retryOnError<T>(
+  operation: () => Promise<T>,
+  retryableErrors: (string | number)[],
+  maxRetries = 3
+): Promise<T> {
+  return retryAsync(operation, maxRetries, 1000, (error) => {
+    const errorCode = error?.code || error?.status || error?.message;
+    return retryableErrors.includes(errorCode);
+  });
+}