v1.3.0 - Rate Limiting & Throttling

What's New

Port of the PHP core v1.3.0 rate limiting architecture to Node.js, bringing the SDK to feature parity.

Rate Limiting & Throttling

• SlidingWindowRateLimiter: Proactive request throttling with a rolling 60-second window. Blocks requests when capacity is reached, preventing 429 errors before they happen.
• 429 Retry Logic: Automatic retry on HTTP 429 responses with Retry-After header support (configurable max retries, default: 3).
• Rate Limit Header Tracking: Automatic extraction and storage of X-RateLimit-Limit and X-RateLimit-Remaining from every API response.
• Adaptive Polling: fetchResults() scales up polling intervals when remaining requests are low, reducing pressure on the API.

New Classes

• SlidingWindowRateLimiter -- standalone rate limiter, zero dependencies
• SharpApiError -- custom error class extending Error with statusCode property (408 for timeout, 429 for rate limit)

New Methods on SharpApiCoreService

• extractRateLimitHeaders(response) -- parse X-RateLimit-* headers
• adjustIntervalForRateLimit(baseInterval) -- adaptive polling scaling
• executeWithRateLimitRetry(method, url, options) -- throttle + 429 retry wrapper
• makeGetRequest(url, queryParams) -- GET convenience method
• getRateLimitState() / setRateLimitState(state) -- external cache support
• canMakeRequest() -- check if remaining > 0
• Getters/setters for all configurable properties

Bug Fixes

• Fixed parseInt radix bug in fetchResults(): parseInt(header, 5) changed to parseInt(header, 10)
• fetchResults() now throws SharpApiError on timeout instead of silently returning (matches PHP behavior)

DTO Updates

• SharpApiSubscriptionInfo now includes current_subscription_reset (Date or null) and requests_per_minute (number or null) -- both backward-compatible with null defaults

Behavior Changes

• ping() and quota() bypass proactive throttling (lightweight health/info endpoints)
• quota() auto-adapts requestsPerMinute from server response when available

Backward Compatibility

• Constructor signature unchanged (3 params, same positions)
• makeRequest(method, url, data, filePath) signature unchanged
• All 30 specialized packages work without any changes

Tests

• 42 unit tests covering all new functionality
• SlidingWindowRateLimiter: 8 tests
• SharpApiCoreService: 34 tests (header extraction, 429 retry, adaptive polling, throttle bypass, getter/setter round-trips, backward compatibility)