@oxyhq/services 5.13.15 → 5.13.17

package/lib/module/core/OxyServices.js

@@ -22,7 +22,7 @@
  * // Upload a file (browser File API)
  * const fileInput = document.querySelector('input[type=file]');
  * const file = fileInput.files[0];
- * await oxy.uploadFile(file);
+ * await oxy.uploadRawFile(file);
  *
  * // Get a file stream URL for <img src>
  * const url = oxy.getFileStreamUrl('fileId');
@@ -58,2181 +58,60 @@
  *
  * See method JSDoc for more details and options.
  */
-import { jwtDecode } from 'jwt-decode';
-import { normalizeLanguageCode, getLanguageMetadata, getLanguageName, getNativeLanguageName } from '../utils/languageUtils';
 
-/**
- * OxyConfig - Configuration for OxyServices
- * @property baseURL - The Oxy API base URL (e.g., https://api.oxy.so)
- * @property cloudURL - The Oxy Cloud (file storage/CDN) URL (e.g., https://cloud.oxy.so)
- */
+import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
 
-import { handleHttpError } from '../utils/errorUtils';
-import { buildSearchParams, buildPaginationParams } from '../utils/apiUtils';
-import { HttpClient } from './HttpClient';
-import { RequestManager } from './RequestManager';
-/**
- * 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';
-  }
-}
+// 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:
- * - HttpClient: Handles HTTP communication and authentication
- * - RequestManager: Handles caching, deduplication, queuing, and retry
- * - OxyServices: Provides high-level API methods
+ * 
+ * ## Architecture
+ * - **HttpClient**: Handles HTTP communication and authentication
+ * - **RequestManager**: Handles 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
+ * - **TOTP**: Two-factor authentication enrollment
+ * - **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'
+ * });
+ * ```
  */
-export class OxyServices {
-  /**
-   * Creates a new instance of the OxyServices client
-   * @param config - Configuration for the client
-   *   config.baseURL: Oxy API URL (e.g., https://api.oxy.so)
-   *   config.cloudURL: Oxy Cloud URL (e.g., https://cloud.oxy.so)
-   */
-  constructor(config) {
-    this.config = config;
-    this.cloudURL = config.cloudURL || OXY_CLOUD_URL;
-
-    // Initialize HTTP client (handles authentication and interceptors)
-    this.httpClient = new HttpClient(config);
-
-    // Initialize request manager (handles caching, deduplication, queuing, retry)
-    this.requestManager = new RequestManager(this.httpClient, config);
-  }
-
-  // Test-only utility to reset global tokens between jest tests
-  static __resetTokensForTests() {
-    HttpClient.__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.requestManager.request(method, url, data, options);
-  }
-
-  // ============================================================================
-  // CORE METHODS (HTTP Client, Token Management, Error Handling)
-  // ============================================================================
-
-  /**
-   * Get the configured Oxy API base URL
-   */
-  getBaseURL() {
-    return this.httpClient.getBaseURL();
-  }
-
-  /**
-   * Get the HTTP client instance
-   * Useful for advanced use cases where direct access to the HTTP client is needed
-   */
-  getClient() {
-    return this.httpClient;
-  }
-
-  /**
-   * Get performance metrics
-   */
-  getMetrics() {
-    return this.requestManager.getMetrics();
-  }
-
-  /**
-   * Clear request cache
-   */
-  clearCache() {
-    this.requestManager.clearCache();
-  }
-
-  /**
-   * Clear specific cache entry
-   */
-  clearCacheEntry(key) {
-    this.requestManager.clearCacheEntry(key);
-  }
-
-  /**
-   * Get cache statistics
-   */
-  getCacheStats() {
-    return this.requestManager.getCacheStats();
-  }
-
-  /**
-   * Get the configured Oxy Cloud (file storage/CDN) URL
-   */
-  getCloudURL() {
-    return this.cloudURL;
-  }
-
-  /**
-   * Set authentication tokens
-   */
-  setTokens(accessToken, refreshToken = '') {
-    this.httpClient.setTokens(accessToken, refreshToken);
-  }
-
-  /**
-   * Clear stored authentication tokens
-   */
-  clearTokens() {
-    this.httpClient.clearTokens();
-  }
-
-  /**
-   * Get the current user ID from the access token
-   */
-  getCurrentUserId() {
-    const accessToken = this.httpClient.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
-   */
-  hasAccessToken() {
-    return this.httpClient.hasAccessToken();
-  }
-
-  /**
-   * Check if the client has a valid access token (public method)
-   */
-  hasValidToken() {
-    return this.httpClient.hasAccessToken();
-  }
-
-  /**
-   * Get the raw access token (for constructing anchor URLs when needed)
-   */
-  getAccessToken() {
-    return this.httpClient.getAccessToken();
-  }
-
-  /**
-   * Wait for authentication to be ready (public method)
-   * Useful for apps that want to ensure authentication is complete before proceeding
-   */
-  async waitForAuth(timeoutMs = 5000) {
-    return this.waitForAuthentication(timeoutMs);
-  }
-
-  /**
-   * Wait for authentication to be ready with timeout
-   */
-  async waitForAuthentication(timeoutMs = 5000) {
-    const startTime = Date.now();
-    const checkInterval = 100; // Check every 100ms
-
-    while (Date.now() - startTime < timeoutMs) {
-      if (this.httpClient.hasAccessToken()) {
-        return true;
-      }
-      await new Promise(resolve => setTimeout(resolve, checkInterval));
-    }
-    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.httpClient.hasAccessToken()) {
-          if (attempt === 0) {
-            // On first attempt, wait briefly for authentication to complete
-            const authReady = await this.waitForAuthentication(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 isAuthError = error?.response?.status === 401 || error?.code === 'MISSING_TOKEN' || error?.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.hasAccessToken()) {
-      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);
-    const err = new Error(api.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
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // AUTHENTICATION METHODS
-  // ============================================================================
-
-  /**
-   * Sign up a new user
-   */
-  async signUp(username, email, password) {
-    try {
-      const res = await this.makeRequest('POST', '/api/auth/signup', {
-        username,
-        email,
-        password
-      }, {
-        cache: false
-      });
-      if (!res || typeof res === 'object' && Object.keys(res).length === 0) {
-        throw new OxyAuthenticationError('Sign up failed', 'SIGNUP_FAILED', 400);
-      }
-      return res;
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Request account recovery (send verification code)
-   */
-  async requestRecovery(identifier) {
-    try {
-      return await this.makeRequest('POST', '/api/auth/recover/request', {
-        identifier
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Verify recovery code
-   */
-  async verifyRecoveryCode(identifier, code) {
-    try {
-      return await this.makeRequest('POST', '/api/auth/recover/verify', {
-        identifier,
-        code
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Reset password using verified code
-   */
-  async resetPassword(identifier, code, newPassword) {
-    try {
-      return await this.makeRequest('POST', '/api/auth/recover/reset', {
-        identifier,
-        code,
-        newPassword
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Reset password using TOTP code (recommended recovery)
-   */
-  async resetPasswordWithTotp(identifier, code, newPassword) {
-    try {
-      return await this.makeRequest('POST', '/api/auth/recover/totp/reset', {
-        identifier,
-        code,
-        newPassword
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-  async resetPasswordWithBackupCode(identifier, backupCode, newPassword) {
-    try {
-      return await this.makeRequest('POST', '/api/auth/recover/backup/reset', {
-        identifier,
-        backupCode,
-        newPassword
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-  async resetPasswordWithRecoveryKey(identifier, recoveryKey, newPassword) {
-    try {
-      return await this.makeRequest('POST', '/api/auth/recover/recovery-key/reset', {
-        identifier,
-        recoveryKey,
-        newPassword
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Sign in with device management
-   */
-  async signIn(username, password, deviceName, deviceFingerprint) {
-    try {
-      return await this.makeRequest('POST', '/api/auth/login', {
-        username,
-        password,
-        deviceName,
-        deviceFingerprint
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Complete login by verifying TOTP with MFA token
-   */
-  async verifyTotpLogin(mfaToken, code) {
-    try {
-      return await this.makeRequest('POST', '/api/auth/totp/verify-login', {
-        mfaToken,
-        code
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get user by session ID
-   */
-  async getUserBySession(sessionId) {
-    try {
-      return await this.makeRequest('GET', `/api/session/user/${sessionId}`, undefined, {
-        cache: true,
-        cacheTTL: 2 * 60 * 1000 // 2 minutes cache for user data
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Batch get multiple user profiles by session IDs (optimized for account switching)
-   * Returns array of { sessionId, user } objects
-   */
-  async getUsersBySessions(sessionIds) {
-    try {
-      if (!Array.isArray(sessionIds) || sessionIds.length === 0) {
-        return [];
-      }
-
-      // Deduplicate and sort sessionIds for consistent cache keys
-      const uniqueSessionIds = Array.from(new Set(sessionIds)).sort();
-      return await this.makeRequest('POST', '/api/session/users/batch', {
-        sessionIds: uniqueSessionIds
-      }, {
-        cache: true,
-        cacheTTL: 2 * 60 * 1000,
-        // 2 minutes cache
-        deduplicate: true // Important for batch requests
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get access token by session ID and set it in the token store
-   */
-  async getTokenBySession(sessionId) {
-    try {
-      const res = await this.makeRequest('GET', `/api/session/token/${sessionId}`, undefined, {
-        cache: false,
-        retry: false
-      });
-
-      // Set the token in the centralized token store
-      this.setTokens(res.accessToken);
-      return res;
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get sessions by session ID
-   */
-  async getSessionsBySessionId(sessionId) {
-    try {
-      return await this.makeRequest('GET', `/api/session/sessions/${sessionId}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Logout from a specific session
-   */
-  async logoutSession(sessionId, targetSessionId) {
-    try {
-      const url = targetSessionId ? `/api/session/logout/${sessionId}/${targetSessionId}` : `/api/session/logout/${sessionId}`;
-      await this.makeRequest('POST', url, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Logout from all sessions
-   */
-  async logoutAllSessions(sessionId) {
-    try {
-      await this.makeRequest('POST', `/api/session/logout-all/${sessionId}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Validate session
-   */
-  async validateSession(sessionId, options = {}) {
-    try {
-      const params = new URLSearchParams();
-      if (options.deviceFingerprint) {
-        params.append('deviceFingerprint', options.deviceFingerprint);
-      }
-      if (options.useHeaderValidation) {
-        params.append('useHeaderValidation', 'true');
-      }
-      const url = `/api/session/validate/${sessionId}`;
-      const urlParams = {};
-      if (options.deviceFingerprint) urlParams.deviceFingerprint = options.deviceFingerprint;
-      if (options.useHeaderValidation) urlParams.useHeaderValidation = 'true';
-      return await this.makeRequest('GET', url, urlParams, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Check username availability
-   */
-  async checkUsernameAvailability(username) {
-    try {
-      return await this.makeRequest('GET', `/api/auth/check-username/${username}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Check email availability
-   */
-  async checkEmailAvailability(email) {
-    try {
-      return await this.makeRequest('GET', `/api/auth/check-email/${email}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // USER METHODS
-  // ============================================================================
-
-  /**
-   * Get profile by username
-   */
-  async getProfileByUsername(username) {
-    try {
-      return await this.makeRequest('GET', `/api/profiles/username/${username}`, undefined, {
-        cache: true,
-        cacheTTL: 5 * 60 * 1000 // 5 minutes cache for profiles
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // TOTP ENROLLMENT
-  // ============================================================================
-
-  async startTotpEnrollment(sessionId) {
-    try {
-      // Note: x-session-id header is handled by HttpClient interceptors if needed
-      return await this.makeRequest('POST', '/api/auth/totp/enroll/start', {
-        sessionId
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-  async verifyTotpEnrollment(sessionId, code) {
-    try {
-      return await this.makeRequest('POST', '/api/auth/totp/enroll/verify', {
-        sessionId,
-        code
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-  async disableTotp(sessionId, code) {
-    try {
-      return await this.makeRequest('POST', '/api/auth/totp/disable', {
-        sessionId,
-        code
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Search user profiles
-   */
-  async searchProfiles(query, pagination) {
-    try {
-      const params = {
-        query,
-        ...pagination
-      };
-      const searchParams = buildSearchParams(params);
-      const paramsObj = {};
-      searchParams.forEach((value, key) => {
-        paramsObj[key] = value;
-      });
-      return await this.makeRequest('GET', '/api/profiles/search', paramsObj, {
-        cache: true,
-        cacheTTL: 2 * 60 * 1000 // 2 minutes cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get profile recommendations
-   */
-  async getProfileRecommendations() {
-    return this.withAuthRetry(async () => {
-      return await this.makeRequest('GET', '/api/profiles/recommendations', undefined, {
-        cache: true
-      });
-    }, 'getProfileRecommendations');
-  }
-
-  /**
-   * Get user by ID
-   */
-  async getUserById(userId) {
-    try {
-      return await this.makeRequest('GET', `/api/users/${userId}`, undefined, {
-        cache: true,
-        cacheTTL: 5 * 60 * 1000 // 5 minutes cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get current user
-   */
-  async getCurrentUser() {
-    return this.withAuthRetry(async () => {
-      return await this.makeRequest('GET', '/api/users/me', undefined, {
-        cache: true,
-        cacheTTL: 1 * 60 * 1000 // 1 minute cache for current user
-      });
-    }, 'getCurrentUser');
-  }
-
-  /**
-   * Update user profile
-   */
-  async updateProfile(updates) {
-    try {
-      return await this.makeRequest('PUT', '/api/users/me', updates, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get privacy settings for a user
-   * @param userId - The user ID (defaults to current user)
-   */
-  async getPrivacySettings(userId) {
-    try {
-      const id = userId || (await this.getCurrentUser()).id;
-      return await this.makeRequest('GET', `/api/privacy/${id}/privacy`, undefined, {
-        cache: true,
-        cacheTTL: 2 * 60 * 1000 // 2 minutes cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Update privacy settings
-   * @param settings - Partial privacy settings object
-   * @param userId - The user ID (defaults to current user)
-   */
-  async updatePrivacySettings(settings, userId) {
-    try {
-      const id = userId || (await this.getCurrentUser()).id;
-      return await this.makeRequest('PATCH', `/api/privacy/${id}/privacy`, settings, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // BLOCKED USERS METHODS
-  // ============================================================================
-
-  /**
-   * Get list of blocked users
-   * @returns Array of blocked users
-   */
-  async getBlockedUsers() {
-    try {
-      return await this.makeRequest('GET', '/api/privacy/blocked', undefined, {
-        cache: true,
-        cacheTTL: 1 * 60 * 1000 // 1 minute cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Block a user
-   * @param userId - The user ID to block
-   * @returns Success message
-   */
-  async blockUser(userId) {
-    try {
-      if (!userId) {
-        throw new Error('User ID is required');
-      }
-      return await this.makeRequest('POST', `/api/privacy/blocked/${userId}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Unblock a user
-   * @param userId - The user ID to unblock
-   * @returns Success message
-   */
-  async unblockUser(userId) {
-    try {
-      if (!userId) {
-        throw new Error('User ID is required');
-      }
-      return await this.makeRequest('DELETE', `/api/privacy/blocked/${userId}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Extract user ID from blocked/restricted user object
-   * @private
-   */
-  extractUserId(userIdField) {
-    return typeof userIdField === 'string' ? userIdField : userIdField._id;
-  }
-
-  /**
-   * Check if a user is in a list (blocked or restricted)
-   * @private
-   */
-  async isUserInList(userId, getUserList, getIdField) {
-    try {
-      if (!userId) {
-        return false;
-      }
-      const users = await getUserList();
-      return users.some(item => {
-        const itemId = this.extractUserId(getIdField(item));
-        return itemId === userId;
-      });
-    } catch (error) {
-      // If there's an error, assume not in list to avoid breaking functionality
-      if (__DEV__) {
-        console.warn('Error checking user list:', error);
-      }
-      return false;
-    }
-  }
-
-  /**
-   * Check if a user is blocked
-   * @param userId - The user ID to check
-   * @returns True if the user is blocked, false otherwise
-   */
-  async isUserBlocked(userId) {
-    return this.isUserInList(userId, () => this.getBlockedUsers(), block => block.blockedId);
-  }
-
-  // ============================================================================
-  // RESTRICTED USERS METHODS
-  // ============================================================================
-
-  /**
-   * Get list of restricted users
-   * @returns Array of restricted users
-   */
-  async getRestrictedUsers() {
-    try {
-      return await this.makeRequest('GET', '/api/privacy/restricted', undefined, {
-        cache: true,
-        cacheTTL: 1 * 60 * 1000 // 1 minute cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Restrict a user (limit their interactions without fully blocking)
-   * @param userId - The user ID to restrict
-   * @returns Success message
-   */
-  async restrictUser(userId) {
-    try {
-      if (!userId) {
-        throw new Error('User ID is required');
-      }
-      return await this.makeRequest('POST', `/api/privacy/restricted/${userId}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Unrestrict a user
-   * @param userId - The user ID to unrestrict
-   * @returns Success message
-   */
-  async unrestrictUser(userId) {
-    try {
-      if (!userId) {
-        throw new Error('User ID is required');
-      }
-      return await this.makeRequest('DELETE', `/api/privacy/restricted/${userId}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Check if a user is restricted
-   * @param userId - The user ID to check
-   * @returns True if the user is restricted, false otherwise
-   */
-  async isUserRestricted(userId) {
-    return this.isUserInList(userId, () => this.getRestrictedUsers(), restrict => restrict.restrictedId);
-  }
-
-  /**
-   * Request account verification
-   */
-  async requestAccountVerification(reason, evidence) {
-    try {
-      return await this.makeRequest('POST', '/api/users/verify/request', {
-        reason,
-        evidence
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Download account data export
-   */
-  async downloadAccountData(format = 'json') {
-    try {
-      // Use axios instance directly for blob responses since RequestManager doesn't handle blobs
-      const axiosInstance = this.httpClient.getAxiosInstance();
-      const response = await axiosInstance.get(`/api/users/me/data?format=${format}`, {
-        responseType: 'blob'
-      });
-      return response.data;
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Delete account permanently
-   * @param password - User password for confirmation
-   * @param confirmText - Confirmation text (usually username)
-   */
-  async deleteAccount(password, confirmText) {
-    try {
-      return await this.makeRequest('DELETE', '/api/users/me', {
-        password,
-        confirmText
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // LANGUAGE METHODS
-  // ============================================================================
+// Compose all mixins into the final OxyServices class
+const OxyServicesComposed = composeOxyServices();
 
-  /**
-   * Get the current language from storage or user profile
-   * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
-   * @returns The current language code (e.g., 'en-US') or null if not set
-   */
-  async getCurrentLanguage(storageKeyPrefix = 'oxy_session') {
-    try {
-      // First try to get from user profile if authenticated
-      try {
-        const user = await this.getCurrentUser();
-        const userLanguage = user?.language;
-        if (userLanguage) {
-          return normalizeLanguageCode(userLanguage) || userLanguage;
-        }
-      } catch (e) {
-        // User not authenticated or error, continue to storage
-      }
-
-      // Fall back to storage
-      const storage = await this.getStorage();
-      const storageKey = `${storageKeyPrefix}_language`;
-      const storedLanguage = await storage.getItem(storageKey);
-      if (storedLanguage) {
-        return normalizeLanguageCode(storedLanguage) || storedLanguage;
-      }
-      return null;
-    } catch (error) {
-      if (__DEV__) {
-        console.warn('Failed to get current language:', error);
-      }
-      return null;
-    }
-  }
-
-  /**
-   * Get the current language with metadata (name, nativeName, etc.)
-   * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
-   * @returns Language metadata object or null if not set
-   */
-  async getCurrentLanguageMetadata(storageKeyPrefix = 'oxy_session') {
-    const languageCode = await this.getCurrentLanguage(storageKeyPrefix);
-    return getLanguageMetadata(languageCode);
-  }
-
-  /**
-   * Get the current language name (e.g., 'English')
-   * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
-   * @returns Language name or null if not set
-   */
-  async getCurrentLanguageName(storageKeyPrefix = 'oxy_session') {
-    const languageCode = await this.getCurrentLanguage(storageKeyPrefix);
-    if (!languageCode) return null;
-    return getLanguageName(languageCode);
-  }
-
-  /**
-   * Get the current native language name (e.g., 'Español')
-   * @param storageKeyPrefix - Optional prefix for storage key (default: 'oxy_session')
-   * @returns Native language name or null if not set
-   */
-  async getCurrentNativeLanguageName(storageKeyPrefix = 'oxy_session') {
-    const languageCode = await this.getCurrentLanguage(storageKeyPrefix);
-    if (!languageCode) return null;
-    return getNativeLanguageName(languageCode);
-  }
-
-  /**
-   * Get appropriate storage for the platform (similar to DeviceManager)
-   * @private
-   */
-  async getStorage() {
-    const isReactNative = typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
-    if (isReactNative) {
-      try {
-        const asyncStorageModule = await import('@react-native-async-storage/async-storage');
-        const storage = asyncStorageModule.default;
-        return {
-          getItem: storage.getItem.bind(storage),
-          setItem: storage.setItem.bind(storage),
-          removeItem: storage.removeItem.bind(storage)
-        };
-      } catch (error) {
-        console.error('AsyncStorage not available in React Native:', error);
-        throw new Error('AsyncStorage is required in React Native environment');
-      }
-    } else {
-      // Use localStorage for web
-      return {
-        getItem: async key => {
-          if (typeof window !== 'undefined' && window.localStorage) {
-            return localStorage.getItem(key);
-          }
-          return null;
-        },
-        setItem: async (key, value) => {
-          if (typeof window !== 'undefined' && window.localStorage) {
-            localStorage.setItem(key, value);
-          }
-        },
-        removeItem: async key => {
-          if (typeof window !== 'undefined' && window.localStorage) {
-            localStorage.removeItem(key);
-          }
-        }
-      };
-    }
-  }
-
-  /**
-   * Update user by ID (admin function)
-   */
-  async updateUser(userId, updates) {
-    try {
-      return await this.makeRequest('PUT', `/api/users/${userId}`, updates, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Follow a user
-   */
-  async followUser(userId) {
-    try {
-      return await this.makeRequest('POST', `/api/users/${userId}/follow`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Unfollow a user
-   */
-  async unfollowUser(userId) {
-    try {
-      return await this.makeRequest('DELETE', `/api/users/${userId}/follow`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get follow status
-   */
-  async getFollowStatus(userId) {
-    try {
-      return await this.makeRequest('GET', `/api/users/${userId}/follow-status`, undefined, {
-        cache: true,
-        cacheTTL: 1 * 60 * 1000 // 1 minute cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get user followers
-   */
-  async getUserFollowers(userId, pagination) {
-    try {
-      const params = buildPaginationParams(pagination || {});
-      const response = await this.makeRequest('GET', `/api/users/${userId}/followers`, params, {
-        cache: true,
-        cacheTTL: 2 * 60 * 1000 // 2 minutes cache
-      });
-      return {
-        followers: response.data || [],
-        total: response.pagination.total,
-        hasMore: response.pagination.hasMore
-      };
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get user following
-   */
-  async getUserFollowing(userId, pagination) {
-    try {
-      const params = buildPaginationParams(pagination || {});
-      const response = await this.makeRequest('GET', `/api/users/${userId}/following`, params, {
-        cache: true,
-        cacheTTL: 2 * 60 * 1000 // 2 minutes cache
-      });
-      return {
-        following: response.data || [],
-        total: response.pagination.total,
-        hasMore: response.pagination.hasMore
-      };
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get notifications
-   */
-  async getNotifications() {
-    return this.withAuthRetry(async () => {
-      return await this.makeRequest('GET', '/api/notifications', undefined, {
-        cache: false // Don't cache notifications - always get fresh data
-      });
-    }, 'getNotifications');
-  }
-
-  /**
-   * Get unread notification count
-   */
-  async getUnreadCount() {
-    try {
-      const res = await this.makeRequest('GET', '/api/notifications/unread-count', undefined, {
-        cache: false // Don't cache unread count - always get fresh data
-      });
-      return res.count;
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Create notification
-   */
-  async createNotification(data) {
-    try {
-      return await this.makeRequest('POST', '/api/notifications', data, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Mark notification as read
-   */
-  async markNotificationAsRead(notificationId) {
-    try {
-      await this.makeRequest('PUT', `/api/notifications/${notificationId}/read`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Mark all notifications as read
-   */
-  async markAllNotificationsAsRead() {
-    try {
-      await this.makeRequest('PUT', '/api/notifications/read-all', undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Delete notification
-   */
-  async deleteNotification(notificationId) {
-    try {
-      await this.makeRequest('DELETE', `/api/notifications/${notificationId}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // PAYMENT METHODS
-  // ============================================================================
-
-  /**
-   * Create a payment
-   */
-  async createPayment(data) {
-    try {
-      return await this.makeRequest('POST', '/api/payments', data, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get payment by ID
-   */
-  async getPayment(paymentId) {
-    try {
-      return await this.makeRequest('GET', `/api/payments/${paymentId}`, undefined, {
-        cache: true,
-        cacheTTL: 5 * 60 * 1000 // 5 minutes cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get user payments
-   */
-  async getUserPayments() {
-    try {
-      return await this.makeRequest('GET', '/api/payments/user', undefined, {
-        cache: false // Don't cache user payments - always get fresh data
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // KARMA METHODS
-  // ============================================================================
-
-  /**
-   * Get user karma
-   */
-  async getUserKarma(userId) {
-    try {
-      return await this.makeRequest('GET', `/api/karma/${userId}`, undefined, {
-        cache: true,
-        cacheTTL: 2 * 60 * 1000 // 2 minutes cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Give karma to user
-   */
-  async giveKarma(userId, amount, reason) {
-    try {
-      return await this.makeRequest('POST', `/api/karma/${userId}/give`, {
-        amount,
-        reason
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get user karma total
-   */
-  async getUserKarmaTotal(userId) {
-    try {
-      return await this.makeRequest('GET', `/api/karma/${userId}/total`, undefined, {
-        cache: true,
-        cacheTTL: 2 * 60 * 1000 // 2 minutes cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get user karma history
-   */
-  async getUserKarmaHistory(userId, limit, offset) {
-    try {
-      const params = {};
-      if (limit) params.limit = limit;
-      if (offset) params.offset = offset;
-      return await this.makeRequest('GET', `/api/karma/${userId}/history`, params, {
-        cache: true,
-        cacheTTL: 2 * 60 * 1000 // 2 minutes cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get karma leaderboard
-   */
-  async getKarmaLeaderboard() {
-    try {
-      return await this.makeRequest('GET', '/api/karma/leaderboard', undefined, {
-        cache: true,
-        cacheTTL: 5 * 60 * 1000 // 5 minutes cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get karma rules
-   */
-  async getKarmaRules() {
-    try {
-      return await this.makeRequest('GET', '/api/karma/rules', undefined, {
-        cache: true,
-        cacheTTL: 30 * 60 * 1000 // 30 minutes cache (rules don't change often)
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // FILE METHODS (LEGACY - Using Asset Service)
-  // ============================================================================
-
-  /**
-   * Delete file
-   */
-  async deleteFile(fileId) {
-    try {
-      // Central Asset Service delete with force=true behavior controlled by caller via assetDelete
-      return await this.makeRequest('DELETE', `/api/assets/${encodeURIComponent(fileId)}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get file download URL (API streaming proxy, attaches token for <img src>)
-   */
-  getFileDownloadUrl(fileId, variant, expiresIn) {
-    const base = this.getBaseURL();
-    const params = new URLSearchParams();
-    if (variant) params.set('variant', variant);
-    if (expiresIn) params.set('expiresIn', String(expiresIn));
-    params.set('fallback', 'placeholderVisible');
-    const token = this.httpClient.getAccessToken();
-    if (token) params.set('token', token);
-
-    // Use params.toString() to detect whether there are query params.
-    // URLSearchParams.size is not a standard property across all JS runtimes
-    // (some environments like React Native may not implement it), which
-    // caused the query string to be omitted on native. Checking the
-    // serialized string is reliable everywhere.
-    const qs = params.toString();
-    return `${base}/api/assets/${encodeURIComponent(fileId)}/stream${qs ? `?${qs}` : ''}`;
-  }
-
-  /**
-   * Get file stream URL (direct Oxy Cloud/CDN URL, no token)
-   */
-  getFileStreamUrl(fileId) {
-    return `${this.getCloudURL()}/files/${fileId}/stream`;
-  }
-
-  // ...existing code...
-
-  /**
-   * List user files
-   */
-  async listUserFiles(limit, offset) {
-    try {
-      const paramsObj = {};
-      if (limit) paramsObj.limit = limit;
-      if (offset) paramsObj.offset = offset;
-      return await this.makeRequest('GET', '/api/assets', paramsObj, {
-        cache: false // Don't cache file lists - always get fresh data
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // (removed legacy downloadFileContent; use getFileContentAsBlob/Text which resolve CAS URL first)
-
-  /**
-   * Get file content as text
-   */
-  async getFileContentAsText(fileId, variant) {
-    try {
-      const params = variant ? {
-        variant
-      } : undefined;
-      const urlRes = await this.makeRequest('GET', `/api/assets/${encodeURIComponent(fileId)}/url`, params, {
-        cache: true,
-        cacheTTL: 10 * 60 * 1000 // 10 minutes cache for URLs
-      });
-      const downloadUrl = urlRes?.url;
-      const response = await fetch(downloadUrl);
-      return await response.text();
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get file content as blob
-   */
-  async getFileContentAsBlob(fileId, variant) {
-    try {
-      const params = variant ? {
-        variant
-      } : undefined;
-      const urlRes = await this.makeRequest('GET', `/api/assets/${encodeURIComponent(fileId)}/url`, params, {
-        cache: true,
-        cacheTTL: 10 * 60 * 1000 // 10 minutes cache for URLs
-      });
-      const downloadUrl = urlRes?.url;
-      const response = await fetch(downloadUrl);
-      return await response.blob();
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Upload raw file data
-   */
-  async uploadRawFile(file, visibility, metadata) {
-    // Switch to Central Asset Service upload flow
-    return this.assetUpload(file, visibility, metadata);
-  }
-
-  // ============================================================================
-  // CENTRAL ASSET SERVICE METHODS
-  // ============================================================================
-
-  /**
-   * Calculate SHA256 hash of file content
-   */
-  async calculateSHA256(file) {
-    const buffer = await file.arrayBuffer();
-    const hashBuffer = await crypto.subtle.digest('SHA-256', buffer);
-    const hashArray = Array.from(new Uint8Array(hashBuffer));
-    return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
-  }
-
-  /**
-   * Initialize asset upload - returns pre-signed URL and file ID
-   */
-  async assetInit(sha256, size, mime) {
-    try {
-      return await this.makeRequest('POST', '/api/assets/init', {
-        sha256,
-        size,
-        mime
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Complete asset upload - commit metadata and trigger variant generation
-   */
-  async assetComplete(fileId, originalName, size, mime, visibility, metadata) {
-    try {
-      return await this.makeRequest('POST', '/api/assets/complete', {
-        fileId,
-        originalName,
-        size,
-        mime,
-        visibility,
-        metadata
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Upload file using Central Asset Service
-   */
-  async assetUpload(file, visibility, metadata, onProgress) {
-    try {
-      // Calculate SHA256
-      const sha256 = await this.calculateSHA256(file);
-
-      // Initialize upload
-      const initResponse = await this.assetInit(sha256, file.size, file.type);
-
-      // Try presigned URL first
-      try {
-        await this.uploadToPresignedUrl(initResponse.uploadUrl, file, onProgress);
-      } catch (e) {
-        // Fallback: direct upload via API to avoid CORS issues
-        const fd = new FormData();
-        fd.append('file', file);
-        // Use httpClient directly for FormData uploads (bypasses RequestManager for special handling)
-        await this.httpClient.request({
-          method: 'POST',
-          url: `/api/assets/${encodeURIComponent(initResponse.fileId)}/upload-direct`,
-          data: fd
-        });
-      }
-
-      // Complete upload
-      return await this.assetComplete(initResponse.fileId, file.name, file.size, file.type, visibility, metadata);
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Upload file to pre-signed URL
-   */
-  async uploadToPresignedUrl(url, file, onProgress) {
-    return new Promise((resolve, reject) => {
-      const xhr = new XMLHttpRequest();
-      xhr.upload.addEventListener('progress', event => {
-        if (event.lengthComputable && onProgress) {
-          const progress = event.loaded / event.total * 100;
-          onProgress(progress);
-        }
-      });
-      xhr.addEventListener('load', () => {
-        if (xhr.status >= 200 && xhr.status < 300) {
-          resolve();
-        } else {
-          reject(new Error(`Upload failed with status ${xhr.status}`));
-        }
-      });
-      xhr.addEventListener('error', () => {
-        reject(new Error('Upload failed'));
-      });
-      xhr.open('PUT', url);
-      xhr.setRequestHeader('Content-Type', file.type);
-      xhr.send(file);
-    });
-  }
-
-  /**
-   * Link asset to an entity
-   */
-  async assetLink(fileId, app, entityType, entityId, visibility, webhookUrl) {
-    try {
-      const body = {
-        app,
-        entityType,
-        entityId
-      };
-      if (visibility) body.visibility = visibility;
-      if (webhookUrl) body.webhookUrl = webhookUrl;
-      return await this.makeRequest('POST', `/api/assets/${fileId}/links`, body, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Unlink asset from an entity
-   */
-  async assetUnlink(fileId, app, entityType, entityId) {
-    try {
-      return await this.makeRequest('DELETE', `/api/assets/${fileId}/links`, {
-        app,
-        entityType,
-        entityId
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get asset metadata
-   */
-  async assetGet(fileId) {
-    try {
-      return await this.makeRequest('GET', `/api/assets/${fileId}`, undefined, {
-        cache: true,
-        cacheTTL: 5 * 60 * 1000 // 5 minutes cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get asset URL (CDN or signed URL)
-   */
-  async assetGetUrl(fileId, variant, expiresIn) {
-    try {
-      const params = {};
-      if (variant) params.variant = variant;
-      if (expiresIn) params.expiresIn = expiresIn;
-      return await this.makeRequest('GET', `/api/assets/${fileId}/url`, params, {
-        cache: true,
-        cacheTTL: 10 * 60 * 1000 // 10 minutes cache for URLs
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Restore asset from trash
-   */
-  async assetRestore(fileId) {
-    try {
-      return await this.makeRequest('POST', `/api/assets/${fileId}/restore`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Delete asset with optional force
-   */
-  async assetDelete(fileId, force = false) {
-    try {
-      const params = force ? {
-        force: 'true'
-      } : undefined;
-      return await this.makeRequest('DELETE', `/api/assets/${fileId}`, params, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get list of available variants for an asset
-   */
-  async assetGetVariants(fileId) {
-    try {
-      const assetData = await this.assetGet(fileId);
-      return assetData.file?.variants || [];
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Update asset visibility
-   * @param fileId - The file ID
-   * @param visibility - New visibility level ('private', 'public', or 'unlisted')
-   * @returns Updated asset information
-   */
-  async assetUpdateVisibility(fileId, visibility) {
-    try {
-      return await this.makeRequest('PATCH', `/api/assets/${fileId}/visibility`, {
-        visibility
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Helper: Upload and link avatar with automatic public visibility
-   * @param file - The avatar file
-   * @param userId - User ID to link to
-   * @param app - App name (defaults to 'profiles')
-   * @returns The uploaded and linked asset
-   */
-  async uploadAvatar(file, userId, app = 'profiles') {
-    try {
-      // Upload as public
-      const asset = await this.assetUpload(file, 'public');
-
-      // Link to user profile as avatar
-      await this.assetLink(asset.file.id, app, 'avatar', userId, 'public');
-      return asset;
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Helper: Upload and link profile banner with automatic public visibility
-   * @param file - The banner file
-   * @param userId - User ID to link to
-   * @param app - App name (defaults to 'profiles')
-   * @returns The uploaded and linked asset
-   */
-  async uploadProfileBanner(file, userId, app = 'profiles') {
-    try {
-      // Upload as public
-      const asset = await this.assetUpload(file, 'public');
-
-      // Link to user profile as banner
-      await this.assetLink(asset.file.id, app, 'profile-banner', userId, 'public');
-      return asset;
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // DEVELOPER API METHODS
-  // ============================================================================
-
-  /**
-   * Get developer apps for the current user
-   */
-  async getDeveloperApps() {
-    try {
-      const res = await this.makeRequest('GET', '/api/developer/apps', undefined, {
-        cache: true,
-        cacheTTL: 2 * 60 * 1000 // 2 minutes cache
-      });
-      return res.apps || [];
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Create a new developer app
-   */
-  async createDeveloperApp(data) {
-    try {
-      const res = await this.makeRequest('POST', '/api/developer/apps', data, {
-        cache: false
-      });
-      return res.app;
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get a specific developer app
-   */
-  async getDeveloperApp(appId) {
-    try {
-      const res = await this.makeRequest('GET', `/api/developer/apps/${appId}`, undefined, {
-        cache: true,
-        cacheTTL: 5 * 60 * 1000 // 5 minutes cache
-      });
-      return res.app;
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Update a developer app
-   */
-  async updateDeveloperApp(appId, data) {
-    try {
-      const res = await this.makeRequest('PATCH', `/api/developer/apps/${appId}`, data, {
-        cache: false
-      });
-      return res.app;
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Regenerate API secret for a developer app
-   */
-  async regenerateDeveloperAppSecret(appId) {
-    try {
-      return await this.makeRequest('POST', `/api/developer/apps/${appId}/regenerate-secret`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Delete a developer app
-   */
-  async deleteDeveloperApp(appId) {
-    try {
-      return await this.makeRequest('DELETE', `/api/developer/apps/${appId}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // LOCATION METHODS
-  // ============================================================================
-
-  /**
-   * Update user location
-   */
-  async updateLocation(latitude, longitude) {
-    try {
-      return await this.makeRequest('POST', '/api/location', {
-        latitude,
-        longitude
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get nearby users
-   */
-  async getNearbyUsers(radius) {
-    try {
-      const params = radius ? {
-        radius
-      } : undefined;
-      return await this.makeRequest('GET', '/api/location/nearby', params, {
-        cache: false // Don't cache location data - always get fresh data
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // ANALYTICS METHODS
-  // ============================================================================
-
-  /**
-   * Track event
-   */
-  async trackEvent(eventName, properties) {
-    try {
-      await this.makeRequest('POST', '/api/analytics/events', {
-        event: eventName,
-        properties
-      }, {
-        cache: false,
-        retry: false
-      }); // Don't retry analytics events
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get analytics data
-   */
-  async getAnalytics(startDate, endDate) {
-    try {
-      const params = {};
-      if (startDate) params.startDate = startDate;
-      if (endDate) params.endDate = endDate;
-      return await this.makeRequest('GET', '/api/analytics', params, {
-        cache: true,
-        cacheTTL: 5 * 60 * 1000 // 5 minutes cache
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // DEVICE METHODS
-  // ============================================================================
-
-  /**
-   * Register device
-   */
-  async registerDevice(deviceData) {
-    try {
-      return await this.makeRequest('POST', '/api/devices', deviceData, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get user devices
-   */
-  async getUserDevices() {
-    try {
-      return await this.makeRequest('GET', '/api/devices', undefined, {
-        cache: false // Don't cache device list - always get fresh data
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Remove device
-   */
-  async removeDevice(deviceId) {
-    try {
-      await this.makeRequest('DELETE', `/api/devices/${deviceId}`, undefined, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Get device sessions
-   * Note: Not cached by default to ensure fresh data, but can be cached via makeRequest if needed
-   */
-  async getDeviceSessions(sessionId) {
-    try {
-      // Use makeRequest for consistent error handling and optional caching
-      // Cache disabled by default to ensure fresh session data
-      return await this.makeRequest('GET', `/api/session/device/sessions/${sessionId}`, undefined, {
-        cache: false,
-        // Don't cache sessions - always get fresh data
-        deduplicate: true // Deduplicate concurrent requests for same sessionId
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Logout all device sessions
-   */
-  async logoutAllDeviceSessions(sessionId, deviceId, excludeCurrent) {
-    try {
-      const params = new URLSearchParams();
-      if (deviceId) params.append('deviceId', deviceId);
-      if (excludeCurrent) params.append('excludeCurrent', 'true');
-      const urlParams = {};
-      params.forEach((value, key) => {
-        urlParams[key] = value;
-      });
-      return await this.makeRequest('POST', `/api/session/device/logout-all/${sessionId}`, urlParams, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Update device name
-   */
-  async updateDeviceName(sessionId, deviceName) {
-    try {
-      return await this.makeRequest('PUT', `/api/session/device/name/${sessionId}`, {
-        deviceName
-      }, {
-        cache: false
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  // ============================================================================
-  // UTILITY METHODS
-  // ============================================================================
-
-  /**
-   * Fetch link metadata
-   */
-  async fetchLinkMetadata(url) {
-    try {
-      return await this.makeRequest('GET', '/api/link-metadata', {
-        url
-      }, {
-        cache: true,
-        cacheTTL: 30 * 60 * 1000 // 30 minutes cache for link metadata
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-
-  /**
-   * Simple Express.js authentication middleware
-   * 
-   * Built-in authentication middleware that validates JWT tokens and adds user data to requests.
-   * 
-   * @example
-   * ```typescript
-   * // Basic usage - just add it to your routes
-   * app.use('/api/protected', oxyServices.auth());
-   * 
-   * // With debug logging
-   * app.use('/api/protected', oxyServices.auth({ debug: true }));
-   * 
-   * // With custom error handling
-   * app.use('/api/protected', oxyServices.auth({
-   *   onError: (error) => console.error('Auth failed:', error)
-   * }));
-   * 
-   * // Load full user data
-   * app.use('/api/protected', oxyServices.auth({ loadUser: true }));
-   * ```
-   * 
-   * @param options Optional configuration
-   * @param options.debug Enable debug logging (default: false)
-   * @param options.onError Custom error handler
-   * @param options.loadUser Load full user data (default: false for performance)
-   * @param options.session Use session-based validation (default: false)
-   * @returns Express middleware function
-   */
-  auth(options = {}) {
-    const {
-      debug = false,
-      onError,
-      loadUser = false,
-      session = false
-    } = options;
-
-    // Return a synchronous middleware function
-    return (req, res, next) => {
-      try {
-        // Extract token from Authorization header
-        const authHeader = req.headers['authorization'];
-        const token = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
-        if (debug) {
-          console.log(`🔐 Auth: Processing ${req.method} ${req.path}`);
-          console.log(`🔐 Auth: Token present: ${!!token}`);
-        }
-        if (!token) {
-          const error = {
-            message: 'Access token required',
-            code: 'MISSING_TOKEN',
-            status: 401
-          };
-          if (debug) console.log(`❌ Auth: Missing token`);
-          if (onError) return onError(error);
-          return res.status(401).json(error);
-        }
-
-        // Decode and validate token
-        let decoded;
-        try {
-          decoded = jwtDecode(token);
-          if (debug) {
-            console.log(`🔐 Auth: Token decoded, User ID: ${decoded.userId || decoded.id}`);
-          }
-        } catch (decodeError) {
-          const error = {
-            message: 'Invalid token format',
-            code: 'INVALID_TOKEN_FORMAT',
-            status: 403
-          };
-          if (debug) console.log(`❌ Auth: Token decode failed`);
-          if (onError) return onError(error);
-          return res.status(403).json(error);
-        }
-        const userId = decoded.userId || decoded.id;
-        if (!userId) {
-          const error = {
-            message: 'Token missing user ID',
-            code: 'INVALID_TOKEN_PAYLOAD',
-            status: 403
-          };
-          if (debug) console.log(`❌ Auth: Token missing user ID`);
-          if (onError) return onError(error);
-          return res.status(403).json(error);
-        }
-
-        // Check token expiration
-        if (decoded.exp && decoded.exp < Math.floor(Date.now() / 1000)) {
-          const error = {
-            message: 'Token expired',
-            code: 'TOKEN_EXPIRED',
-            status: 403
-          };
-          if (debug) console.log(`❌ Auth: Token expired`);
-          if (onError) return onError(error);
-          return res.status(403).json(error);
-        }
-
-        // For now, skip session validation to keep it simple
-        // Session validation can be added later if needed
-
-        // Set request properties immediately
-        req.userId = userId;
-        req.accessToken = token;
-        req.user = {
-          id: userId
-        };
-        if (debug) {
-          console.log(`✅ Auth: Authentication successful for user ${userId}`);
-        }
-        next();
-      } catch (error) {
-        const apiError = this.handleError(error);
-        if (debug) {
-          console.log(`❌ Auth: Unexpected error:`, apiError);
-        }
-        if (onError) return onError(apiError);
-        return res.status(apiError && apiError.status || 500).json(apiError);
-      }
-    };
+// 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)
  */