@oxyhq/core 1.0.0

package/dist/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/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/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/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/types/utils/requestUtils.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Request utilities for HTTP clients
+ *
+ * Provides reusable components for request deduplication, queuing, and logging
+ */
+/**
+ * Request deduplication - prevents duplicate concurrent requests
+ *
+ * When multiple requests with the same key are made simultaneously,
+ * only one request is executed and all callers receive the same result.
+ *
+ * @example
+ * ```typescript
+ * const deduplicator = new RequestDeduplicator();
+ *
+ * // Multiple calls with same key will share the same promise
+ * const promise1 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
+ * const promise2 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
+ * // promise1 === promise2, only one API call is made
+ * ```
+ */
+export declare class RequestDeduplicator {
+    private pendingRequests;
+    /**
+     * Deduplicate a request by key
+     * @param key Unique key for the request
+     * @param requestFn Function that returns a promise
+     * @returns Promise that will be shared if key already exists
+     */
+    deduplicate<T>(key: string, requestFn: () => Promise<T>): Promise<T>;
+    /**
+     * Clear all pending requests
+     */
+    clear(): void;
+    /**
+     * Get number of pending requests
+     */
+    size(): number;
+}
+/**
+ * Request queue with concurrency control
+ *
+ * Limits the number of concurrent requests and queues excess requests.
+ * Useful for rate limiting and preventing request flooding.
+ *
+ * @example
+ * ```typescript
+ * const queue = new RequestQueue(5, 100); // Max 5 concurrent, queue up to 100
+ *
+ * // All requests will be queued and processed with max 5 concurrent
+ * await queue.enqueue(() => fetchUser('1'));
+ * await queue.enqueue(() => fetchUser('2'));
+ * // ...
+ * ```
+ */
+export declare class RequestQueue {
+    private queue;
+    private running;
+    private maxConcurrent;
+    private maxQueueSize;
+    /**
+     * Create a new request queue
+     * @param maxConcurrent Maximum number of concurrent requests (default: 10)
+     * @param maxQueueSize Maximum queue size (default: 100)
+     */
+    constructor(maxConcurrent?: number, maxQueueSize?: number);
+    /**
+     * Enqueue a request
+     * @param requestFn Function that returns a promise
+     * @returns Promise that resolves when request completes
+     */
+    enqueue<T>(requestFn: () => Promise<T>): Promise<T>;
+    /**
+     * Process queued requests
+     */
+    private process;
+    /**
+     * Clear all queued requests
+     */
+    clear(): void;
+    /**
+     * Get queue size
+     */
+    size(): number;
+    /**
+     * Get number of currently running requests
+     */
+    runningCount(): number;
+}
+/** Log level type for SimpleLogger */
+export type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';
+/**
+ * Simple logger with level support
+ *
+ * Lightweight logger for HTTP clients and utilities.
+ * For more advanced logging, use loggerUtils.ts
+ *
+ * @example
+ * ```typescript
+ * const logger = new SimpleLogger(true, 'debug');
+ * logger.debug('Debug message');
+ * logger.info('Info message');
+ * logger.error('Error message');
+ * ```
+ */
+export declare class SimpleLogger {
+    private enabled;
+    private level;
+    private prefix;
+    /**
+     * Create a new simple logger
+     * @param enabled Whether logging is enabled
+     * @param level Minimum log level
+     * @param prefix Prefix for log messages (default: '')
+     */
+    constructor(enabled?: boolean, level?: LogLevel, prefix?: string);
+    private shouldLog;
+    private formatMessage;
+    error(...args: any[]): void;
+    warn(...args: any[]): void;
+    info(...args: any[]): void;
+    debug(...args: any[]): void;
+}

package/dist/types/utils/sessionUtils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Session management utilities
+ *
+ * Provides consistent session normalization, deduplication, and sorting
+ * to ensure sessions are always displayed in a predictable order.
+ */
+import type { ClientSession } from '../models/session';
+/**
+ * Normalize a session to ensure all required fields are present
+ */
+export declare function normalizeSession(session: Partial<ClientSession> & {
+    sessionId: string;
+}): ClientSession;
+/**
+ * Compare two sessions for equality
+ */
+export declare function sessionsEqual(a: ClientSession, b: ClientSession): boolean;
+/**
+ * Sort sessions by lastActive (most recent first), then by sessionId for stability
+ */
+export declare function sortSessions(sessions: ClientSession[]): ClientSession[];
+/**
+ * Deduplicate sessions by sessionId, keeping the most recent version
+ */
+export declare function deduplicateSessions(sessions: ClientSession[]): ClientSession[];
+/**
+ * Deduplicate sessions by userId, keeping only one session per user
+ * Priority: 1) Active session (if provided), 2) Most recent session
+ * This prevents showing duplicate accounts for the same user
+ */
+export declare function deduplicateSessionsByUserId(sessions: ClientSession[], activeSessionId?: string | null): ClientSession[];
+/**
+ * Normalize, deduplicate, and sort sessions
+ * This ensures consistent session ordering across the application
+ *
+ * @param sessions - Array of sessions to normalize
+ * @param activeSessionId - Optional active session ID to prioritize
+ * @param deduplicateByUserId - If true, deduplicate by userId (one account per user). Default: true
+ */
+export declare function normalizeAndSortSessions(sessions: ClientSession[], activeSessionId?: string | null, deduplicateByUserId?: boolean): ClientSession[];
+/**
+ * Merge two session arrays, prioritizing newer data
+ * Returns normalized, deduplicated, and sorted sessions
+ *
+ * @param existing - Existing sessions array
+ * @param incoming - New sessions to merge in
+ * @param activeSessionId - Optional active session ID to prioritize
+ * @param deduplicateByUserId - If true, deduplicate by userId (one account per user). Default: true
+ */
+export declare function mergeSessions(existing: ClientSession[], incoming: ClientSession[], activeSessionId?: string | null, deduplicateByUserId?: boolean): ClientSession[];
+/**
+ * Check if two session arrays are equal (same sessionIds in same order)
+ */
+export declare function sessionsArraysEqual(a: ClientSession[], b: ClientSession[]): boolean;

package/dist/types/utils/validationUtils.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Validation utilities for common data validation patterns
+ */
+/**
+ * Email validation regex
+ */
+export declare const EMAIL_REGEX: RegExp;
+/**
+ * Username validation regex (alphanumeric, underscores, and hyphens, 3-30 chars)
+ */
+export declare const USERNAME_REGEX: RegExp;
+/**
+ * Password validation regex (at least 8 chars, 1 uppercase, 1 lowercase, 1 number)
+ */
+export declare const PASSWORD_REGEX: RegExp;
+/**
+ * Validate email format
+ */
+export declare function isValidEmail(email: string): boolean;
+/**
+ * Validate username format
+ */
+export declare function isValidUsername(username: string): boolean;
+/**
+ * Validate password strength
+ */
+export declare function isValidPassword(password: string): boolean;
+/**
+ * Validate required string
+ */
+export declare function isRequiredString(value: unknown): boolean;
+/**
+ * Validate required number
+ */
+export declare function isRequiredNumber(value: unknown): boolean;
+/**
+ * Validate required boolean
+ */
+export declare function isRequiredBoolean(value: unknown): boolean;
+/**
+ * Validate array
+ */
+export declare function isValidArray(value: unknown): boolean;
+/**
+ * Validate object
+ */
+export declare function isValidObject(value: unknown): boolean;
+/**
+ * Validate UUID format
+ */
+export declare function isValidUUID(uuid: string): boolean;
+/**
+ * Validate URL format
+ */
+export declare function isValidURL(url: string): boolean;
+/**
+ * Validate date string
+ */
+export declare function isValidDate(dateString: string): boolean;
+/**
+ * Validate file size (in bytes)
+ */
+export declare function isValidFileSize(size: number, maxSize: number): boolean;
+/**
+ * Validate file type
+ */
+export declare function isValidFileType(filename: string, allowedTypes: string[]): boolean;
+/**
+ * Sanitize string input
+ */
+export declare function sanitizeString(input: string): string;
+/**
+ * Sanitize HTML input
+ */
+export declare function sanitizeHTML(input: string): string;
+/**
+ * Validate MongoDB ObjectId format
+ * Note: This is a basic format check. For full validation, use mongoose.Types.ObjectId.isValid()
+ * This function works in environments where mongoose may not be available (e.g., client-side)
+ */
+export declare function isValidObjectId(id: string): boolean;
+/**
+ * Validate and sanitize user input
+ */
+export declare function validateAndSanitizeUserInput(input: unknown, type: 'string' | 'email' | 'username'): string | null;

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@oxyhq/core",
+  "version": "1.0.0",
+  "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "source": "src/index.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./crypto": {
+      "types": "./dist/types/crypto/index.d.ts",
+      "import": "./dist/esm/crypto/index.js",
+      "require": "./dist/cjs/crypto/index.js",
+      "default": "./dist/esm/crypto/index.js"
+    },
+    "./shared": {
+      "types": "./dist/types/shared/index.d.ts",
+      "import": "./dist/esm/shared/index.js",
+      "require": "./dist/cjs/shared/index.js",
+      "default": "./dist/esm/shared/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "oxyhq",
+    "sdk",
+    "authentication",
+    "api-client",
+    "crypto",
+    "identity"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oxyhq/sdk",
+    "directory": "packages/core"
+  },
+  "author": "OxyHQ",
+  "license": "MIT",
+  "homepage": "https://oxy.so",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm && npm run build:types && npm run copy-assets",
+    "copy-assets": "cp -r src/i18n/locales dist/cjs/i18n/locales && cp -r src/i18n/locales dist/esm/i18n/locales",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "typescript": "tsc --noEmit",
+    "lint": "biome lint --error-on-warnings ./src"
+  },
+  "dependencies": {
+    "axios": "^1.9.0",
+    "bip39": "^3.1.0",
+    "buffer": "^6.0.3",
+    "elliptic": "^6.6.1",
+    "invariant": "^2.2.4",
+    "jwt-decode": "^4.0.0",
+    "socket.io-client": "^4.8.1",
+    "zod": "^3.25.64"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/elliptic": "^6.4.18",
+    "@types/invariant": "^2.2.34",
+    "@types/node": "^20.19.9",
+    "typescript": "^5.9.2"
+  }
+}