Add rate limiting, throttling, and 429 retry logic (v1.3.0)

Port PHP core v1.3.0 rate limiting architecture to Node.js:
- SlidingWindowRateLimiter: proactive request throttling with rolling 60s window
- SharpApiError: custom error class with HTTP status code
- executeWithRateLimitRetry: 429 retry loop with configurable max retries
- extractRateLimitHeaders: X-RateLimit-Limit/Remaining tracking
- adjustIntervalForRateLimit: adaptive polling when rate limit is low
- ping/quota bypass throttling; quota adapts RPM from server response
- Fix parseInt radix bug in fetchResults (5 → 10)
- fetchResults now throws SharpApiError on timeout instead of silently returning
- Add current_subscription_reset and requests_per_minute to SubscriptionInfo DTO
- 42 unit tests covering all new functionality

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: makowskid

__tests__/SharpApiCoreService.test.js

@@ -0,0 +1,84 @@
+const { SlidingWindowRateLimiter } = require('../src/SlidingWindowRateLimiter');
+
+describe('SlidingWindowRateLimiter', () => {
+  test('constructor sets default values', () => {
+    const limiter = new SlidingWindowRateLimiter();
+    expect(limiter.getMaxRequests()).toBe(60);
+    expect(limiter.getWindowSeconds()).toBe(60);
+  });
+
+  test('constructor accepts custom values', () => {
+    const limiter = new SlidingWindowRateLimiter(10, 30);
+    expect(limiter.getMaxRequests()).toBe(10);
+    expect(limiter.getWindowSeconds()).toBe(30);
+  });
+
+  test('canProceed returns true when under limit', () => {
+    const limiter = new SlidingWindowRateLimiter(5, 60);
+    expect(limiter.canProceed()).toBe(true);
+  });
+
+  test('canProceed returns false when at limit', async () => {
+    const limiter = new SlidingWindowRateLimiter(2, 60);
+    await limiter.waitIfNeeded();
+    await limiter.waitIfNeeded();
+    expect(limiter.canProceed()).toBe(false);
+  });
+
+  test('remaining counts correctly', async () => {
+    const limiter = new SlidingWindowRateLimiter(5, 60);
+    expect(limiter.remaining()).toBe(5);
+
+    await limiter.waitIfNeeded();
+    expect(limiter.remaining()).toBe(4);
+
+    await limiter.waitIfNeeded();
+    expect(limiter.remaining()).toBe(3);
+  });
+
+  test('waitIfNeeded returns 0 when capacity available', async () => {
+    const limiter = new SlidingWindowRateLimiter(5, 60);
+    const waited = await limiter.waitIfNeeded();
+    expect(waited).toBe(0);
+  });
+
+  test('adaptFromServerLimit ratchets up only', () => {
+    const limiter = new SlidingWindowRateLimiter(10, 60);
+
+    // Should increase
+    limiter.adaptFromServerLimit(20);
+    expect(limiter.getMaxRequests()).toBe(20);
+
+    // Should NOT decrease
+    limiter.adaptFromServerLimit(5);
+    expect(limiter.getMaxRequests()).toBe(20);
+
+    // Ignores non-numbers
+    limiter.adaptFromServerLimit(null);
+    expect(limiter.getMaxRequests()).toBe(20);
+
+    limiter.adaptFromServerLimit(undefined);
+    expect(limiter.getMaxRequests()).toBe(20);
+  });
+
+  test('setMaxRequests / getMaxRequests round-trip', () => {
+    const limiter = new SlidingWindowRateLimiter(10, 60);
+    limiter.setMaxRequests(100);
+    expect(limiter.getMaxRequests()).toBe(100);
+  });
+
+  test('expired timestamps are pruned', async () => {
+    // Use a very short window for testing
+    const limiter = new SlidingWindowRateLimiter(2, 0.1); // 100ms window
+
+    await limiter.waitIfNeeded();
+    await limiter.waitIfNeeded();
+    expect(limiter.canProceed()).toBe(false);
+
+    // Wait for the window to expire
+    await new Promise((resolve) => setTimeout(resolve, 150));
+
+    expect(limiter.canProceed()).toBe(true);
+    expect(limiter.remaining()).toBe(2);
+  });
+});

__tests__/SlidingWindowRateLimiter.test.js

@@ -1,6 +1,6 @@
 {
   "name": "@sharpapi/sharpapi-node-core",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "description": "SharpAPI.com Node.js SDK Core - Shared functionality for SharpAPI clients",
   "main": "src/index.js",
   "scripts": {

package.json

@@ -9,19 +9,23 @@ class SharpApiSubscriptionInfo {
     subscribed,
     current_subscription_start,
     current_subscription_end,
+    current_subscription_reset = null,
     subscription_words_quota,
     subscription_words_used,
     subscription_words_used_percentage,
+    requests_per_minute = null,
   }) {
     this.timestamp = new Date(timestamp);
     this.on_trial = on_trial;
     this.trial_ends = new Date(trial_ends);
     this.subscribed = subscribed;
     this.current_subscription_start = new Date(current_subscription_start);
     this.current_subscription_end = new Date(current_subscription_end);
+    this.current_subscription_reset = current_subscription_reset ? new Date(current_subscription_reset) : null;
     this.subscription_words_quota = subscription_words_quota;
     this.subscription_words_used = subscription_words_used;
     this.subscription_words_used_percentage = subscription_words_used_percentage;
+    this.requests_per_minute = requests_per_minute;
   }
 
   toJSON() {
@@ -32,11 +36,13 @@ class SharpApiSubscriptionInfo {
       subscribed: this.subscribed,
       current_subscription_start: this.current_subscription_start,
       current_subscription_end: this.current_subscription_end,
+      current_subscription_reset: this.current_subscription_reset,
       subscription_words_quota: this.subscription_words_quota,
       subscription_words_used: this.subscription_words_used,
       subscription_words_used_percentage: this.subscription_words_used_percentage,
+      requests_per_minute: this.requests_per_minute,
     };
   }
 }
 
-module.exports = { SharpApiSubscriptionInfo };
+module.exports = { SharpApiSubscriptionInfo };

src/Dto/SharpApiSubscriptionInfo.js

@@ -84,6 +84,11 @@ class SharpApiJobTypeEnum {
     url: '/content/detect_profanities',
   };
 
+  static CONTENT_DETECT_AI = {
+    value: 'content_detect_ai',
+    url: '/content/detect_ai',
+  };
+
   static CONTENT_SUMMARIZE = {
     value: 'content_summarize',
     url: '/content/summarize',

src/Enums/SharpApiJobTypeEnum.js

@@ -0,0 +1,19 @@
+/**
+ * SharpAPI Error
+ *
+ * Custom error class that carries an HTTP status code.
+ * Mirrors PHP's ApiException from sharpapi/php-core.
+ */
+class SharpApiError extends Error {
+  /**
+   * @param {string} message - Error message.
+   * @param {number|null} statusCode - HTTP status code (e.g. 429, 408).
+   */
+  constructor(message, statusCode = null) {
+    super(message);
+    this.name = 'SharpApiError';
+    this.statusCode = statusCode;
+  }
+}
+
+module.exports = { SharpApiError };