@oxyhq/services 5.13.15 → 5.13.16

package/README.md

@@ -719,6 +719,16 @@ npm install axios jwt-decode invariant
 
 **Note**: `react-native-url-polyfill` is already included as a dependency in this package.
 
+## 📚 Documentation
+
+Comprehensive documentation is available in the `/docs` directory:
+
+- **[Getting Started](./docs/GETTING_STARTED.md)** - Quick start guide for new developers
+- **[API Reference](./docs/API_REFERENCE.md)** - Complete API method documentation
+- **[Integration Guide](./docs/INTEGRATION_GUIDE.md)** - Platform-specific integration guides
+- **[Examples](./docs/EXAMPLES.md)** - Complete working code examples
+- **[Best Practices](./docs/BEST_PRACTICES.md)** - Production-ready patterns and tips
+
 ## 📚 Examples
 
 ### Complete React Native App

package/lib/commonjs/core/OxyServices.base.js

@@ -0,0 +1,271 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.OxyServicesBase = void 0;
+var _jwtDecode = require("jwt-decode");
+var _errorUtils = require("../utils/errorUtils");
+var _HttpClient = require("./HttpClient");
+var _RequestManager = require("./RequestManager");
+var _OxyServices = require("./OxyServices.errors");
+/**
+ * OxyServices Base Class
+ * 
+ * Contains core infrastructure, HTTP client, request management, and error handling
+ */
+
+/**
+ * Base class for OxyServices with core infrastructure
+ */
+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 HTTP client (handles authentication and interceptors)
+    this.httpClient = new _HttpClient.HttpClient(config);
+
+    // Initialize request manager (handles caching, deduplication, queuing, retry)
+    this.requestManager = new _RequestManager.RequestManager(this.httpClient, config);
+  }
+
+  // Test-only utility to reset global tokens between jest tests
+  static __resetTokensForTests() {
+    _HttpClient.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 = (0, _jwtDecode.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.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;
+  }
+
+  /**
+   * Check if the client has a valid access token
+   */
+  hasAccessToken() {
+    return this.httpClient.hasAccessToken();
+  }
+
+  /**
+   * 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 _OxyServices.OxyAuthenticationTimeoutError(operationName, authTimeoutMs);
+            }
+          } else {
+            // On retry attempts, fail immediately if no token
+            throw new _OxyServices.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 _OxyServices.OxyAuthenticationError;
+        if (isAuthError && !isLastAttempt && !(error instanceof _OxyServices.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 _OxyServices.OxyAuthenticationError) {
+          throw error;
+        }
+        throw this.handleError(error);
+      }
+    }
+
+    // This should never be reached, but TypeScript requires it
+    throw new _OxyServices.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 = (0, _errorUtils.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);
+    }
+  }
+}
+exports.OxyServicesBase = OxyServicesBase;
+//# sourceMappingURL=OxyServices.base.js.map

package/lib/commonjs/core/OxyServices.base.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_jwtDecode","require","_errorUtils","_HttpClient","_RequestManager","_OxyServices","OxyServicesBase","constructor","args","config","Error","cloudURL","httpClient","HttpClient","requestManager","RequestManager","__resetTokensForTests","makeRequest","method","url","data","options","request","getBaseURL","getClient","getMetrics","clearCache","clearCacheEntry","key","getCacheStats","getCloudURL","setTokens","accessToken","refreshToken","clearTokens","getCurrentUserId","getAccessToken","decoded","jwtDecode","userId","id","error","hasValidToken","hasAccessToken","waitForAuth","timeoutMs","waitForAuthentication","startTime","Date","now","checkInterval","Promise","resolve","setTimeout","withAuthRetry","operation","operationName","maxRetries","retryDelay","authTimeoutMs","attempt","authReady","OxyAuthenticationTimeoutError","OxyAuthenticationError","isLastAttempt","isAuthError","response","status","code","message","includes","handleError","validate","res","undefined","cache","retry","valid","api","handleHttpError","err","details","healthCheck","exports"],"sourceRoot":"../../../src","sources":["core/OxyServices.base.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/core/OxyServices.errors.js

@@ -0,0 +1,26 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = void 0;
+/**
+ * Custom error types for better error handling
+ */
+class OxyAuthenticationError extends Error {
+  constructor(message, code = 'AUTH_ERROR', status = 401) {
+    super(message);
+    this.name = 'OxyAuthenticationError';
+    this.code = code;
+    this.status = status;
+  }
+}
+exports.OxyAuthenticationError = OxyAuthenticationError;
+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';
+  }
+}
+exports.OxyAuthenticationTimeoutError = OxyAuthenticationTimeoutError;
+//# sourceMappingURL=OxyServices.errors.js.map

package/lib/commonjs/core/OxyServices.errors.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["OxyAuthenticationError","Error","constructor","message","code","status","name","exports","OxyAuthenticationTimeoutError","operationName","timeoutMs"],"sourceRoot":"../../../src","sources":["core/OxyServices.errors.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACO,MAAMA,sBAAsB,SAASC,KAAK,CAAC;EAIhDC,WAAWA,CAACC,OAAe,EAAEC,IAAI,GAAG,YAAY,EAAEC,MAAM,GAAG,GAAG,EAAE;IAC9D,KAAK,CAACF,OAAO,CAAC;IACd,IAAI,CAACG,IAAI,GAAG,wBAAwB;IACpC,IAAI,CAACF,IAAI,GAAGA,IAAI;IAChB,IAAI,CAACC,MAAM,GAAGA,MAAM;EACtB;AACF;AAACE,OAAA,CAAAP,sBAAA,GAAAA,sBAAA;AAEM,MAAMQ,6BAA6B,SAASR,sBAAsB,CAAC;EACxEE,WAAWA,CAACO,aAAqB,EAAEC,SAAiB,EAAE;IACpD,KAAK,CACH,2BAA2BA,SAAS,QAAQD,aAAa,gGAAgG,EACzJ,cAAc,EACd,GACF,CAAC;IACD,IAAI,CAACH,IAAI,GAAG,+BAA+B;EAC7C;AACF;AAACC,OAAA,CAAAC,6BAAA,GAAAA,6BAAA","ignoreList":[]}