@oxy.so/core 1.0.0

package/src/shared/utils/errorUtils.ts

@@ -0,0 +1,181 @@
+/**
+ * Error Utility Functions
+ *
+ * Consolidated error handling utilities for the OxyServices ecosystem.
+ * These functions help with common error patterns like checking HTTP status codes.
+ *
+ * @module shared/utils/errorUtils
+ */
+
+/**
+ * Common HTTP status codes used in error checking.
+ */
+export const HttpStatus = {
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500,
+  BAD_GATEWAY: 502,
+  SERVICE_UNAVAILABLE: 503,
+  GATEWAY_TIMEOUT: 504,
+} as const;
+
+/**
+ * Extracts the HTTP status code from an error object.
+ *
+ * @param error - Any error object
+ * @returns The status code if found, undefined otherwise
+ */
+export const getErrorStatus = (error: unknown): number | undefined => {
+  if (!error || typeof error !== 'object') return undefined;
+
+  const err = error as Record<string, unknown>;
+
+  // Direct status property
+  if (typeof err.status === 'number') return err.status;
+
+  // Axios-style response.status
+  if (err.response && typeof err.response === 'object') {
+    const response = err.response as Record<string, unknown>;
+    if (typeof response.status === 'number') return response.status;
+  }
+
+  // statusCode property (some libraries use this)
+  if (typeof err.statusCode === 'number') return err.statusCode;
+
+  return undefined;
+};
+
+/**
+ * Extracts the error message from an error object.
+ *
+ * @param error - Any error object
+ * @param fallback - Fallback message if none found
+ * @returns The error message
+ */
+export const getErrorMessage = (error: unknown, fallback = 'An unknown error occurred'): string => {
+  if (!error) return fallback;
+
+  if (typeof error === 'string') return error;
+
+  if (error instanceof Error) return error.message;
+
+  if (typeof error === 'object') {
+    const err = error as Record<string, unknown>;
+
+    if (typeof err.message === 'string') return err.message;
+    if (typeof err.error === 'string') return err.error;
+
+    // Axios-style response.data.message
+    if (err.response && typeof err.response === 'object') {
+      const response = err.response as Record<string, unknown>;
+      if (response.data && typeof response.data === 'object') {
+        const data = response.data as Record<string, unknown>;
+        if (typeof data.message === 'string') return data.message;
+        if (typeof data.error === 'string') return data.error;
+      }
+    }
+  }
+
+  return fallback;
+};
+
+/**
+ * Check if an error indicates the user is already registered (HTTP 409 Conflict).
+ *
+ * The backend should always return HTTP 409 for duplicate registrations.
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 409 Conflict
+ */
+export const isAlreadyRegisteredError = (error: unknown): boolean => {
+  return getErrorStatus(error) === HttpStatus.CONFLICT;
+};
+
+/**
+ * Check if an error is an authentication error (HTTP 401).
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 401 Unauthorized
+ */
+export const isUnauthorizedError = (error: unknown): boolean => {
+  return getErrorStatus(error) === HttpStatus.UNAUTHORIZED;
+};
+
+/**
+ * Check if an error is a forbidden error (HTTP 403).
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 403 Forbidden
+ */
+export const isForbiddenError = (error: unknown): boolean => {
+  return getErrorStatus(error) === HttpStatus.FORBIDDEN;
+};
+
+/**
+ * Check if an error is a not found error (HTTP 404).
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 404 Not Found
+ */
+export const isNotFoundError = (error: unknown): boolean => {
+  return getErrorStatus(error) === HttpStatus.NOT_FOUND;
+};
+
+/**
+ * Check if an error is a rate limit error (HTTP 429).
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 429 Too Many Requests
+ */
+export const isRateLimitError = (error: unknown): boolean => {
+  return getErrorStatus(error) === HttpStatus.TOO_MANY_REQUESTS;
+};
+
+/**
+ * Check if an error is a server error (HTTP 5xx).
+ *
+ * @param error - Any error object
+ * @returns true if the error is a 5xx server error
+ */
+export const isServerError = (error: unknown): boolean => {
+  const status = getErrorStatus(error);
+  return status !== undefined && status >= 500 && status < 600;
+};
+
+/**
+ * Check if an error is a network error (no response received).
+ *
+ * @param error - Any error object
+ * @returns true if the error appears to be a network error
+ */
+export const isNetworkError = (error: unknown): boolean => {
+  if (!error || typeof error !== 'object') return false;
+
+  const err = error as Record<string, unknown>;
+
+  // Check for common network error indicators
+  if (err.name === 'NetworkError') return true;
+  if (err.code === 'ENOTFOUND' || err.code === 'ECONNREFUSED' || err.code === 'ETIMEDOUT') return true;
+
+  // Axios-style: has request but no response
+  if (err.request && !err.response) return true;
+
+  // Message-based detection
+  const message = getErrorMessage(error, '').toLowerCase();
+  return message.includes('network') || message.includes('connection') || message.includes('timeout');
+};
+
+/**
+ * Check if an error is retryable (network errors or 5xx server errors).
+ *
+ * @param error - Any error object
+ * @returns true if the request should be retried
+ */
+export const isRetryableError = (error: unknown): boolean => {
+  return isNetworkError(error) || isServerError(error) || isRateLimitError(error);
+};

package/src/shared/utils/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared Utility Functions
+ *
+ * Re-exports all shared utilities for convenient importing.
+ *
+ * @module shared/utils
+ */
+
+// Color utilities
+export {
+  darkenColor,
+  lightenColor,
+  hexToRgb,
+  rgbToHex,
+  withOpacity,
+  isLightColor,
+  getContrastTextColor,
+} from './colorUtils';
+
+// Theme utilities
+export {
+  normalizeTheme,
+  normalizeColorScheme,
+  getOppositeTheme,
+  systemPrefersDarkMode,
+  getSystemColorScheme,
+} from './themeUtils';
+export type { ThemeValue } from './themeUtils';
+
+// Error utilities
+export {
+  HttpStatus,
+  getErrorStatus,
+  getErrorMessage,
+  isAlreadyRegisteredError,
+  isUnauthorizedError,
+  isForbiddenError,
+  isNotFoundError,
+  isRateLimitError,
+  isServerError,
+  isNetworkError,
+  isRetryableError,
+} from './errorUtils';
+
+// Network utilities
+export {
+  DEFAULT_CIRCUIT_BREAKER_CONFIG,
+  createCircuitBreakerState,
+  calculateBackoffInterval,
+  recordFailure,
+  recordSuccess,
+  shouldAllowRequest,
+  delay,
+  withRetry,
+} from './networkUtils';
+export type {
+  CircuitBreakerState,
+  CircuitBreakerConfig,
+} from './networkUtils';

package/src/shared/utils/networkUtils.ts

@@ -0,0 +1,248 @@
+/**
+ * Network Utility Functions
+ *
+ * Consolidated network utilities including circuit breaker pattern
+ * and exponential backoff for resilient API calls.
+ *
+ * @module shared/utils/networkUtils
+ */
+
+/**
+ * State for circuit breaker pattern.
+ */
+export interface CircuitBreakerState {
+  /** Number of consecutive failures */
+  consecutiveFailures: number;
+  /** Current interval between retries (ms) */
+  currentInterval: number;
+  /** Base interval for retries (ms) */
+  baseInterval: number;
+  /** Maximum interval cap (ms) */
+  maxInterval: number;
+  /** Number of failures before circuit opens */
+  maxFailures: number;
+  /** Whether the circuit is currently open (blocking requests) */
+  isOpen?: boolean;
+  /** Timestamp when circuit was opened */
+  openedAt?: number;
+}
+
+/**
+ * Configuration for circuit breaker.
+ */
+export interface CircuitBreakerConfig {
+  /** Base interval between retries in milliseconds. Default: 10000 (10s) */
+  baseInterval?: number;
+  /** Maximum interval cap in milliseconds. Default: 60000 (60s) */
+  maxInterval?: number;
+  /** Number of consecutive failures before opening circuit. Default: 5 */
+  maxFailures?: number;
+  /** Time to wait before attempting recovery in milliseconds. Default: 30000 (30s) */
+  recoveryTimeout?: number;
+}
+
+/**
+ * Default circuit breaker configuration.
+ */
+export const DEFAULT_CIRCUIT_BREAKER_CONFIG: Required<CircuitBreakerConfig> = {
+  baseInterval: 10000,
+  maxInterval: 60000,
+  maxFailures: 5,
+  recoveryTimeout: 30000,
+};
+
+/**
+ * Creates initial circuit breaker state.
+ *
+ * @param config - Optional custom configuration
+ * @returns Initial circuit breaker state
+ *
+ * @example
+ * ```ts
+ * const state = createCircuitBreakerState({ maxFailures: 3 });
+ * ```
+ */
+export const createCircuitBreakerState = (
+  config: CircuitBreakerConfig = {}
+): CircuitBreakerState => {
+  const { baseInterval, maxInterval, maxFailures } = {
+    ...DEFAULT_CIRCUIT_BREAKER_CONFIG,
+    ...config,
+  };
+
+  return {
+    consecutiveFailures: 0,
+    currentInterval: baseInterval,
+    baseInterval,
+    maxInterval,
+    maxFailures,
+    isOpen: false,
+  };
+};
+
+/**
+ * Calculates next interval using exponential backoff.
+ *
+ * @param state - Current circuit breaker state
+ * @returns Next interval in milliseconds
+ *
+ * @example
+ * ```ts
+ * const nextInterval = calculateBackoffInterval(state);
+ * await delay(nextInterval);
+ * ```
+ */
+export const calculateBackoffInterval = (state: CircuitBreakerState): number => {
+  const { consecutiveFailures, baseInterval, maxInterval } = state;
+
+  if (consecutiveFailures === 0) return baseInterval;
+
+  const backoffMultiplier = Math.min(
+    Math.pow(2, consecutiveFailures - 1),
+    maxInterval / baseInterval
+  );
+
+  return Math.min(baseInterval * backoffMultiplier, maxInterval);
+};
+
+/**
+ * Records a failure and updates circuit breaker state.
+ *
+ * @param state - Current circuit breaker state
+ * @returns Updated state after recording failure
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await apiCall();
+ *   state = recordSuccess(state);
+ * } catch (error) {
+ *   state = recordFailure(state);
+ * }
+ * ```
+ */
+export const recordFailure = (state: CircuitBreakerState): CircuitBreakerState => {
+  const newFailures = state.consecutiveFailures + 1;
+  const newInterval = calculateBackoffInterval({
+    ...state,
+    consecutiveFailures: newFailures,
+  });
+
+  const shouldOpenCircuit = newFailures >= state.maxFailures;
+  const finalInterval = shouldOpenCircuit ? state.maxInterval : newInterval;
+
+  return {
+    ...state,
+    consecutiveFailures: newFailures,
+    currentInterval: finalInterval,
+    isOpen: shouldOpenCircuit,
+    openedAt: shouldOpenCircuit ? Date.now() : state.openedAt,
+  };
+};
+
+/**
+ * Records a success and resets circuit breaker state.
+ *
+ * @param state - Current circuit breaker state
+ * @returns Reset state after successful request
+ */
+export const recordSuccess = (state: CircuitBreakerState): CircuitBreakerState => {
+  return {
+    ...state,
+    consecutiveFailures: 0,
+    currentInterval: state.baseInterval,
+    isOpen: false,
+    openedAt: undefined,
+  };
+};
+
+/**
+ * Checks if the circuit breaker should allow a request.
+ *
+ * When the circuit is open, it will only allow requests after
+ * the recovery timeout has passed (half-open state).
+ *
+ * @param state - Current circuit breaker state
+ * @param recoveryTimeout - Time to wait before allowing recovery attempts
+ * @returns true if request should be allowed
+ */
+export const shouldAllowRequest = (
+  state: CircuitBreakerState,
+  recoveryTimeout: number = DEFAULT_CIRCUIT_BREAKER_CONFIG.recoveryTimeout
+): boolean => {
+  if (!state.isOpen) return true;
+
+  if (!state.openedAt) return true;
+
+  const timeSinceOpen = Date.now() - state.openedAt;
+  return timeSinceOpen >= recoveryTimeout;
+};
+
+/**
+ * Delays execution for a specified duration.
+ *
+ * @param ms - Milliseconds to delay
+ * @returns Promise that resolves after the delay
+ *
+ * @example
+ * ```ts
+ * await delay(1000); // Wait 1 second
+ * ```
+ */
+export const delay = (ms: number): Promise<void> =>
+  new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Executes a function with exponential backoff retry.
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry options
+ * @returns Result of the function
+ * @throws Last error if all retries fail
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *   () => fetchData(),
+ *   { maxRetries: 3, baseDelay: 1000 }
+ * );
+ * ```
+ */
+export const withRetry = async <T>(
+  fn: () => Promise<T>,
+  options: {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+    shouldRetry?: (error: unknown) => boolean;
+    onRetry?: (error: unknown, attempt: number) => void;
+  } = {}
+): Promise<T> => {
+  const {
+    maxRetries = 3,
+    baseDelay = 1000,
+    maxDelay = 30000,
+    shouldRetry = () => true,
+    onRetry,
+  } = options;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt === maxRetries || !shouldRetry(error)) {
+        throw error;
+      }
+
+      const delayMs = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+      onRetry?.(error, attempt + 1);
+      await delay(delayMs);
+    }
+  }
+
+  throw lastError;
+};

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/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';
+}
+