@oxyhq/services 5.9.2 → 5.9.4

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

@@ -0,0 +1,102 @@
+/**
+ * React hook utilities for common patterns and state management
+ */
+/**
+ * Hook for managing async operations with loading, error, and data states
+ */
+export declare function useAsync<T>(asyncFn: () => Promise<T>, deps?: any[]): {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    execute: () => Promise<T>;
+};
+/**
+ * Hook for managing async operations that execute on mount
+ */
+export declare function useAsyncEffect<T>(asyncFn: () => Promise<T>, deps?: any[]): {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+};
+/**
+ * Hook for debounced values
+ */
+export declare function useDebounce<T>(value: T, delay: number): T;
+/**
+ * Hook for throttled values
+ */
+export declare function useThrottle<T>(value: T, delay: number): T;
+/**
+ * Hook for previous value
+ */
+export declare function usePrevious<T>(value: T): T | undefined;
+/**
+ * Hook for boolean state with toggle
+ */
+export declare function useToggle(initialValue?: boolean): {
+    value: boolean;
+    toggle: () => void;
+    setTrue: () => void;
+    setFalse: () => void;
+    setValue: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+};
+/**
+ * Hook for counter state
+ */
+export declare function useCounter(initialValue?: number): {
+    count: number;
+    increment: () => void;
+    decrement: () => void;
+    reset: () => void;
+    setValue: (value: number) => void;
+};
+/**
+ * Hook for local storage
+ */
+export declare function useLocalStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void];
+/**
+ * Hook for session storage
+ */
+export declare function useSessionStorage<T>(key: string, initialValue: T): readonly [T, (value: T | ((val: T) => T)) => void];
+/**
+ * Hook for window size
+ */
+export declare function useWindowSize(): {
+    width: number;
+    height: number;
+};
+/**
+ * Hook for scroll position
+ */
+export declare function useScrollPosition(): number;
+/**
+ * Hook for online/offline status
+ */
+export declare function useOnlineStatus(): boolean;
+/**
+ * Hook for media queries
+ */
+export declare function useMediaQuery(query: string): boolean;
+/**
+ * Hook for keyboard events
+ */
+export declare function useKeyPress(targetKey: string): boolean;
+/**
+ * Hook for click outside detection
+ */
+export declare function useClickOutside(ref: React.RefObject<HTMLElement>, handler: () => void): void;
+/**
+ * Hook for form validation
+ */
+export declare function useFormValidation<T extends Record<string, any>>(initialValues: T, validationSchema: (values: T) => Partial<Record<keyof T, string>>): {
+    values: T;
+    errors: Partial<Record<keyof T, string>>;
+    touched: Partial<Record<keyof T, boolean>>;
+    isValid: boolean;
+    setValue: (field: keyof T, value: any) => void;
+    setTouchedField: (field: keyof T) => void;
+    setValues: import("react").Dispatch<import("react").SetStateAction<T>>;
+    setErrors: import("react").Dispatch<import("react").SetStateAction<Partial<Record<keyof T, string>>>>;
+    setTouched: import("react").Dispatch<import("react").SetStateAction<Partial<Record<keyof T, boolean>>>>;
+};
+//# sourceMappingURL=hookUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hookUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/hookUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,IAAI,GAAE,GAAG,EAAO;;;;;EAwBjB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,IAAI,GAAE,GAAG,EAAO;;;;EAiCjB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAczD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,CAkBzD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAQtD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,YAAY,GAAE,OAAe;;;;;;EAQtD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,YAAY,GAAE,MAAU;;;;;sBAMZ,MAAM;EAG5C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,wBAWxB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,WAWzD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,wBAW1B,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,WAWzD;AAED;;GAEG;AACH,wBAAgB,aAAa;;;EAmB5B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,WAahC;AAED;;GAEG;AACH,wBAAgB,eAAe,YAiB9B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAgBpD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CA0BtD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,MAAM,IAAI,QAiBrF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7D,aAAa,EAAE,CAAC,EAChB,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;;;;;sBAU5B,MAAM,CAAC,SAAS,GAAG;6BAQZ,MAAM,CAAC;;;;EAsBpD"}

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

@@ -0,0 +1,49 @@
+/**
+ * Centralized logging utilities for consistent logging across the application
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+export interface LogContext {
+    component?: string;
+    method?: string;
+    userId?: string;
+    sessionId?: string;
+    requestId?: string;
+    [key: string]: any;
+}
+declare class Logger {
+    private level;
+    private isDevelopment;
+    setLevel(level: LogLevel): void;
+    private shouldLog;
+    private formatMessage;
+    debug(message: string, context?: LogContext, ...args: any[]): void;
+    info(message: string, context?: LogContext, ...args: any[]): void;
+    warn(message: string, context?: LogContext, ...args: any[]): void;
+    error(message: string, error?: any, context?: LogContext, ...args: any[]): void;
+    auth(message: string, context?: LogContext, ...args: any[]): void;
+    api(message: string, context?: LogContext, ...args: any[]): void;
+    session(message: string, context?: LogContext, ...args: any[]): void;
+    user(message: string, context?: LogContext, ...args: any[]): void;
+    device(message: string, context?: LogContext, ...args: any[]): void;
+    payment(message: string, context?: LogContext, ...args: any[]): void;
+    performance(operation: string, duration: number, context?: LogContext): void;
+    errorWithStack(message: string, error: Error, context?: LogContext): void;
+    group(label: string, fn: () => void): void;
+}
+export declare const logger: Logger;
+export declare const logAuth: (message: string, context?: LogContext, ...args: any[]) => void;
+export declare const logApi: (message: string, context?: LogContext, ...args: any[]) => void;
+export declare const logSession: (message: string, context?: LogContext, ...args: any[]) => void;
+export declare const logUser: (message: string, context?: LogContext, ...args: any[]) => void;
+export declare const logDevice: (message: string, context?: LogContext, ...args: any[]) => void;
+export declare const logPayment: (message: string, context?: LogContext, ...args: any[]) => void;
+export declare const logError: (message: string, error?: any, context?: LogContext, ...args: any[]) => void;
+export declare const logPerformance: (operation: string, duration: number, context?: LogContext) => void;
+export {};
+//# sourceMappingURL=loggerUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loggerUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/loggerUtils.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,80 @@
+/**
+ * Validation utilities for common data validation patterns
+ */
+/**
+ * Email validation regex
+ */
+export declare const EMAIL_REGEX: RegExp;
+/**
+ * Username validation regex (alphanumeric, underscore, dash, 3-30 chars)
+ */
+export declare const USERNAME_REGEX: RegExp;
+/**
+ * Password validation regex (at least 8 chars, 1 uppercase, 1 lowercase, 1 number)
+ */
+export declare const PASSWORD_REGEX: RegExp;
+/**
+ * Validate email format
+ */
+export declare function isValidEmail(email: string): boolean;
+/**
+ * Validate username format
+ */
+export declare function isValidUsername(username: string): boolean;
+/**
+ * Validate password strength
+ */
+export declare function isValidPassword(password: string): boolean;
+/**
+ * Validate required string
+ */
+export declare function isRequiredString(value: any): boolean;
+/**
+ * Validate required number
+ */
+export declare function isRequiredNumber(value: any): boolean;
+/**
+ * Validate required boolean
+ */
+export declare function isRequiredBoolean(value: any): boolean;
+/**
+ * Validate array
+ */
+export declare function isValidArray(value: any): boolean;
+/**
+ * Validate object
+ */
+export declare function isValidObject(value: any): boolean;
+/**
+ * Validate UUID format
+ */
+export declare function isValidUUID(uuid: string): boolean;
+/**
+ * Validate URL format
+ */
+export declare function isValidURL(url: string): boolean;
+/**
+ * Validate date string
+ */
+export declare function isValidDate(dateString: string): boolean;
+/**
+ * Validate file size (in bytes)
+ */
+export declare function isValidFileSize(size: number, maxSize: number): boolean;
+/**
+ * Validate file type
+ */
+export declare function isValidFileType(filename: string, allowedTypes: string[]): boolean;
+/**
+ * Sanitize string input
+ */
+export declare function sanitizeString(input: string): string;
+/**
+ * Sanitize HTML input
+ */
+export declare function sanitizeHTML(input: string): string;
+/**
+ * Validate and sanitize user input
+ */
+export declare function validateAndSanitizeUserInput(input: any, type: 'string' | 'email' | 'username'): string | null;
+//# sourceMappingURL=validationUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validationUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/validationUtils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,QAA+B,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,cAAc,QAA0B,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,cAAc,QAA0D,CAAC;AAEtF;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAEhD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAEjD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGjD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAGjF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAiB7G"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@oxyhq/services",
-    "version": "5.9.2",
+    "version": "5.9.4",
     "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",
@@ -33,10 +33,6 @@
     "files": [
         "src",
         "lib",
-        "mock.js",
-        "UI_COMPONENTS.md",
-        "CHANGELOG.md",
-        "MIGRATION_GUIDE.md",
         "assets"
     ],
     "keywords": [
@@ -63,9 +59,7 @@
         "copy-dts": "copyfiles -u 1 \"src/**/*.d.ts\" lib/typescript",
         "delete-debug-view": "rm -rf ./lib/commonjs/components/bottomSheetDebugView ./lib/module/components/bottomSheetDebugView ./lib/typescript/components/bottomSheetDebugView || true",
         "delete-dts.js": "find ./lib/commonjs -name '*.d.js*' -delete && find ./lib/module -name '*.d.js*' -delete",
-        "release": "rm -rf lib && npm run build && release-it",
-        "example": "npm --cwd example",
-        "bootstrap": "npm install && npm run example"
+        "release": "rm -rf lib && npm run build && release-it"
     },
     "dependencies": {
         "@react-native-async-storage/async-storage": "^2.1.2",

package/src/core/OxyServices.ts

@@ -0,0 +1,351 @@
+import axios, { AxiosInstance, InternalAxiosRequestConfig } from 'axios';
+import { jwtDecode } from 'jwt-decode';
+import { OxyConfig, ApiError, User } from '../models/interfaces';
+import { handleHttpError } from '../utils/errorUtils';
+
+interface JwtPayload {
+  exp: number;
+  userId: string;
+  [key: string]: any;
+}
+
+/**
+ * OxyServices - Base client library for interacting with the Oxy API
+ * 
+ * This class provides the core HTTP client setup, token management, and error handling.
+ * Specific functionality is delegated to focused service modules.
+ */
+export class OxyServices {
+  protected client: AxiosInstance;
+  private accessToken: string | null = null;
+  private refreshToken: string | null = null;
+
+  /**
+   * Creates a new instance of the OxyServices client
+   * @param config - Configuration for the client
+   */
+  constructor(config: OxyConfig) {
+    this.client = axios.create({ 
+      baseURL: config.baseURL,
+      timeout: 10000 // 10 second timeout
+    });
+    
+    this.setupInterceptors();
+  }
+
+  /**
+   * Setup axios interceptors for authentication and error handling
+   */
+  private setupInterceptors(): void {
+    // Request interceptor for adding auth header and handling token refresh
+    this.client.interceptors.request.use(async (req: InternalAxiosRequestConfig) => {
+      if (!this.accessToken) {
+        return req;
+      }
+      
+      // Check if token is expired and refresh if needed
+      try {
+        const decoded = jwtDecode<JwtPayload>(this.accessToken);
+        const currentTime = Math.floor(Date.now() / 1000);
+      
+        // If token expires in less than 60 seconds, refresh it
+        if (decoded.exp - currentTime < 60) {
+          // For session-based tokens, get a new token from the session
+          if (decoded.sessionId) {
+            try {
+              const res = await this.client.get(`/session/token/${decoded.sessionId}`);
+              this.accessToken = res.data.accessToken;
+            } catch (refreshError) {
+              // If refresh fails, clear tokens
+              this.clearTokens();
+            }
+          }
+        }
+        
+        // Add authorization header
+        req.headers.Authorization = `Bearer ${this.accessToken}`;
+      } catch (error) {
+        // If token is invalid, clear it
+        this.clearTokens();
+      }
+      
+      return req;
+    });
+  }
+
+  /**
+   * Get the configured base URL
+   */
+  public getBaseURL(): string {
+    return this.client.defaults.baseURL || '';
+  }
+
+  /**
+   * Set authentication tokens
+   */
+  public setTokens(accessToken: string, refreshToken: string = ''): void {
+    this.accessToken = accessToken;
+    this.refreshToken = refreshToken;
+  }
+
+  /**
+   * Clear stored authentication tokens
+   */
+  public clearTokens(): void {
+    this.accessToken = null;
+    this.refreshToken = null;
+  }
+
+  /**
+   * Get the current user ID from the access token
+   */
+  public getCurrentUserId(): string | null {
+    if (!this.accessToken) {
+      return null;
+    }
+    
+    try {
+      const decoded = jwtDecode<JwtPayload>(this.accessToken);
+      return decoded.userId || decoded.id || null;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Check if the client has a valid access token
+   */
+  private hasAccessToken(): boolean {
+    return !!this.accessToken;
+  }
+
+  /**
+   * Validate the current access token with the server
+   */
+  async validate(): Promise<boolean> {
+    if (!this.hasAccessToken()) {
+      return false;
+    }
+
+    try {
+      const res = await this.client.get('/auth/validate');
+      return res.data.valid === true;
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Get the HTTP client instance (protected for use by service modules)
+   */
+  protected getClient(): AxiosInstance {
+    return this.client;
+  }
+
+  /**
+   * Centralized error handling
+   */
+  protected handleError(error: any): ApiError {
+    return handleHttpError(error);
+  }
+
+  /**
+   * Health check endpoint
+   */
+  async healthCheck(): Promise<{ 
+    status: string; 
+    users?: number; 
+    timestamp?: string; 
+    [key: string]: any 
+  }> {
+    try {
+      const res = await this.client.get('/health');
+      return res.data;
+    } 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: {
+    debug?: boolean;
+    onError?: (error: ApiError) => any;
+    loadUser?: boolean;
+    session?: boolean;
+  } = {}) {
+    const { debug = false, onError, loadUser = false, session = false } = options;
+    
+    return async (req: any, res: any, next: any) => {
+      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: JwtPayload;
+        try {
+          decoded = jwtDecode<JwtPayload>(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);
+        }
+        
+        // Session-based validation if requested
+        if (session && decoded.sessionId) {
+          try {
+            if (debug) console.log(`🔐 Auth: Validating session ${decoded.sessionId}`);
+            
+            const sessionRes = await this.client.get(`/session/validate/${decoded.sessionId}`);
+            const sessionData = sessionRes.data;
+            
+            if (!sessionData.valid) {
+              const error = {
+                message: 'Invalid session',
+                code: 'INVALID_SESSION',
+                status: 403
+              };
+              
+              if (debug) console.log(`❌ Auth: Session validation failed`);
+              
+              if (onError) return onError(error);
+              return res.status(403).json(error);
+            }
+            
+            if (debug) console.log(`✅ Auth: Session validation successful`);
+          } catch (sessionError) {
+            const error = {
+              message: 'Session validation failed',
+              code: 'SESSION_VALIDATION_ERROR',
+              status: 403
+            };
+            
+            if (debug) console.log(`❌ Auth: Session validation error`);
+            
+            if (onError) return onError(error);
+            return res.status(403).json(error);
+          }
+        }
+        
+        // Set request properties
+        req.userId = userId;
+        req.accessToken = token;
+        
+        // Load user data if requested
+        if (loadUser) {
+          try {
+            const userRes = await this.client.get(`/users/${userId}`);
+            req.user = userRes.data;
+          } catch (userError) {
+            // If user loading fails, just use minimal user data
+            req.user = { id: userId } as User;
+            if (debug) console.log(`⚠️ Auth: Failed to load user data, using minimal data`);
+          }
+        } else {
+          // Use minimal user data for performance
+          req.user = { id: userId } as User;
+        }
+        
+        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.status || 500).json(apiError);
+      }
+    };
+  }
+} 

package/src/core/OxyServicesMain.ts

@@ -0,0 +1,57 @@
+import { OxyConfig } from '../models/interfaces';
+import { AuthService } from './auth/AuthService';
+import { UserService } from './users/UserService';
+import { PaymentService } from './payments/PaymentService';
+import { KarmaService } from './karma/KarmaService';
+import { FileService, OXY_CLOUD_URL } from './files/FileService';
+import { LocationService } from './locations/LocationService';
+import { AnalyticsService } from './analytics/AnalyticsService';
+import { DeviceService } from './devices/DeviceService';
+
+/**
+ * Main OxyServices class that combines all individual services
+ * 
+ * This class provides a unified interface to all Oxy API services while maintaining
+ * backward compatibility with the original monolithic structure.
+ */
+export class OxyServicesMain extends AuthService {
+  // Service instances
+  public readonly users: UserService;
+  public readonly payments: PaymentService;
+  public readonly karma: KarmaService;
+  public readonly files: FileService;
+  public readonly locations: LocationService;
+  public readonly analytics: AnalyticsService;
+  public readonly devices: DeviceService;
+
+  constructor(config: OxyConfig) {
+    super(config);
+    
+    // Initialize all service instances
+    this.users = new UserService(config);
+    this.payments = new PaymentService(config);
+    this.karma = new KarmaService(config);
+    this.files = new FileService(config);
+    this.locations = new LocationService(config);
+    this.analytics = new AnalyticsService(config);
+    this.devices = new DeviceService(config);
+  }
+
+  // Re-export OXY_CLOUD_URL for convenience
+  static readonly OXY_CLOUD_URL = OXY_CLOUD_URL;
+
+  // Additional utility methods that span multiple services
+  async fetchLinkMetadata(url: string): Promise<{
+    url: string;
+    title: string;
+    description: string;
+    image?: string;
+  }> {
+    try {
+      const res = await this.getClient().get(`/link-metadata?url=${encodeURIComponent(url)}`);
+      return res.data;
+    } catch (error) {
+      throw this.handleError(error);
+    }
+  }
+}