@oxyhq/services 5.13.1 → 5.13.3

package/lib/typescript/utils/requestUtils.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Request utilities for HTTP clients
+ *
+ * Provides reusable components for request deduplication, queuing, and logging
+ */
+/**
+ * Request deduplication - prevents duplicate concurrent requests
+ *
+ * When multiple requests with the same key are made simultaneously,
+ * only one request is executed and all callers receive the same result.
+ *
+ * @example
+ * ```typescript
+ * const deduplicator = new RequestDeduplicator();
+ *
+ * // Multiple calls with same key will share the same promise
+ * const promise1 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
+ * const promise2 = deduplicator.deduplicate('user-123', () => fetchUser('123'));
+ * // promise1 === promise2, only one API call is made
+ * ```
+ */
+export declare class RequestDeduplicator {
+    private pendingRequests;
+    /**
+     * Deduplicate a request by key
+     * @param key Unique key for the request
+     * @param requestFn Function that returns a promise
+     * @returns Promise that will be shared if key already exists
+     */
+    deduplicate<T>(key: string, requestFn: () => Promise<T>): Promise<T>;
+    /**
+     * Clear all pending requests
+     */
+    clear(): void;
+    /**
+     * Get number of pending requests
+     */
+    size(): number;
+}
+/**
+ * Request queue with concurrency control
+ *
+ * Limits the number of concurrent requests and queues excess requests.
+ * Useful for rate limiting and preventing request flooding.
+ *
+ * @example
+ * ```typescript
+ * const queue = new RequestQueue(5, 100); // Max 5 concurrent, queue up to 100
+ *
+ * // All requests will be queued and processed with max 5 concurrent
+ * await queue.enqueue(() => fetchUser('1'));
+ * await queue.enqueue(() => fetchUser('2'));
+ * // ...
+ * ```
+ */
+export declare class RequestQueue {
+    private queue;
+    private running;
+    private maxConcurrent;
+    private maxQueueSize;
+    /**
+     * Create a new request queue
+     * @param maxConcurrent Maximum number of concurrent requests (default: 10)
+     * @param maxQueueSize Maximum queue size (default: 100)
+     */
+    constructor(maxConcurrent?: number, maxQueueSize?: number);
+    /**
+     * Enqueue a request
+     * @param requestFn Function that returns a promise
+     * @returns Promise that resolves when request completes
+     */
+    enqueue<T>(requestFn: () => Promise<T>): Promise<T>;
+    /**
+     * Process queued requests
+     */
+    private process;
+    /**
+     * Clear all queued requests
+     */
+    clear(): void;
+    /**
+     * Get queue size
+     */
+    size(): number;
+    /**
+     * Get number of currently running requests
+     */
+    runningCount(): number;
+}
+/**
+ * Simple logger with level support
+ *
+ * Lightweight logger for HTTP clients and utilities.
+ * For more advanced logging, use loggerUtils.ts
+ *
+ * @example
+ * ```typescript
+ * const logger = new SimpleLogger(true, 'debug');
+ * logger.debug('Debug message');
+ * logger.info('Info message');
+ * logger.error('Error message');
+ * ```
+ */
+export declare class SimpleLogger {
+    private enabled;
+    private level;
+    private prefix;
+    /**
+     * Create a new simple logger
+     * @param enabled Whether logging is enabled
+     * @param level Minimum log level
+     * @param prefix Prefix for log messages (default: '')
+     */
+    constructor(enabled?: boolean, level?: string, prefix?: string);
+    private shouldLog;
+    private formatMessage;
+    error(...args: any[]): void;
+    warn(...args: any[]): void;
+    info(...args: any[]): void;
+    debug(...args: any[]): void;
+}
+//# sourceMappingURL=requestUtils.d.ts.map

package/lib/typescript/utils/requestUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/requestUtils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,eAAe,CAAmC;IAE1D;;;;;OAKG;IACG,WAAW,CAAC,CAAC,EACjB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC;IAeb;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,MAAM;CAGf;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAS;IAE7B;;;;OAIG;gBACS,aAAa,GAAE,MAAW,EAAE,YAAY,GAAE,MAAY;IAKlE;;;;OAIG;IACG,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBzD;;OAEG;YACW,OAAO;IAmBrB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,YAAY,IAAI,MAAM;CAGvB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;OAKG;gBAED,OAAO,GAAE,OAAe,EACxB,KAAK,GAAE,MAAgB,EACvB,MAAM,GAAE,MAAW;IAOrB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,aAAa;IAIrB,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM3B,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM1B,IAAI,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;IAM1B,KAAK,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI;CAK5B"}

package/lib/typescript/utils/sessionUtils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Session management utilities
+ *
+ * Provides consistent session normalization, deduplication, and sorting
+ * to ensure sessions are always displayed in a predictable order.
+ */
+import type { ClientSession } from '../models/session';
+/**
+ * Normalize a session to ensure all required fields are present
+ */
+export declare function normalizeSession(session: Partial<ClientSession> & {
+    sessionId: string;
+}): ClientSession;
+/**
+ * Compare two sessions for equality
+ */
+export declare function sessionsEqual(a: ClientSession, b: ClientSession): boolean;
+/**
+ * Sort sessions by lastActive (most recent first), then by sessionId for stability
+ */
+export declare function sortSessions(sessions: ClientSession[]): ClientSession[];
+/**
+ * Deduplicate sessions by sessionId, keeping the most recent version
+ */
+export declare function deduplicateSessions(sessions: ClientSession[]): ClientSession[];
+/**
+ * Deduplicate sessions by userId, keeping only one session per user
+ * Priority: 1) Active session (if provided), 2) Most recent session
+ * This prevents showing duplicate accounts for the same user
+ */
+export declare function deduplicateSessionsByUserId(sessions: ClientSession[], activeSessionId?: string | null): ClientSession[];
+/**
+ * Normalize, deduplicate, and sort sessions
+ * This ensures consistent session ordering across the application
+ *
+ * @param sessions - Array of sessions to normalize
+ * @param activeSessionId - Optional active session ID to prioritize
+ * @param deduplicateByUserId - If true, deduplicate by userId (one account per user). Default: true
+ */
+export declare function normalizeAndSortSessions(sessions: ClientSession[], activeSessionId?: string | null, deduplicateByUserId?: boolean): ClientSession[];
+/**
+ * Merge two session arrays, prioritizing newer data
+ * Returns normalized, deduplicated, and sorted sessions
+ *
+ * @param existing - Existing sessions array
+ * @param incoming - New sessions to merge in
+ * @param activeSessionId - Optional active session ID to prioritize
+ * @param deduplicateByUserId - If true, deduplicate by userId (one account per user). Default: true
+ */
+export declare function mergeSessions(existing: ClientSession[], incoming: ClientSession[], activeSessionId?: string | null, deduplicateByUserId?: boolean): ClientSession[];
+/**
+ * Check if two session arrays are equal (same sessionIds in same order)
+ */
+export declare function sessionsArraysEqual(a: ClientSession[], b: ClientSession[]): boolean;
+//# sourceMappingURL=sessionUtils.d.ts.map

package/lib/typescript/utils/sessionUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/sessionUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CASvG;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAEzE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAWvE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAkB9E;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,aAAa,EAAE,EACzB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,GAC9B,aAAa,EAAE,CAiCjB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,aAAa,EAAE,EACzB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,EAC/B,mBAAmB,GAAE,OAAc,GAClC,aAAa,EAAE,CAgBjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,aAAa,EAAE,EACzB,QAAQ,EAAE,aAAa,EAAE,EACzB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,EAC/B,mBAAmB,GAAE,OAAc,GAClC,aAAa,EAAE,CAgCjB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,aAAa,EAAE,EAAE,CAAC,EAAE,aAAa,EAAE,GAAG,OAAO,CAWnF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/services",
-  "version": "5.13.1",
+  "version": "5.13.3",
   "description": "Reusable OxyHQ module to handle authentication, user management, karma system, device-based session management and more 🚀",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/src/core/HttpClient.ts

@@ -0,0 +1,277 @@
+/**
+ * HTTP Client Service
+ * 
+ * Handles all HTTP communication with authentication, interceptors, and error handling.
+ * This is the single source of truth for making authenticated HTTP requests.
+ */
+
+import axios, { type AxiosInstance, type InternalAxiosRequestConfig, type AxiosResponse } from 'axios';
+import { jwtDecode } from 'jwt-decode';
+import type { OxyConfig } from '../models/interfaces';
+import { handleHttpError } from '../utils/errorUtils';
+import { SimpleLogger } from '../utils/requestUtils';
+
+interface JwtPayload {
+  exp?: number;
+  userId?: string;
+  id?: string;
+  sessionId?: string;
+  [key: string]: any;
+}
+
+/**
+ * Token store for authentication
+ */
+class TokenStore {
+  private static instance: TokenStore;
+  private accessToken: string | null = null;
+  private refreshToken: string | null = null;
+
+  private constructor() {}
+
+  static getInstance(): TokenStore {
+    if (!TokenStore.instance) {
+      TokenStore.instance = new TokenStore();
+    }
+    return TokenStore.instance;
+  }
+
+  setTokens(accessToken: string, refreshToken = ''): void {
+    this.accessToken = accessToken;
+    this.refreshToken = refreshToken;
+  }
+
+  getAccessToken(): string | null {
+    return this.accessToken;
+  }
+
+  getRefreshToken(): string | null {
+    return this.refreshToken;
+  }
+
+  clearTokens(): void {
+    this.accessToken = null;
+    this.refreshToken = null;
+  }
+
+  hasAccessToken(): boolean {
+    return !!this.accessToken;
+  }
+}
+
+/**
+ * HTTP Client Service
+ * 
+ * Manages Axios instance with authentication interceptors.
+ * All HTTP requests should go through this service to ensure authentication.
+ */
+export class HttpClient {
+  private client: AxiosInstance;
+  private tokenStore: TokenStore;
+  private logger: SimpleLogger;
+  private baseURL: string;
+
+  constructor(config: OxyConfig) {
+    this.baseURL = config.baseURL;
+    this.tokenStore = TokenStore.getInstance();
+    this.logger = new SimpleLogger(
+      config.enableLogging || false,
+      config.logLevel || 'error',
+      'HttpClient'
+    );
+
+    const timeout = config.requestTimeout || 5000;
+
+    // Create Axios instance with optimized configuration
+    this.client = axios.create({
+      baseURL: config.baseURL,
+      timeout,
+      headers: {
+        'Accept': 'application/json',
+      },
+      // Enable HTTP keep-alive for connection reuse (Node.js only)
+      ...(typeof process !== 'undefined' && 
+          process.env && 
+          typeof window === 'undefined' && 
+          typeof require !== 'undefined' ? {
+        httpAgent: new (require('http').Agent)({ 
+          keepAlive: true, 
+          keepAliveMsecs: 1000, 
+          maxSockets: 50 
+        }),
+        httpsAgent: new (require('https').Agent)({ 
+          keepAlive: true, 
+          keepAliveMsecs: 1000, 
+          maxSockets: 50 
+        }),
+      } : {}),
+    });
+
+    this.setupInterceptors();
+  }
+
+  /**
+   * Setup axios interceptors for authentication and error handling
+   */
+  private setupInterceptors(): void {
+    // Request interceptor: Add authentication header
+    this.client.interceptors.request.use(
+      async (req: InternalAxiosRequestConfig) => {
+        const accessToken = this.tokenStore.getAccessToken();
+        if (!accessToken) {
+          return req;
+        }
+
+        try {
+          const decoded = jwtDecode<JwtPayload>(accessToken);
+          const currentTime = Math.floor(Date.now() / 1000);
+
+          // If token expires in less than 60 seconds, refresh it
+          if (decoded.exp && decoded.exp - currentTime < 60) {
+            if (decoded.sessionId) {
+              try {
+                // Create a new axios instance to avoid interceptor recursion
+                const refreshClient = axios.create({
+                  baseURL: this.client.defaults.baseURL,
+                  timeout: this.client.defaults.timeout,
+                });
+                const res = await refreshClient.get(`/api/session/token/${decoded.sessionId}`);
+                this.tokenStore.setTokens(res.data.accessToken);
+                req.headers.Authorization = `Bearer ${res.data.accessToken}`;
+                this.logger.debug('Token refreshed');
+              } catch (refreshError) {
+                // If refresh fails, use current token anyway
+                req.headers.Authorization = `Bearer ${accessToken}`;
+                this.logger.warn('Token refresh failed, using current token');
+              }
+            } else {
+              req.headers.Authorization = `Bearer ${accessToken}`;
+            }
+          } else {
+            req.headers.Authorization = `Bearer ${accessToken}`;
+          }
+        } catch (error) {
+          this.logger.error('Error processing token:', error);
+          // Even if there's an error, still try to use the token
+          req.headers.Authorization = `Bearer ${accessToken}`;
+        }
+
+        return req;
+      },
+      (error) => {
+        this.logger.error('Request interceptor error:', error);
+        return Promise.reject(error);
+      }
+    );
+
+    // Response interceptor: Handle auth errors
+    this.client.interceptors.response.use(
+      (response) => response,
+      (error) => {
+        if (error.response?.status === 401) {
+          this.logger.warn('401 Unauthorized, clearing tokens');
+          this.tokenStore.clearTokens();
+        }
+        return Promise.reject(error);
+      }
+    );
+  }
+
+  /**
+   * Get the underlying Axios instance
+   * Use this only when you need direct access to Axios features
+   */
+  getAxiosInstance(): AxiosInstance {
+    return this.client;
+  }
+
+  /**
+   * Make a raw HTTP request (no caching, deduplication, etc.)
+   * Use this for requests that need to bypass performance features
+   */
+  async request<T = any>(config: {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    url: string;
+    data?: any;
+    params?: any;
+    timeout?: number;
+    signal?: AbortSignal;
+  }): Promise<T> {
+    try {
+      const response = await this.client.request<T>({
+        method: config.method,
+        url: config.url,
+        data: config.data,
+        params: config.params,
+        timeout: config.timeout,
+        signal: config.signal,
+      });
+      
+      // Unwrap standardized API response format: { data: ... }
+      // This handles responses from sendSuccess() and sendPaginated() helpers
+      const responseData = response.data as any;
+      
+      // Handle paginated responses: { data: [...], pagination: {...} }
+      // Return the data array directly - the calling method will wrap it appropriately
+      if (responseData && typeof responseData === 'object' && 'data' in responseData && 'pagination' in responseData) {
+        // For paginated responses, return the data array directly
+        // The calling methods like getUserFollowers/getUserFollowing will handle wrapping
+        // We return the whole response so methods can access both data and pagination
+        return responseData as T;
+      }
+      
+      // Handle regular success responses: { data: ... }
+      if (responseData && typeof responseData === 'object' && 'data' in responseData) {
+        return responseData.data as T;
+      }
+      
+      // Return as-is for responses that don't use sendSuccess wrapper
+      return responseData as T;
+    } catch (error) {
+      throw handleHttpError(error);
+    }
+  }
+
+  /**
+   * Get base URL
+   */
+  getBaseURL(): string {
+    return this.baseURL;
+  }
+
+  /**
+   * Set authentication tokens
+   */
+  setTokens(accessToken: string, refreshToken = ''): void {
+    this.tokenStore.setTokens(accessToken, refreshToken);
+  }
+
+  /**
+   * Clear authentication tokens
+   */
+  clearTokens(): void {
+    this.tokenStore.clearTokens();
+  }
+
+  /**
+   * Get access token
+   */
+  getAccessToken(): string | null {
+    return this.tokenStore.getAccessToken();
+  }
+
+  /**
+   * Check if has access token
+   */
+  hasAccessToken(): boolean {
+    return this.tokenStore.hasAccessToken();
+  }
+
+  // Test-only utility to reset global tokens between jest tests
+  static __resetTokensForTests(): void {
+    try {
+      TokenStore.getInstance().clearTokens();
+    } catch {}
+  }
+}
+