@rooguys/js 0.1.0 → 1.0.0

package/src/index.js

@@ -1,138 +1,928 @@
 /**
  * Rooguys Browser SDK
+ * Official JavaScript SDK for the Rooguys Gamification Platform
+ */
+
+import { HttpClient, extractRateLimitInfo, extractRequestId, parseResponseBody } from './http-client.js';
+import {
+  RooguysError,
+  ValidationError,
+  AuthenticationError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  RateLimitError,
+  ServerError,
+  mapStatusToError,
+} from './errors.js';
+
+/**
+ * Main Rooguys SDK class
  */
 class Rooguys {
+  /**
+   * Create a new Rooguys SDK instance
+   * @param {string} apiKey - API key for authentication
+   * @param {Object} [options] - Configuration options
+   * @param {string} [options.baseUrl] - Base URL for API (default: https://api.rooguys.com/v1)
+   * @param {number} [options.timeout] - Request timeout in ms (default: 10000)
+   * @param {Function} [options.onRateLimitWarning] - Callback when rate limit is 80% consumed
+   * @param {boolean} [options.autoRetry] - Enable auto-retry for rate-limited requests (default: false)
+   * @param {number} [options.maxRetries] - Maximum retry attempts for rate limits (default: 3)
+   */
   constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new ValidationError('API key is required', { code: 'MISSING_API_KEY' });
+    }
+
     this.apiKey = apiKey;
     this.baseUrl = options.baseUrl || 'https://api.rooguys.com/v1';
     this.timeout = options.timeout || 10000;
+    this.onRateLimitWarning = options.onRateLimitWarning || null;
+    this.autoRetry = options.autoRetry || false;
+    this.maxRetries = options.maxRetries || 3;
+
+    // Initialize HTTP client
+    this._httpClient = new HttpClient(apiKey, {
+      baseUrl: this.baseUrl,
+      timeout: this.timeout,
+      onRateLimitWarning: this.onRateLimitWarning,
+      autoRetry: this.autoRetry,
+      maxRetries: this.maxRetries,
+    });
   }
 
+  /**
+   * Legacy request method for backward compatibility
+   * @deprecated Use the new module methods instead
+   */
   async _request(endpoint, method = 'GET', data = null, params = {}) {
-    const url = new URL(`${this.baseUrl}${endpoint}`);
-    Object.keys(params).forEach(key => {
-      if (params[key] !== undefined) {
-        url.searchParams.append(key, params[key]);
-      }
+    const response = await this._httpClient.request({
+      method,
+      path: endpoint,
+      body: data,
+      params,
     });
+    return response.data;
+  }
 
-    const config = {
-      method,
-      headers: {
-        'x-api-key': this.apiKey,
-        'Content-Type': 'application/json',
+  /**
+   * Events module for tracking user events
+   */
+  get events() {
+    const self = this;
+    return {
+      /**
+       * Track a single event
+       * @param {string} eventName - Name of the event
+       * @param {string} userId - User ID
+       * @param {Object} [properties] - Event properties
+       * @param {Object} [options] - Additional options
+       * @param {boolean} [options.includeProfile] - Include user profile in response
+       * @param {Date} [options.timestamp] - Custom timestamp for historical events (max 7 days old)
+       * @param {string} [options.idempotencyKey] - Idempotency key to prevent duplicate processing
+       * @returns {Promise<Object>} Event tracking response
+       */
+      track: async (eventName, userId, properties = {}, options = {}) => {
+        const body = {
+          event_name: eventName,
+          user_id: userId,
+          properties,
+        };
+
+        // Add custom timestamp if provided
+        if (options.timestamp) {
+          const timestamp = options.timestamp instanceof Date ? options.timestamp : new Date(options.timestamp);
+          const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+          
+          if (timestamp < sevenDaysAgo) {
+            throw new ValidationError('Custom timestamp cannot be more than 7 days in the past', {
+              code: 'TIMESTAMP_TOO_OLD',
+              fieldErrors: [{ field: 'timestamp', message: 'Timestamp must be within the last 7 days' }],
+            });
+          }
+          
+          body.timestamp = timestamp.toISOString();
+        }
+
+        const response = await self._httpClient.post('/events', body, {
+          params: {
+            include_profile: options.includeProfile,
+          },
+          idempotencyKey: options.idempotencyKey,
+        });
+        return response.data;
       },
-    };
 
-    if (data) {
-      config.body = JSON.stringify(data);
-    }
+      /**
+       * Track multiple events in a single request (batch operation)
+       * @param {Array<Object>} events - Array of events to track (max 100)
+       * @param {string} events[].eventName - Name of the event
+       * @param {string} events[].userId - User ID
+       * @param {Object} [events[].properties] - Event properties
+       * @param {Date} [events[].timestamp] - Custom timestamp for historical events
+       * @param {Object} [options] - Batch options
+       * @param {string} [options.idempotencyKey] - Idempotency key for the batch
+       * @returns {Promise<Object>} Batch tracking response with individual status for each event
+       */
+      trackBatch: async (events, options = {}) => {
+        // Validate array
+        if (!Array.isArray(events)) {
+          throw new ValidationError('Events must be an array', {
+            code: 'INVALID_EVENTS',
+            fieldErrors: [{ field: 'events', message: 'Events must be an array' }],
+          });
+        }
 
-    try {
-      const controller = new AbortController();
-      const id = setTimeout(() => controller.abort(), this.timeout);
-      config.signal = controller.signal;
+        // Validate array length
+        if (events.length === 0) {
+          throw new ValidationError('Events array cannot be empty', {
+            code: 'EMPTY_EVENTS',
+            fieldErrors: [{ field: 'events', message: 'At least one event is required' }],
+          });
+        }
 
-      const response = await fetch(url.toString(), config);
-      clearTimeout(id);
+        if (events.length > 100) {
+          throw new ValidationError('Batch size exceeds maximum of 100 events', {
+            code: 'BATCH_TOO_LARGE',
+            fieldErrors: [{ field: 'events', message: 'Maximum batch size is 100 events' }],
+          });
+        }
 
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        throw new Error(errorData.message || `API Error: ${response.statusText}`);
-      }
+        const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
 
-      return await response.json();
-    } catch (error) {
-      throw error;
-    }
-  }
+        // Transform and validate events
+        const transformedEvents = events.map((event, index) => {
+          const transformed = {
+            event_name: event.eventName,
+            user_id: event.userId,
+            properties: event.properties || {},
+          };
 
-  get events() {
-    return {
-      track: (eventName, userId, properties = {}, options = {}) => {
-        return this._request('/event', 'POST', {
+          // Validate and add custom timestamp if provided
+          if (event.timestamp) {
+            const timestamp = event.timestamp instanceof Date ? event.timestamp : new Date(event.timestamp);
+            
+            if (timestamp < sevenDaysAgo) {
+              throw new ValidationError(`Event at index ${index}: Custom timestamp cannot be more than 7 days in the past`, {
+                code: 'TIMESTAMP_TOO_OLD',
+                fieldErrors: [{ field: `events[${index}].timestamp`, message: 'Timestamp must be within the last 7 days' }],
+              });
+            }
+            
+            transformed.timestamp = timestamp.toISOString();
+          }
+
+          return transformed;
+        });
+
+        const response = await self._httpClient.post('/events/batch', {
+          events: transformedEvents,
+        }, {
+          idempotencyKey: options.idempotencyKey,
+        });
+        return response.data;
+      },
+
+      /**
+       * @deprecated Use track() instead. The /v1/event endpoint is deprecated.
+       * Track a single event using the legacy endpoint
+       * @param {string} eventName - Name of the event
+       * @param {string} userId - User ID
+       * @param {Object} [properties] - Event properties
+       * @param {Object} [options] - Additional options
+       * @returns {Promise<Object>} Event tracking response
+       */
+      trackLegacy: async (eventName, userId, properties = {}, options = {}) => {
+        console.warn('DEPRECATION WARNING: events.trackLegacy() uses the deprecated /v1/event endpoint. Please use events.track() instead which uses /v1/events.');
+        
+        const response = await self._httpClient.post('/event', {
           event_name: eventName,
           user_id: userId,
           properties,
         }, {
-          include_profile: options.includeProfile,
+          params: {
+            include_profile: options.includeProfile,
+          },
         });
+        return response.data;
       },
     };
   }
 
+  /**
+   * Users module for user management and queries
+   */
   get users() {
-    return {
-      get: (userId) => this._request(`/user/${encodeURIComponent(userId)}`),
-      
-      getBulk: (userIds) => this._request('/users/bulk', 'POST', { user_ids: userIds }),
+    const self = this;
+    
+    /**
+     * Validate email format client-side
+     * @param {string} email - Email to validate
+     * @returns {boolean} True if valid
+     */
+    const isValidEmail = (email) => {
+      if (!email || typeof email !== 'string') return true; // Optional field
+      // RFC 5322 compliant email regex (simplified)
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+      return emailRegex.test(email);
+    };
+
+    /**
+     * Build request body with only provided fields (partial update support)
+     * @param {Object} userData - User data object
+     * @returns {Object} Cleaned request body
+     */
+    const buildUserRequestBody = (userData) => {
+      const body = {};
       
-      getBadges: (userId) => this._request(`/user/${encodeURIComponent(userId)}/badges`),
+      if (userData.userId !== undefined) {
+        body.user_id = userData.userId;
+      }
+      if (userData.displayName !== undefined) {
+        body.display_name = userData.displayName;
+      }
+      if (userData.email !== undefined) {
+        body.email = userData.email;
+      }
+      if (userData.metadata !== undefined) {
+        body.metadata = userData.metadata;
+      }
+      if (userData.firstName !== undefined) {
+        body.first_name = userData.firstName;
+      }
+      if (userData.lastName !== undefined) {
+        body.last_name = userData.lastName;
+      }
       
-      getRank: (userId, timeframe = 'all-time') => 
-        this._request(`/user/${encodeURIComponent(userId)}/rank`, 'GET', null, { timeframe }),
+      return body;
+    };
+
+    return {
+      /**
+       * Create a new user
+       * @param {Object} userData - User data
+       * @param {string} userData.userId - Unique user ID
+       * @param {string} [userData.displayName] - Display name
+       * @param {string} [userData.email] - Email address
+       * @param {string} [userData.firstName] - First name
+       * @param {string} [userData.lastName] - Last name
+       * @param {Object} [userData.metadata] - Custom metadata
+       * @returns {Promise<Object>} Created user profile
+       */
+      create: async (userData) => {
+        // Validate required fields
+        if (!userData || !userData.userId) {
+          throw new ValidationError('User ID is required', {
+            code: 'MISSING_USER_ID',
+            fieldErrors: [{ field: 'userId', message: 'User ID is required' }],
+          });
+        }
+
+        // Validate email format if provided
+        if (userData.email && !isValidEmail(userData.email)) {
+          throw new ValidationError('Invalid email format', {
+            code: 'INVALID_EMAIL',
+            fieldErrors: [{ field: 'email', message: 'Email must be a valid email address' }],
+          });
+        }
+
+        const body = buildUserRequestBody(userData);
+        const response = await self._httpClient.post('/users', body);
+        return response.data;
+      },
+
+      /**
+       * Update an existing user
+       * @param {string} userId - User ID to update
+       * @param {Object} userData - User data to update (partial update supported)
+       * @param {string} [userData.displayName] - Display name
+       * @param {string} [userData.email] - Email address
+       * @param {string} [userData.firstName] - First name
+       * @param {string} [userData.lastName] - Last name
+       * @param {Object} [userData.metadata] - Custom metadata
+       * @returns {Promise<Object>} Updated user profile
+       */
+      update: async (userId, userData) => {
+        // Validate user ID
+        if (!userId) {
+          throw new ValidationError('User ID is required', {
+            code: 'MISSING_USER_ID',
+            fieldErrors: [{ field: 'userId', message: 'User ID is required' }],
+          });
+        }
+
+        // Validate email format if provided
+        if (userData.email && !isValidEmail(userData.email)) {
+          throw new ValidationError('Invalid email format', {
+            code: 'INVALID_EMAIL',
+            fieldErrors: [{ field: 'email', message: 'Email must be a valid email address' }],
+          });
+        }
+
+        const body = buildUserRequestBody(userData);
+        const response = await self._httpClient.patch(`/users/${encodeURIComponent(userId)}`, body);
+        return response.data;
+      },
+
+      /**
+       * Create multiple users in a single request (batch operation)
+       * @param {Array<Object>} users - Array of user data objects (max 100)
+       * @param {string} users[].userId - Unique user ID
+       * @param {string} [users[].displayName] - Display name
+       * @param {string} [users[].email] - Email address
+       * @param {Object} [users[].metadata] - Custom metadata
+       * @returns {Promise<Object>} Batch creation response with individual status for each user
+       */
+      createBatch: async (users) => {
+        // Validate array
+        if (!Array.isArray(users)) {
+          throw new ValidationError('Users must be an array', {
+            code: 'INVALID_USERS',
+            fieldErrors: [{ field: 'users', message: 'Users must be an array' }],
+          });
+        }
+
+        // Validate array length
+        if (users.length === 0) {
+          throw new ValidationError('Users array cannot be empty', {
+            code: 'EMPTY_USERS',
+            fieldErrors: [{ field: 'users', message: 'At least one user is required' }],
+          });
+        }
+
+        if (users.length > 100) {
+          throw new ValidationError('Batch size exceeds maximum of 100 users', {
+            code: 'BATCH_TOO_LARGE',
+            fieldErrors: [{ field: 'users', message: 'Maximum batch size is 100 users' }],
+          });
+        }
+
+        // Validate and transform each user
+        const transformedUsers = users.map((user, index) => {
+          // Validate required fields
+          if (!user.userId) {
+            throw new ValidationError(`User at index ${index}: User ID is required`, {
+              code: 'MISSING_USER_ID',
+              fieldErrors: [{ field: `users[${index}].userId`, message: 'User ID is required' }],
+            });
+          }
+
+          // Validate email format if provided
+          if (user.email && !isValidEmail(user.email)) {
+            throw new ValidationError(`User at index ${index}: Invalid email format`, {
+              code: 'INVALID_EMAIL',
+              fieldErrors: [{ field: `users[${index}].email`, message: 'Email must be a valid email address' }],
+            });
+          }
+
+          return buildUserRequestBody(user);
+        });
+
+        const response = await self._httpClient.post('/users/batch', { users: transformedUsers });
+        return response.data;
+      },
+
+      /**
+       * Get user profile with optional field selection
+       * @param {string} userId - User ID
+       * @param {Object} [options] - Query options
+       * @param {string[]} [options.fields] - Fields to include in response
+       * @returns {Promise<Object>} User profile
+       */
+      get: async (userId, options = {}) => {
+        const params = {};
         
-      submitAnswers: (userId, questionnaireId, answers) =>
-        this._request(`/user/${encodeURIComponent(userId)}/answers`, 'POST', {
-          questionnaire_id: questionnaireId,
-          answers,
-        }),
+        // Add field selection if provided
+        if (options.fields && Array.isArray(options.fields) && options.fields.length > 0) {
+          params.fields = options.fields.join(',');
+        }
+
+        const response = await self._httpClient.get(`/users/${encodeURIComponent(userId)}`, params);
+        return self._parseUserProfile(response.data);
+      },
+
+      /**
+       * Search users with pagination
+       * @param {string} query - Search query
+       * @param {Object} [options] - Search options
+       * @param {number} [options.page=1] - Page number
+       * @param {number} [options.limit=50] - Items per page
+       * @param {string[]} [options.fields] - Fields to include in response
+       * @returns {Promise<Object>} Paginated search results
+       */
+      search: async (query, options = {}) => {
+        const params = {
+          q: query,
+          page: options.page || 1,
+          limit: options.limit || 50,
+        };
+
+        // Add field selection if provided
+        if (options.fields && Array.isArray(options.fields) && options.fields.length > 0) {
+          params.fields = options.fields.join(',');
+        }
+
+        const response = await self._httpClient.get('/users/search', params);
+        return {
+          ...response.data,
+          users: (response.data.users || []).map(user => self._parseUserProfile(user)),
+        };
+      },
+
+      /**
+       * Get multiple user profiles
+       * @param {string[]} userIds - Array of user IDs
+       * @returns {Promise<Object>} Bulk users response
+       */
+      getBulk: async (userIds) => {
+        const response = await self._httpClient.post('/users/bulk', { user_ids: userIds });
+        return {
+          ...response.data,
+          users: (response.data.users || []).map(user => self._parseUserProfile(user)),
+        };
+      },
+
+      /**
+       * Get user badges
+       * @param {string} userId - User ID
+       * @returns {Promise<Object[]>} User badges
+       */
+      getBadges: async (userId) => {
+        const response = await self._httpClient.get(`/users/${encodeURIComponent(userId)}/badges`);
+        return response.data;
+      },
+
+      /**
+       * Get user rank
+       * @param {string} userId - User ID
+       * @param {string} [timeframe='all-time'] - Timeframe for ranking
+       * @returns {Promise<Object>} User rank info
+       */
+      getRank: async (userId, timeframe = 'all-time') => {
+        const response = await self._httpClient.get(
+          `/users/${encodeURIComponent(userId)}/rank`,
+          { timeframe }
+        );
+        return response.data;
+      },
+
+      /**
+       * Submit questionnaire answers
+       * @param {string} userId - User ID
+       * @param {string} questionnaireId - Questionnaire ID
+       * @param {Object[]} answers - Array of answers
+       * @returns {Promise<Object>} Submission response
+       */
+      submitAnswers: async (userId, questionnaireId, answers) => {
+        const response = await self._httpClient.post(
+          `/users/${encodeURIComponent(userId)}/answers`,
+          {
+            questionnaire_id: questionnaireId,
+            answers,
+          }
+        );
+        return response.data;
+      },
     };
   }
 
+  /**
+   * Parse user profile to include activity summary, streak, and inventory
+   * @private
+   * @param {Object} profile - Raw user profile from API
+   * @returns {Object} Parsed user profile
+   */
+  _parseUserProfile(profile) {
+    if (!profile) return profile;
+
+    const parsed = { ...profile };
+
+    // Parse activity summary if present
+    if (profile.activity_summary) {
+      parsed.activitySummary = {
+        lastEventAt: profile.activity_summary.last_event_at 
+          ? new Date(profile.activity_summary.last_event_at) 
+          : null,
+        eventCount: profile.activity_summary.event_count || 0,
+        daysActive: profile.activity_summary.days_active || 0,
+      };
+    }
+
+    // Parse streak info if present
+    if (profile.streak) {
+      parsed.streak = {
+        currentStreak: profile.streak.current_streak || 0,
+        longestStreak: profile.streak.longest_streak || 0,
+        lastActivityAt: profile.streak.last_activity_at 
+          ? new Date(profile.streak.last_activity_at) 
+          : null,
+        streakStartedAt: profile.streak.streak_started_at 
+          ? new Date(profile.streak.streak_started_at) 
+          : null,
+      };
+    }
+
+    // Parse inventory summary if present
+    if (profile.inventory) {
+      parsed.inventory = {
+        itemCount: profile.inventory.item_count || 0,
+        activeEffects: profile.inventory.active_effects || [],
+      };
+    }
+
+    return parsed;
+  }
+
+  /**
+   * Leaderboards module for ranking queries
+   */
   get leaderboards() {
+    const self = this;
+
+    /**
+     * Build filter query parameters from options
+     * @private
+     * @param {Object} options - Filter options
+     * @returns {Object} Query parameters
+     */
+    const buildFilterParams = (options = {}) => {
+      const params = {};
+
+      // Pagination
+      if (options.page !== undefined) params.page = options.page;
+      if (options.limit !== undefined) params.limit = options.limit;
+      if (options.search !== undefined && options.search !== null) params.search = options.search;
+
+      // Persona filter
+      if (options.persona !== undefined && options.persona !== null) {
+        params.persona = options.persona;
+      }
+
+      // Level range filters
+      if (options.minLevel !== undefined && options.minLevel !== null) {
+        params.min_level = options.minLevel;
+      }
+      if (options.maxLevel !== undefined && options.maxLevel !== null) {
+        params.max_level = options.maxLevel;
+      }
+
+      // Date range filters (convert to ISO 8601)
+      if (options.startDate !== undefined && options.startDate !== null) {
+        const startDate = options.startDate instanceof Date 
+          ? options.startDate 
+          : new Date(options.startDate);
+        params.start_date = startDate.toISOString();
+      }
+      if (options.endDate !== undefined && options.endDate !== null) {
+        const endDate = options.endDate instanceof Date 
+          ? options.endDate 
+          : new Date(options.endDate);
+        params.end_date = endDate.toISOString();
+      }
+
+      // Timeframe
+      if (options.timeframe !== undefined) params.timeframe = options.timeframe;
+
+      return params;
+    };
+
+    /**
+     * Parse leaderboard response to include cache metadata and percentile ranks
+     * @private
+     * @param {Object} response - Raw API response
+     * @returns {Object} Parsed leaderboard response
+     */
+    const parseLeaderboardResponse = (response) => {
+      const parsed = { ...response };
+
+      // Parse cache metadata if present
+      if (response.cache_metadata || response.cacheMetadata) {
+        const cacheData = response.cache_metadata || response.cacheMetadata;
+        parsed.cacheMetadata = {
+          cachedAt: cacheData.cached_at ? new Date(cacheData.cached_at) : null,
+          ttl: cacheData.ttl || 0,
+        };
+        // Remove snake_case version
+        delete parsed.cache_metadata;
+      }
+
+      // Parse rankings to include percentile if present
+      if (parsed.rankings && Array.isArray(parsed.rankings)) {
+        parsed.rankings = parsed.rankings.map(entry => ({
+          ...entry,
+          percentile: entry.percentile !== undefined ? entry.percentile : null,
+        }));
+      }
+
+      return parsed;
+    };
+
     return {
-      getGlobal: (timeframe = 'all-time', page = 1, limit = 50) =>
-        this._request('/leaderboard', 'GET', null, { timeframe, page, limit }),
-        
-      list: (page = 1, limit = 50, search = null) =>
-        this._request('/leaderboards', 'GET', null, { page, limit, search }),
-        
-      getCustom: (leaderboardId, page = 1, limit = 50, search = null) =>
-        this._request(`/leaderboard/${encodeURIComponent(leaderboardId)}`, 'GET', null, { page, limit, search }),
+      /**
+       * Get global leaderboard with optional filters
+       * @param {string|Object} [timeframeOrOptions='all-time'] - Timeframe string or options object
+       * @param {number} [page=1] - Page number (deprecated, use options object)
+       * @param {number} [limit=50] - Items per page (deprecated, use options object)
+       * @param {Object} [options] - Additional filter options
+       * @param {string} [options.timeframe='all-time'] - Timeframe (all-time, weekly, monthly)
+       * @param {number} [options.page=1] - Page number
+       * @param {number} [options.limit=50] - Items per page
+       * @param {string} [options.persona] - Filter by persona
+       * @param {number} [options.minLevel] - Minimum level filter
+       * @param {number} [options.maxLevel] - Maximum level filter
+       * @param {Date|string} [options.startDate] - Start date filter (ISO 8601)
+       * @param {Date|string} [options.endDate] - End date filter (ISO 8601)
+       * @returns {Promise<Object>} Leaderboard response with rankings, stats, pagination, and cache metadata
+       */
+      getGlobal: async (timeframeOrOptions = 'all-time', page = 1, limit = 50, options = {}) => {
+        let params;
+
+        // Support both legacy signature and new options object
+        if (typeof timeframeOrOptions === 'object') {
+          // New signature: getGlobal(options)
+          params = buildFilterParams({
+            timeframe: 'all-time',
+            page: 1,
+            limit: 50,
+            ...timeframeOrOptions,
+          });
+        } else {
+          // Legacy signature: getGlobal(timeframe, page, limit, options)
+          params = buildFilterParams({
+            timeframe: timeframeOrOptions,
+            page,
+            limit,
+            ...options,
+          });
+        }
+
+        const response = await self._httpClient.get('/leaderboards/global', params);
+        return parseLeaderboardResponse(response.data);
+      },
+
+      /**
+       * List all leaderboards
+       * @param {number|Object} [pageOrOptions=1] - Page number or options object
+       * @param {number} [limit=50] - Items per page (deprecated, use options object)
+       * @param {string} [search=null] - Search query (deprecated, use options object)
+       * @returns {Promise<Object>} Leaderboards list
+       */
+      list: async (pageOrOptions = 1, limit = 50, search = null) => {
+        let params;
+
+        // Support both legacy signature and new options object
+        if (typeof pageOrOptions === 'object') {
+          params = {
+            page: pageOrOptions.page || 1,
+            limit: pageOrOptions.limit || 50,
+          };
+          if (pageOrOptions.search !== undefined && pageOrOptions.search !== null) {
+            params.search = pageOrOptions.search;
+          }
+        } else {
+          params = { page: pageOrOptions, limit };
+          if (search !== null) params.search = search;
+        }
+
+        const response = await self._httpClient.get('/leaderboards', params);
+        return response.data;
+      },
+
+      /**
+       * Get custom leaderboard with optional filters
+       * @param {string} leaderboardId - Leaderboard ID
+       * @param {number|Object} [pageOrOptions=1] - Page number or options object
+       * @param {number} [limit=50] - Items per page (deprecated, use options object)
+       * @param {string} [search=null] - Search query (deprecated, use options object)
+       * @param {Object} [options] - Additional filter options
+       * @param {number} [options.page=1] - Page number
+       * @param {number} [options.limit=50] - Items per page
+       * @param {string} [options.search] - Search query
+       * @param {string} [options.persona] - Filter by persona
+       * @param {number} [options.minLevel] - Minimum level filter
+       * @param {number} [options.maxLevel] - Maximum level filter
+       * @param {Date|string} [options.startDate] - Start date filter (ISO 8601)
+       * @param {Date|string} [options.endDate] - End date filter (ISO 8601)
+       * @returns {Promise<Object>} Leaderboard response with rankings, stats, pagination, and cache metadata
+       */
+      getCustom: async (leaderboardId, pageOrOptions = 1, limit = 50, search = null, options = {}) => {
+        let params;
+
+        // Support both legacy signature and new options object
+        if (typeof pageOrOptions === 'object') {
+          // New signature: getCustom(leaderboardId, options)
+          params = buildFilterParams({
+            page: 1,
+            limit: 50,
+            ...pageOrOptions,
+          });
+        } else {
+          // Legacy signature: getCustom(leaderboardId, page, limit, search, options)
+          params = buildFilterParams({
+            page: pageOrOptions,
+            limit,
+            search,
+            ...options,
+          });
+        }
+
+        const response = await self._httpClient.get(
+          `/leaderboards/${encodeURIComponent(leaderboardId)}`,
+          params
+        );
+        return parseLeaderboardResponse(response.data);
+      },
+
+      /**
+       * Get user rank in leaderboard
+       * @param {string} leaderboardId - Leaderboard ID
+       * @param {string} userId - User ID
+       * @returns {Promise<Object>} User rank response with rank, score, and percentile
+       */
+      getUserRank: async (leaderboardId, userId) => {
+        const response = await self._httpClient.get(
+          `/leaderboards/${encodeURIComponent(leaderboardId)}/users/${encodeURIComponent(userId)}/rank`
+        );
         
-      getUserRank: (leaderboardId, userId) =>
-        this._request(`/leaderboard/${encodeURIComponent(leaderboardId)}/user/${encodeURIComponent(userId)}/rank`),
+        // Include percentile in response if available
+        const data = response.data;
+        return {
+          ...data,
+          percentile: data.percentile !== undefined ? data.percentile : null,
+        };
+      },
+
+      /**
+       * Get leaderboard entries around a specific user ("around me" view)
+       * @param {string} leaderboardId - Leaderboard ID
+       * @param {string} userId - User ID to center the view around
+       * @param {number} [range=5] - Number of entries above and below the user
+       * @returns {Promise<Object>} Leaderboard entries around the user with user's rank and percentile
+       */
+      getAroundUser: async (leaderboardId, userId, range = 5) => {
+        const response = await self._httpClient.get(
+          `/leaderboards/${encodeURIComponent(leaderboardId)}/users/${encodeURIComponent(userId)}/around`,
+          { range }
+        );
+        return parseLeaderboardResponse(response.data);
+      },
     };
   }
 
+  /**
+   * Badges module for badge queries
+   */
   get badges() {
     return {
-      list: (page = 1, limit = 50, activeOnly = false) =>
-        this._request('/badges', 'GET', null, { page, limit, active_only: activeOnly }),
+      /**
+       * List all badges
+       * @param {number} [page=1] - Page number
+       * @param {number} [limit=50] - Items per page
+       * @param {boolean} [activeOnly=false] - Only active badges
+       * @returns {Promise<Object>} Badges list
+       */
+      list: async (page = 1, limit = 50, activeOnly = false) => {
+        const response = await this._httpClient.get('/badges', {
+          page,
+          limit,
+          active_only: activeOnly,
+        });
+        return response.data;
+      },
     };
   }
 
+  /**
+   * Levels module for level queries
+   */
   get levels() {
     return {
-      list: (page = 1, limit = 50) =>
-        this._request('/levels', 'GET', null, { page, limit }),
+      /**
+       * List all levels
+       * @param {number} [page=1] - Page number
+       * @param {number} [limit=50] - Items per page
+       * @returns {Promise<Object>} Levels list
+       */
+      list: async (page = 1, limit = 50) => {
+        const response = await this._httpClient.get('/levels', { page, limit });
+        return response.data;
+      },
     };
   }
 
+  /**
+   * Questionnaires module for questionnaire queries
+   */
   get questionnaires() {
     return {
-      get: (slug) => this._request(`/questionnaire/${slug}`),
-      getActive: () => this._request('/questionnaire/active'),
+      /**
+       * Get questionnaire by slug
+       * @param {string} slug - Questionnaire slug
+       * @returns {Promise<Object>} Questionnaire data
+       */
+      get: async (slug) => {
+        const response = await this._httpClient.get(`/questionnaires/${slug}`);
+        return response.data;
+      },
+
+      /**
+       * Get active questionnaire
+       * @returns {Promise<Object>} Active questionnaire
+       */
+      getActive: async () => {
+        const response = await this._httpClient.get('/questionnaires/active');
+        return response.data;
+      },
     };
   }
 
+  /**
+   * Aha moment module for engagement tracking
+   */
   get aha() {
     return {
-      declare: (userId, value) => {
+      /**
+       * Declare aha moment score
+       * @param {string} userId - User ID
+       * @param {number} value - Score value (1-5)
+       * @returns {Promise<Object>} Declaration response
+       */
+      declare: async (userId, value) => {
         // Validate value is between 1 and 5
         if (!Number.isInteger(value) || value < 1 || value > 5) {
-          throw new Error('Aha score value must be an integer between 1 and 5');
+          throw new ValidationError('Aha score value must be an integer between 1 and 5', {
+            code: 'INVALID_AHA_VALUE',
+            fieldErrors: [{ field: 'value', message: 'value must be an integer between 1 and 5' }],
+          });
         }
-        return this._request('/aha/declare', 'POST', {
+        const response = await this._httpClient.post('/aha/declare', {
           user_id: userId,
           value,
         });
+        return response.data;
+      },
+
+      /**
+       * Get user aha score
+       * @param {string} userId - User ID
+       * @returns {Promise<Object>} User aha score
+       */
+      getUserScore: async (userId) => {
+        const response = await this._httpClient.get(`/users/${encodeURIComponent(userId)}/aha`);
+        return response.data;
+      },
+    };
+  }
+
+  /**
+   * Health module for API health checks
+   */
+  get health() {
+    return {
+      /**
+       * Check API health status
+       * @returns {Promise<Object>} Health status
+       */
+      check: async () => {
+        const response = await this._httpClient.get('/health');
+        return response.data;
       },
 
-      getUserScore: (userId) => this._request(`/users/${encodeURIComponent(userId)}/aha`),
+      /**
+       * Quick availability check
+       * @returns {Promise<boolean>} True if API is ready
+       */
+      isReady: async () => {
+        try {
+          await this._httpClient.get('/health');
+          return true;
+        } catch {
+          return false;
+        }
+      },
     };
   }
 }
 
+// Export error classes for external use
+export {
+  RooguysError,
+  ValidationError,
+  AuthenticationError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  RateLimitError,
+  ServerError,
+  mapStatusToError,
+};
+
+// Export utility functions
+export { extractRateLimitInfo, extractRequestId, parseResponseBody };
+
+// Export HttpClient for advanced usage
+export { HttpClient };
+
+// Default export
 export default Rooguys;