@oxyhq/services 5.26.4 → 6.0.0

package/src/core/OxyServices.base.ts

@@ -1,334 +0,0 @@
-/**
- * OxyServices Base Class
- * 
- * Contains core infrastructure, HTTP client, request management, and error handling
- */
-import { jwtDecode } from 'jwt-decode';
-import type { OxyConfig as OxyConfigBase, ApiError, User } from '../models/interfaces';
-import { handleHttpError } from '../utils/errorUtils';
-import { HttpService, type RequestOptions } from './HttpService';
-import { OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices.errors';
-
-export interface OxyConfig extends OxyConfigBase {
-  cloudURL?: string;
-}
-
-interface JwtPayload {
-  exp?: number;
-  userId?: string;
-  id?: string;
-  sessionId?: string;
-  [key: string]: any;
-}
-
-/**
- * Base class for OxyServices with core infrastructure
- */
-export class OxyServicesBase {
-  public httpService: HttpService;
-  public cloudURL: string;
-  public config: OxyConfig;
-
-  constructor(...args: any[]) {
-    const config = args[0] as OxyConfig;
-    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(): void {
-    HttpService.__resetTokensForTests();
-  }
-
-  /**
-   * Make a request with all performance optimizations
-   * This is the main method for all API calls - ensures authentication and performance features
-   */
-  public async makeRequest<T>(
-    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
-    url: string,
-    data?: any,
-    options: RequestOptions = {}
-  ): Promise<T> {
-    return this.httpService.request<T>({
-      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
-   */
-  public getBaseURL(): string {
-    return this.httpService.getBaseURL();
-  }
-
-  /**
-   * Get the HTTP service instance
-   * Useful for advanced use cases where direct access to the HTTP service is needed
-   */
-  public getClient(): HttpService {
-    return this.httpService;
-  }
-
-  /**
-   * Get performance metrics
-   */
-  public getMetrics() {
-    return this.httpService.getMetrics();
-  }
-
-  /**
-   * Clear request cache
-   */
-  public clearCache(): void {
-    this.httpService.clearCache();
-  }
-
-  /**
-   * Clear specific cache entry
-   */
-  public clearCacheEntry(key: string): void {
-    this.httpService.clearCacheEntry(key);
-  }
-
-  /**
-   * Get cache statistics
-   */
-  public getCacheStats() {
-    return this.httpService.getCacheStats();
-  }
-
-  /**
-   * Get the configured Oxy Cloud (file storage/CDN) URL
-   */
-  public getCloudURL(): string {
-    return this.cloudURL;
-  }
-
-  /**
-   * Set authentication tokens
-   */
-  public setTokens(accessToken: string, refreshToken = ''): void {
-    this.httpService.setTokens(accessToken, refreshToken);
-  }
-
-  /**
-   * Clear stored authentication tokens
-   */
-  public clearTokens(): void {
-    this.httpService.clearTokens();
-  }
-
-  /**
-   * Get the current user ID from the access token
-   */
-  public getCurrentUserId(): string | null {
-    const accessToken = this.httpService.getAccessToken();
-    if (!accessToken) {
-      return null;
-    }
-    
-    try {
-      const decoded = jwtDecode<JwtPayload>(accessToken);
-      return decoded.userId || decoded.id || null;
-    } catch (error) {
-      return null;
-    }
-  }
-
-  /**
-   * Check if the client has a valid access token (public method)
-   */
-  public hasValidToken(): boolean {
-    return this.httpService.hasAccessToken();
-  }
-
-  /**
-   * Get the raw access token (for constructing anchor URLs when needed)
-   */
-  public getAccessToken(): string | null {
-    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
-   * }
-   * ```
-   */
-  public async waitForAuth(timeoutMs = 5000): Promise<boolean> {
-    // 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
-   */
-  public async withAuthRetry<T>(
-    operation: () => Promise<T>, 
-    operationName: string,
-    options: {
-      maxRetries?: number;
-      retryDelay?: number;
-      authTimeoutMs?: number;
-    } = {}
-  ): Promise<T> {
-    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: unknown) {
-        const isLastAttempt = attempt === maxRetries;
-        const errorObj = error && typeof error === 'object' ? error as { response?: { status?: number }; code?: string; message?: string } : 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(): Promise<boolean> {
-    if (!this.hasValidToken()) {
-      return false;
-    }
-
-    try {
-      const res = await this.makeRequest<{ valid: boolean }>('GET', '/api/auth/validate', undefined, {
-        cache: false,
-        retry: false,
-      });
-      return res.valid === true;
-    } catch (error) {
-      return false;
-    }
-  }
-
-  /**
-   * Centralized error handling
-   */
-  public handleError(error: unknown): 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) as Error & { code?: string; status?: number; details?: Record<string, unknown> };
-    err.code = api.code;
-    err.status = api.status;
-    err.details = api.details;
-    return err;
-  }
-
-  /**
-   * Health check endpoint
-   */
-  async healthCheck(): Promise<{ 
-    status: string; 
-    users?: number; 
-    timestamp?: string; 
-    [key: string]: any 
-  }> {
-    try {
-      return await this.makeRequest('GET', '/health', undefined, { 
-        cache: false,
-        retry: false,
-        timeout: 5000
-      });
-    } catch (error) {
-      throw this.handleError(error);
-    }
-  }
-}
-

package/src/core/OxyServices.errors.ts

@@ -1,26 +0,0 @@
-/**
- * Custom error types for better error handling
- */
-export class OxyAuthenticationError extends Error {
-  public readonly code: string;
-  public readonly status: number;
-
-  constructor(message: string, code = 'AUTH_ERROR', status = 401) {
-    super(message);
-    this.name = 'OxyAuthenticationError';
-    this.code = code;
-    this.status = status;
-  }
-}
-
-export class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
-  constructor(operationName: string, timeoutMs: number) {
-    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/src/core/OxyServices.ts

@@ -1,129 +0,0 @@
-/**
- * OxyServices - Unified client for Oxy API and Oxy Cloud
- *
- * # Usage Examples
- *
- * ## Browser (ESM/TypeScript)
- *
- * ```typescript
- * import { OxyServices } from './core/OxyServices';
- *
- * const oxy = new OxyServices({
- *   baseURL: 'https://api.oxy.so',
- *   cloudURL: 'https://cloud.oxy.so',
- * });
- *
- * // Authenticate and fetch user
- * await oxy.setTokens('ACCESS_TOKEN');
- * const user = await oxy.getCurrentUser();
- *
- * // Upload a file (browser File API)
- * const fileInput = document.querySelector('input[type=file]');
- * const file = fileInput.files[0];
- * await oxy.uploadRawFile(file);
- *
- * // Get a file download URL for <img src>
- * const url = oxy.getFileDownloadUrl('fileId', 'thumb');
- * ```
- *
- * ## Node.js (CommonJS/TypeScript)
- *
- * ```typescript
- * import { OxyServices } from './core/OxyServices';
- * import fs from 'fs';
- *
- * const oxy = new OxyServices({
- *   baseURL: 'https://api.oxy.so',
- *   cloudURL: 'https://cloud.oxy.so',
- * });
- *
- * // Authenticate and fetch user
- * await oxy.setTokens('ACCESS_TOKEN');
- * const user = await oxy.getCurrentUser();
- *
- * // Upload a file (Node.js Buffer)
- * const buffer = fs.readFileSync('myfile.png');
- * const blob = new Blob([buffer]);
- * await oxy.uploadRawFile(blob, { filename: 'myfile.png' });
- *
- * // Get a file download URL
- * const url = oxy.getFileDownloadUrl('fileId');
- * ```
- *
- * ## Configuration
- * - `baseURL`: Oxy API endpoint (e.g., https://api.oxy.so)
- * - `cloudURL`: Oxy Cloud/CDN endpoint (e.g., https://cloud.oxy.so)
- *
- * See method JSDoc for more details and options.
- */
-import { OxyServicesBase, type OxyConfig } from './OxyServices.base';
-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 as any) {
-  constructor(config: OxyConfig) {
-    super(config);
-  }
-}
-
-// Type augmentation to expose mixin methods to TypeScript
-// This allows proper type checking while avoiding complex mixin type inference
-export interface OxyServices extends InstanceType<ReturnType<typeof composeOxyServices>> {}
-
-// 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/src/core/index.ts

@@ -1,42 +0,0 @@
-/**
- * OxyServices Core Module - Unified Architecture
- * 
- * This module exports the unified OxyServices class that provides all API functionality
- * in one simple, easy-to-use interface.
- */
-
-// Main OxyServices class (unified)
-export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './OxyServices';
-export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
-
-// Cross-domain authentication
-export { CrossDomainAuth, createCrossDomainAuth } from './CrossDomainAuth';
-export type { CrossDomainAuthOptions } from './CrossDomainAuth';
-
-// Centralized auth management
-export { AuthManager, createAuthManager } from './AuthManager';
-export type { StorageAdapter, AuthStateChangeCallback, AuthMethod, AuthManagerConfig } from './AuthManager';
-
-// Re-export all models and types for convenience
-export * from '../models/interfaces';
-export * from '../models/session';
-
-// Export device management utilities
-export { DeviceManager } from '../utils/deviceManager';
-export type { DeviceFingerprint, StoredDeviceInfo } from '../utils/deviceManager';
-
-// Export language utilities
-export { 
-  SUPPORTED_LANGUAGES,
-  getLanguageMetadata,
-  getLanguageName,
-  getNativeLanguageName,
-  normalizeLanguageCode
-} from '../utils/languageUtils';
-export type { LanguageMetadata } from '../utils/languageUtils';
-
-// Import for default export
-import { OxyServices } from './OxyServices';
-
-// Default export for backward compatibility
-export default OxyServices;

package/src/core/mixins/OxyServices.analytics.ts

@@ -1,53 +0,0 @@
-/**
- * Analytics Methods Mixin
- * 
- * Provides methods for analytics tracking and data retrieval
- */
-import type { OxyServicesBase } from '../OxyServices.base';
-import { CACHE_TIMES } from './mixinHelpers';
-
-export function OxyServicesAnalyticsMixin<T extends typeof OxyServicesBase>(Base: T) {
-  return class extends Base {
-    constructor(...args: any[]) {
-      super(...(args as [any]));
-    }
-
-    /**
-     * Track an analytics event
-     * @param eventName - Name of the event to track
-     * @param properties - Optional event properties
-     */
-    async trackEvent(eventName: string, properties?: Record<string, any>): Promise<void> {
-      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 for a date range
-     * @param startDate - Optional start date (ISO string)
-     * @param endDate - Optional end date (ISO string)
-     * @returns Analytics data
-     */
-    async getAnalytics(startDate?: string, endDate?: string): Promise<any> {
-      try {
-        const params: any = {};
-        if (startDate) params.startDate = startDate;
-        if (endDate) params.endDate = endDate;
-        
-        return await this.makeRequest('GET', '/api/analytics', params, {
-          cache: true,
-          cacheTTL: CACHE_TIMES.LONG,
-        });
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-  };
-}
-