@oxyhq/services 5.16.23 → 5.16.25

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

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

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

@@ -0,0 +1 @@
+{"version":3,"names":["handleHttpError","HttpService","OxyAuthenticationError","OxyAuthenticationTimeoutError","tokenService","OxyServicesBase","constructor","args","config","Error","cloudURL","httpService","__resetTokensForTests","makeRequest","method","url","data","options","request","undefined","params","getBaseURL","getClient","getMetrics","clearCache","clearCacheEntry","key","getCacheStats","getCloudURL","setTokens","accessToken","refreshToken","clearTokens","getCurrentUserId","getUserIdFromToken","hasValidToken","hasAccessToken","getAccessToken","waitForAuth","timeoutMs","startTime","performance","now","maxTime","pollInterval","Promise","resolve","setTimeout","Math","min","withAuthRetry","operation","operationName","maxRetries","retryDelay","authTimeoutMs","attempt","authReady","error","isLastAttempt","errorObj","isAuthError","response","status","code","message","includes","handleError","validate","res","cache","retry","valid","api","trim","err","details","healthCheck","timeout"],"sourceRoot":"../../../src","sources":["core/OxyServices.base.ts"],"mappings":"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","ignoreList":[]}

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

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * 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';
+  }
+}
+//# sourceMappingURL=OxyServices.errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["OxyAuthenticationError","Error","constructor","message","code","status","name","OxyAuthenticationTimeoutError","operationName","timeoutMs"],"sourceRoot":"../../../src","sources":["core/OxyServices.errors.ts"],"mappings":";;AAAA;AACA;AACA;AACA,OAAO,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;AAEA,OAAO,MAAME,6BAA6B,SAASP,sBAAsB,CAAC;EACxEE,WAAWA,CAACM,aAAqB,EAAEC,SAAiB,EAAE;IACpD,KAAK,CACH,2BAA2BA,SAAS,QAAQD,aAAa,gGAAgG,EACzJ,cAAc,EACd,GACF,CAAC;IACD,IAAI,CAACF,IAAI,GAAG,+BAA+B;EAC7C;AACF","ignoreList":[]}

package/lib/module/core/OxyServices.js

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

package/lib/module/core/OxyServices.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["OxyAuthenticationError","OxyAuthenticationTimeoutError","composeOxyServices","OxyServicesComposed","OxyServices","constructor","config","OXY_CLOUD_URL","OXY_API_URL","process","env","oxyClient","baseURL","cloudURL"],"sourceRoot":"../../../src","sources":["core/OxyServices.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,sBAAsB,EAAEC,6BAA6B,QAAQ,sBAAsB;;AAE5F;AACA,SAASC,kBAAkB,QAAQ,UAAU;;AAE7C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,mBAA0D,GAAGD,kBAAkB,CAAC,CAAC;;AAEvF;AACA,OAAO,MAAME,WAAW,SAASD,mBAAmB,CAAC;EACnDE,WAAWA,CAACC,MAAiB,EAAE;IAC7B,KAAK,CAACA,MAAM,CAAC;EACf;AACF;;AAEA;AACA,SAASN,sBAAsB,EAAEC,6BAA6B;;AAE9D;AACA;AACA;AACA,OAAO,MAAMM,aAAa,GAAG,sBAAsB;;AAEnD;AACA;AACA;AACA,OAAO,MAAMC,WAAW,GAAI,OAAOC,OAAO,KAAK,WAAW,IAAIA,OAAO,CAACC,GAAG,IAAID,OAAO,CAACC,GAAG,CAACF,WAAW,IAAK,oBAAoB;;AAE7H;AACA;AACA;AACA;AACA,OAAO,MAAMG,SAAS,GAAG,IAAIP,WAAW,CAAC;EAAEQ,OAAO,EAAEJ,WAAW;EAAEK,QAAQ,EAAEN;AAAc,CAAC,CAAC","ignoreList":[]}

package/lib/module/core/index.js

@@ -0,0 +1,27 @@
+"use strict";
+
+/**
+ * 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';
+
+// 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 language utilities
+export { SUPPORTED_LANGUAGES, getLanguageMetadata, getLanguageName, getNativeLanguageName, normalizeLanguageCode } from '../utils/languageUtils';
+// Import for default export
+import { OxyServices } from './OxyServices';
+
+// Default export for backward compatibility
+export default OxyServices;
+//# sourceMappingURL=index.js.map

package/lib/module/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["OxyServices","OxyAuthenticationError","OxyAuthenticationTimeoutError","OXY_CLOUD_URL","oxyClient","DeviceManager","SUPPORTED_LANGUAGES","getLanguageMetadata","getLanguageName","getNativeLanguageName","normalizeLanguageCode"],"sourceRoot":"../../../src","sources":["core/index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA,SAASA,WAAW,EAAEC,sBAAsB,EAAEC,6BAA6B,QAAQ,eAAe;AAClG,SAASC,aAAa,EAAEC,SAAS,QAAQ,eAAe;;AAExD;AACA,cAAc,sBAAsB;AACpC,cAAc,mBAAmB;;AAEjC;AACA,SAASC,aAAa,QAAQ,wBAAwB;AAGtD;AACA,SACEC,mBAAmB,EACnBC,mBAAmB,EACnBC,eAAe,EACfC,qBAAqB,EACrBC,qBAAqB,QAChB,wBAAwB;AAG/B;AACA,SAASV,WAAW,QAAQ,eAAe;;AAE3C;AACA,eAAeA,WAAW","ignoreList":[]}

package/lib/module/core/mixins/OxyServices.analytics.js

@@ -0,0 +1,56 @@
+"use strict";
+
+/**
+ * Analytics Methods Mixin
+ * 
+ * Provides methods for analytics tracking and data retrieval
+ */
+
+import { CACHE_TIMES } from './mixinHelpers';
+export function OxyServicesAnalyticsMixin(Base) {
+  return class extends Base {
+    constructor(...args) {
+      super(...args);
+    }
+
+    /**
+     * Track an analytics event
+     * @param eventName - Name of the event to track
+     * @param properties - Optional event properties
+     */
+    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 for a date range
+     * @param startDate - Optional start date (ISO string)
+     * @param endDate - Optional end date (ISO string)
+     * @returns 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: CACHE_TIMES.LONG
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}
+//# sourceMappingURL=OxyServices.analytics.js.map

package/lib/module/core/mixins/OxyServices.analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["CACHE_TIMES","OxyServicesAnalyticsMixin","Base","constructor","args","trackEvent","eventName","properties","makeRequest","event","cache","retry","error","handleError","getAnalytics","startDate","endDate","params","cacheTTL","LONG"],"sourceRoot":"../../../../src","sources":["core/mixins/OxyServices.analytics.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;;AAEA,SAASA,WAAW,QAAQ,gBAAgB;AAE5C,OAAO,SAASC,yBAAyBA,CAAmCC,IAAO,EAAE;EACnF,OAAO,cAAcA,IAAI,CAAC;IACxBC,WAAWA,CAAC,GAAGC,IAAW,EAAE;MAC1B,KAAK,CAAC,GAAIA,IAAc,CAAC;IAC3B;;IAEA;AACJ;AACA;AACA;AACA;IACI,MAAMC,UAAUA,CAACC,SAAiB,EAAEC,UAAgC,EAAiB;MACnF,IAAI;QACF,MAAM,IAAI,CAACC,WAAW,CAAC,MAAM,EAAE,uBAAuB,EAAE;UACtDC,KAAK,EAAEH,SAAS;UAChBC;QACF,CAAC,EAAE;UAAEG,KAAK,EAAE,KAAK;UAAEC,KAAK,EAAE;QAAM,CAAC,CAAC,CAAC,CAAC;MACtC,CAAC,CAAC,OAAOC,KAAK,EAAE;QACd,MAAM,IAAI,CAACC,WAAW,CAACD,KAAK,CAAC;MAC/B;IACF;;IAEA;AACJ;AACA;AACA;AACA;AACA;IACI,MAAME,YAAYA,CAACC,SAAkB,EAAEC,OAAgB,EAAgB;MACrE,IAAI;QACF,MAAMC,MAAW,GAAG,CAAC,CAAC;QACtB,IAAIF,SAAS,EAAEE,MAAM,CAACF,SAAS,GAAGA,SAAS;QAC3C,IAAIC,OAAO,EAAEC,MAAM,CAACD,OAAO,GAAGA,OAAO;QAErC,OAAO,MAAM,IAAI,CAACR,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAES,MAAM,EAAE;UAC7DP,KAAK,EAAE,IAAI;UACXQ,QAAQ,EAAElB,WAAW,CAACmB;QACxB,CAAC,CAAC;MACJ,CAAC,CAAC,OAAOP,KAAK,EAAE;QACd,MAAM,IAAI,CAACC,WAAW,CAACD,KAAK,CAAC;MAC/B;IACF;EACF,CAAC;AACH","ignoreList":[]}