@oxyhq/core 1.0.0

package/dist/esm/OxyServices.base.js

@@ -0,0 +1,259 @@
+/**
+ * OxyServices Base Class
+ *
+ * Contains core infrastructure, HTTP client, request management, and error handling
+ */
+import { jwtDecode } from 'jwt-decode';
+import { handleHttpError } from './utils/errorUtils';
+import { HttpService } from './HttpService';
+import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
+/**
+ * Base class for OxyServices with core infrastructure
+ */
+export class OxyServicesBase {
+    constructor(...args) {
+        const config = args[0];
+        if (!config || typeof config !== 'object') {
+            throw new Error('OxyConfig is required');
+        }
+        this.config = config;
+        this.cloudURL = config.cloudURL || 'https://cloud.oxy.so';
+        // Initialize unified HTTP service (handles auth, caching, deduplication, queuing, retry)
+        this.httpService = new HttpService(config);
+    }
+    // Test-only utility to reset global tokens between jest tests
+    static __resetTokensForTests() {
+        HttpService.__resetTokensForTests();
+    }
+    /**
+     * Make a request with all performance optimizations
+     * This is the main method for all API calls - ensures authentication and performance features
+     */
+    async makeRequest(method, url, data, options = {}) {
+        return this.httpService.request({
+            method,
+            url,
+            data: method !== 'GET' ? data : undefined,
+            params: method === 'GET' ? data : undefined,
+            ...options,
+        });
+    }
+    // ============================================================================
+    // CORE METHODS (HTTP Client, Token Management, Error Handling)
+    // ============================================================================
+    /**
+     * Get the configured Oxy API base URL
+     */
+    getBaseURL() {
+        return this.httpService.getBaseURL();
+    }
+    /**
+     * Get the HTTP service instance
+     * Useful for advanced use cases where direct access to the HTTP service is needed
+     */
+    getClient() {
+        return this.httpService;
+    }
+    /**
+     * Get performance metrics
+     */
+    getMetrics() {
+        return this.httpService.getMetrics();
+    }
+    /**
+     * Clear request cache
+     */
+    clearCache() {
+        this.httpService.clearCache();
+    }
+    /**
+     * Clear specific cache entry
+     */
+    clearCacheEntry(key) {
+        this.httpService.clearCacheEntry(key);
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        return this.httpService.getCacheStats();
+    }
+    /**
+     * Get the configured Oxy Cloud (file storage/CDN) URL
+     */
+    getCloudURL() {
+        return this.cloudURL;
+    }
+    /**
+     * Set authentication tokens
+     */
+    setTokens(accessToken, refreshToken = '') {
+        this.httpService.setTokens(accessToken, refreshToken);
+    }
+    /**
+     * Clear stored authentication tokens
+     */
+    clearTokens() {
+        this.httpService.clearTokens();
+    }
+    /**
+     * Get the current user ID from the access token
+     */
+    getCurrentUserId() {
+        const accessToken = this.httpService.getAccessToken();
+        if (!accessToken) {
+            return null;
+        }
+        try {
+            const decoded = jwtDecode(accessToken);
+            return decoded.userId || decoded.id || null;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    /**
+     * Check if the client has a valid access token (public method)
+     */
+    hasValidToken() {
+        return this.httpService.hasAccessToken();
+    }
+    /**
+     * Get the raw access token (for constructing anchor URLs when needed)
+     */
+    getAccessToken() {
+        return this.httpService.getAccessToken();
+    }
+    /**
+     * Wait for authentication to be ready
+     *
+     * Optimized for high-scale usage with immediate synchronous check and adaptive polling.
+     * Returns immediately if token is already available (0ms delay), otherwise uses
+     * adaptive polling that starts fast (50ms) and gradually increases to reduce CPU usage.
+     *
+     * @param timeoutMs Maximum time to wait in milliseconds (default: 5000ms)
+     * @returns Promise that resolves to true if authentication is ready, false if timeout
+     *
+     * @example
+     * ```typescript
+     * const isReady = await oxyServices.waitForAuth(3000);
+     * if (isReady) {
+     *   // Proceed with authenticated operations
+     * }
+     * ```
+     */
+    async waitForAuth(timeoutMs = 5000) {
+        // Immediate synchronous check - no delay if token is ready
+        if (this.httpService.hasAccessToken()) {
+            return true;
+        }
+        const startTime = performance.now();
+        const maxTime = startTime + timeoutMs;
+        // Adaptive polling: start fast, then slow down to reduce CPU usage
+        let pollInterval = 50; // Start with 50ms
+        while (performance.now() < maxTime) {
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+            if (this.httpService.hasAccessToken()) {
+                return true;
+            }
+            // Increase interval after first few checks (adaptive polling)
+            // This reduces CPU usage for long waits while maintaining responsiveness
+            if (pollInterval < 200) {
+                pollInterval = Math.min(pollInterval * 1.5, 200);
+            }
+        }
+        return false;
+    }
+    /**
+     * Execute a function with automatic authentication retry logic
+     * This handles the common case where API calls are made before authentication completes
+     */
+    async withAuthRetry(operation, operationName, options = {}) {
+        const { maxRetries = 2, retryDelay = 1000, authTimeoutMs = 5000 } = options;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                // First attempt: check if we have a token
+                if (!this.httpService.hasAccessToken()) {
+                    if (attempt === 0) {
+                        // On first attempt, wait briefly for authentication to complete
+                        const authReady = await this.waitForAuth(authTimeoutMs);
+                        if (!authReady) {
+                            throw new OxyAuthenticationTimeoutError(operationName, authTimeoutMs);
+                        }
+                    }
+                    else {
+                        // On retry attempts, fail immediately if no token
+                        throw new OxyAuthenticationError(`Authentication required: ${operationName} requires a valid access token.`, 'AUTH_REQUIRED');
+                    }
+                }
+                // Execute the operation
+                return await operation();
+            }
+            catch (error) {
+                const isLastAttempt = attempt === maxRetries;
+                const errorObj = error && typeof error === 'object' ? error : null;
+                const isAuthError = errorObj?.response?.status === 401 ||
+                    errorObj?.code === 'MISSING_TOKEN' ||
+                    errorObj?.message?.includes('Authentication') ||
+                    error instanceof OxyAuthenticationError;
+                if (isAuthError && !isLastAttempt && !(error instanceof OxyAuthenticationTimeoutError)) {
+                    await new Promise(resolve => setTimeout(resolve, retryDelay));
+                    continue;
+                }
+                // If it's not an auth error, or it's the last attempt, throw the error
+                if (error instanceof OxyAuthenticationError) {
+                    throw error;
+                }
+                throw this.handleError(error);
+            }
+        }
+        // This should never be reached, but TypeScript requires it
+        throw new OxyAuthenticationError(`${operationName} failed after ${maxRetries + 1} attempts`);
+    }
+    /**
+     * Validate the current access token with the server
+     */
+    async validate() {
+        if (!this.hasValidToken()) {
+            return false;
+        }
+        try {
+            const res = await this.makeRequest('GET', '/api/auth/validate', undefined, {
+                cache: false,
+                retry: false,
+            });
+            return res.valid === true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * Centralized error handling
+     */
+    handleError(error) {
+        const api = handleHttpError(error);
+        // Ensure we always have a non-empty message
+        const message = api.message?.trim() || 'An unexpected error occurred';
+        const err = new Error(message);
+        err.code = api.code;
+        err.status = api.status;
+        err.details = api.details;
+        return err;
+    }
+    /**
+     * Health check endpoint
+     */
+    async healthCheck() {
+        try {
+            return await this.makeRequest('GET', '/health', undefined, {
+                cache: false,
+                retry: false,
+                timeout: 5000
+            });
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+}

package/dist/esm/OxyServices.errors.js

@@ -0,0 +1,17 @@
+/**
+ * Custom error types for better error handling
+ */
+export class OxyAuthenticationError extends Error {
+    constructor(message, code = 'AUTH_ERROR', status = 401) {
+        super(message);
+        this.name = 'OxyAuthenticationError';
+        this.code = code;
+        this.status = status;
+    }
+}
+export class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
+    constructor(operationName, timeoutMs) {
+        super(`Authentication timeout (${timeoutMs}ms): ${operationName} requires user authentication. Please ensure the user is logged in before calling this method.`, 'AUTH_TIMEOUT', 408);
+        this.name = 'OxyAuthenticationTimeoutError';
+    }
+}

package/dist/esm/OxyServices.js

@@ -0,0 +1,59 @@
+import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
+// Import mixin composition helper
+import { composeOxyServices } from './mixins';
+/**
+ * OxyServices - Unified client library for interacting with the Oxy API
+ *
+ * This class provides all API functionality in one simple, easy-to-use interface.
+ *
+ * ## Architecture
+ * - **HttpService**: Unified HTTP service handling authentication, caching, deduplication, queuing, and retry
+ * - **OxyServices**: Provides high-level API methods
+ *
+ * ## Mixin Composition
+ * The class is composed using TypeScript mixins for better code organization:
+ * - **Base**: Core infrastructure (HTTP client, request management, error handling)
+ * - **Auth**: Authentication and session management
+ * - **User**: User profiles, follow, notifications
+ * - **Privacy**: Blocked and restricted users
+ * - **Language**: Language detection and metadata
+ * - **Payment**: Payment processing
+ * - **Karma**: Karma system
+ * - **Assets**: File upload and asset management
+ * - **Developer**: Developer API management
+ * - **Location**: Location-based features
+ * - **Analytics**: Analytics tracking
+ * - **Devices**: Device management
+ * - **Utility**: Utility methods and Express middleware
+ *
+ * @example
+ * ```typescript
+ * const oxy = new OxyServices({
+ *   baseURL: 'https://api.oxy.so',
+ *   cloudURL: 'https://cloud.oxy.so'
+ * });
+ * ```
+ */
+// Compose all mixins into the final OxyServices class
+const OxyServicesComposed = composeOxyServices();
+// Export as a named class to avoid TypeScript issues with anonymous class types
+export class OxyServices extends OxyServicesComposed {
+    constructor(config) {
+        super(config);
+    }
+}
+// Re-export error classes for convenience
+export { OxyAuthenticationError, OxyAuthenticationTimeoutError };
+/**
+ * Export the default Oxy Cloud URL (for backward compatibility)
+ */
+export const OXY_CLOUD_URL = 'https://cloud.oxy.so';
+/**
+ * Export the default Oxy API URL (for documentation)
+ */
+export const OXY_API_URL = (typeof process !== 'undefined' && process.env && process.env.OXY_API_URL) || 'https://api.oxy.so';
+/**
+ * Pre-configured client instance for easy import
+ * Uses OXY_API_URL as baseURL and OXY_CLOUD_URL as cloudURL
+ */
+export const oxyClient = new OxyServices({ baseURL: OXY_API_URL, cloudURL: OXY_CLOUD_URL });

package/dist/esm/constants/version.js

@@ -0,0 +1,13 @@
+/**
+ * Package version and metadata constants
+ * This file is auto-generated to avoid runtime dependency on package.json
+ */
+export const packageInfo = {
+    name: "@oxyhq/services",
+    version: "5.2.1",
+    description: "Reusable OxyHQ module to handle authentication, user management, karma system and more 🚀",
+    main: "lib/commonjs/node/index.js",
+    module: "lib/module/node/index.js",
+    types: "lib/typescript/node/index.d.ts"
+};
+export const { name, version, description } = packageInfo;

package/dist/esm/crypto/index.js

@@ -0,0 +1,13 @@
+/**
+ * Oxy Crypto Module
+ *
+ * Provides cryptographic identity management for the Oxy ecosystem.
+ * Handles key generation, secure storage, digital signatures, and recovery phrases.
+ */
+// Import polyfills first - this ensures Buffer is available for bip39 and other libraries
+import './polyfill';
+export { KeyManager } from './keyManager';
+export { SignatureService } from './signatureService';
+export { RecoveryPhraseService } from './recoveryPhrase';
+// Re-export for convenience
+export { KeyManager as default } from './keyManager';