@rooguys/js 0.1.0 → 1.0.0

package/src/http-client.js

@@ -0,0 +1,276 @@
+/**
+ * Rooguys SDK HTTP Client
+ * Handles standardized response format, rate limit headers, and error mapping
+ */
+
+import { mapStatusToError, RooguysError, RateLimitError } from './errors.js';
+
+/**
+ * Rate limit information extracted from response headers
+ * @typedef {Object} RateLimitInfo
+ * @property {number} limit - Maximum requests allowed
+ * @property {number} remaining - Remaining requests in window
+ * @property {number} reset - Unix timestamp when limit resets
+ */
+
+/**
+ * API response wrapper with metadata
+ * @typedef {Object} ApiResponse
+ * @property {*} data - Response data
+ * @property {string} requestId - Request ID for debugging
+ * @property {RateLimitInfo} rateLimit - Rate limit information
+ * @property {Object} [pagination] - Pagination info if present
+ */
+
+/**
+ * Extract rate limit information from response headers
+ * @param {Headers|Object} headers - Response headers
+ * @returns {RateLimitInfo} Rate limit info
+ */
+export function extractRateLimitInfo(headers) {
+  // Handle both Headers object and plain object
+  const getHeader = (name) => {
+    if (typeof headers.get === 'function') {
+      return headers.get(name);
+    }
+    return headers[name] || headers[name.toLowerCase()];
+  };
+
+  return {
+    limit: parseInt(getHeader('X-RateLimit-Limit') || getHeader('x-ratelimit-limit') || '1000', 10),
+    remaining: parseInt(getHeader('X-RateLimit-Remaining') || getHeader('x-ratelimit-remaining') || '1000', 10),
+    reset: parseInt(getHeader('X-RateLimit-Reset') || getHeader('x-ratelimit-reset') || '0', 10),
+  };
+}
+
+/**
+ * Extract request ID from response headers or body
+ * @param {Headers|Object} headers - Response headers
+ * @param {Object} body - Response body
+ * @returns {string|null} Request ID
+ */
+export function extractRequestId(headers, body) {
+  // Try headers first
+  const getHeader = (name) => {
+    if (typeof headers.get === 'function') {
+      return headers.get(name);
+    }
+    return headers[name] || headers[name.toLowerCase()];
+  };
+
+  const headerRequestId = getHeader('X-Request-Id') || getHeader('x-request-id');
+  if (headerRequestId) {
+    return headerRequestId;
+  }
+
+  // Fall back to body
+  return body?.request_id || body?.requestId || null;
+}
+
+/**
+ * Parse standardized API response format
+ * Handles both new format { success: true, data: {...} } and legacy format
+ * @param {Object} body - Response body
+ * @returns {Object} Parsed response with data and metadata
+ */
+export function parseResponseBody(body) {
+  // New standardized format
+  if (body && typeof body.success === 'boolean') {
+    if (body.success) {
+      return {
+        data: body.data,
+        pagination: body.pagination || null,
+        requestId: body.request_id || null,
+      };
+    }
+    // Error response in standardized format
+    return {
+      error: body.error,
+      requestId: body.request_id || null,
+    };
+  }
+
+  // Legacy format - return as-is
+  return {
+    data: body,
+    pagination: body?.pagination || null,
+    requestId: null,
+  };
+}
+
+/**
+ * HTTP Client class for making API requests
+ */
+export class HttpClient {
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey;
+    this.baseUrl = options.baseUrl || 'https://api.rooguys.com/v1';
+    this.timeout = options.timeout || 10000;
+    this.defaultHeaders = {
+      'x-api-key': apiKey,
+      'Content-Type': 'application/json',
+    };
+    this.onRateLimitWarning = options.onRateLimitWarning || null;
+    
+    // Auto-retry configuration for rate-limited requests
+    this.autoRetry = options.autoRetry || false;
+    this.maxRetries = options.maxRetries || 3;
+    this.retryDelay = options.retryDelay || 1000; // Base delay in ms
+  }
+
+  /**
+   * Sleep for a specified duration
+   * @param {number} ms - Milliseconds to sleep
+   * @returns {Promise<void>}
+   */
+  _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Make an HTTP request with optional auto-retry for rate limits
+   * @param {Object} config - Request configuration
+   * @param {string} config.method - HTTP method
+   * @param {string} config.path - API endpoint path
+   * @param {Object} [config.params] - Query parameters
+   * @param {Object} [config.body] - Request body
+   * @param {Object} [config.headers] - Additional headers
+   * @param {string} [config.idempotencyKey] - Idempotency key for POST requests
+   * @param {number} [retryCount=0] - Current retry attempt (internal use)
+   * @returns {Promise<ApiResponse>} API response with data and metadata
+   */
+  async request(config, retryCount = 0) {
+    const { method = 'GET', path, params = {}, body = null, headers = {}, idempotencyKey = null } = config;
+
+    // Build URL with query parameters
+    const url = new URL(`${this.baseUrl}${path}`);
+    Object.keys(params).forEach(key => {
+      if (params[key] !== undefined && params[key] !== null) {
+        url.searchParams.append(key, params[key]);
+      }
+    });
+
+    // Build request headers
+    const requestHeaders = {
+      ...this.defaultHeaders,
+      ...headers,
+    };
+
+    // Add idempotency key if provided
+    if (idempotencyKey) {
+      requestHeaders['X-Idempotency-Key'] = idempotencyKey;
+    }
+
+    // Build fetch config
+    const fetchConfig = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body) {
+      fetchConfig.body = JSON.stringify(body);
+    }
+
+    try {
+      // Setup timeout
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      fetchConfig.signal = controller.signal;
+
+      // Make request
+      const response = await fetch(url.toString(), fetchConfig);
+      clearTimeout(timeoutId);
+
+      // Extract headers info
+      const rateLimit = extractRateLimitInfo(response.headers);
+      
+      // Check for rate limit warning (80% consumed)
+      if (rateLimit.remaining < rateLimit.limit * 0.2 && this.onRateLimitWarning) {
+        this.onRateLimitWarning(rateLimit);
+      }
+
+      // Parse response body
+      const responseBody = await response.json().catch(() => ({}));
+      const requestId = extractRequestId(response.headers, responseBody);
+
+      // Handle error responses
+      if (!response.ok) {
+        const error = mapStatusToError(response.status, responseBody, requestId, {
+          'retry-after': response.headers.get('Retry-After'),
+        });
+
+        // Auto-retry for rate limit errors if enabled
+        if (this.autoRetry && error instanceof RateLimitError && retryCount < this.maxRetries) {
+          const retryAfterMs = error.retryAfter * 1000;
+          await this._sleep(retryAfterMs);
+          return this.request(config, retryCount + 1);
+        }
+
+        throw error;
+      }
+
+      // Parse successful response
+      const parsed = parseResponseBody(responseBody);
+
+      // Check for error in standardized format
+      if (parsed.error) {
+        throw mapStatusToError(400, { error: parsed.error }, requestId, {});
+      }
+
+      return {
+        data: parsed.data,
+        requestId: requestId || parsed.requestId,
+        rateLimit,
+        pagination: parsed.pagination,
+      };
+    } catch (error) {
+      // Re-throw RooguysError instances
+      if (error instanceof RooguysError) {
+        throw error;
+      }
+
+      // Handle abort/timeout
+      if (error.name === 'AbortError') {
+        throw new RooguysError('Request timeout', { code: 'TIMEOUT', statusCode: 408 });
+      }
+
+      // Handle network errors
+      throw new RooguysError(error.message || 'Network error', { code: 'NETWORK_ERROR', statusCode: 0 });
+    }
+  }
+
+  /**
+   * Convenience method for GET requests
+   */
+  get(path, params = {}, options = {}) {
+    return this.request({ method: 'GET', path, params, ...options });
+  }
+
+  /**
+   * Convenience method for POST requests
+   */
+  post(path, body = null, options = {}) {
+    return this.request({ method: 'POST', path, body, ...options });
+  }
+
+  /**
+   * Convenience method for PUT requests
+   */
+  put(path, body = null, options = {}) {
+    return this.request({ method: 'PUT', path, body, ...options });
+  }
+
+  /**
+   * Convenience method for PATCH requests
+   */
+  patch(path, body = null, options = {}) {
+    return this.request({ method: 'PATCH', path, body, ...options });
+  }
+
+  /**
+   * Convenience method for DELETE requests
+   */
+  delete(path, options = {}) {
+    return this.request({ method: 'DELETE', path, ...options });
+  }
+}