@profplum700/etsy-v3-api-client 2.3.17 → 2.4.0

package/dist/node.esm.js

@@ -234,14 +234,18 @@ class EtsyAuthError extends Error {
     }
 }
 class EtsyRateLimitError extends Error {
-    constructor(message, _retryAfter) {
+    constructor(message, _retryAfter, errorType = 'unknown') {
         super(message);
         this._retryAfter = _retryAfter;
         this.name = 'EtsyRateLimitError';
+        this.errorType = errorType;
     }
     get retryAfter() {
         return this._retryAfter;
     }
+    isRetryable() {
+        return this.errorType !== 'qpd_exhausted';
+    }
 }
 
 const isBrowser$1 = typeof window !== 'undefined' && typeof window.document !== 'undefined';
@@ -674,10 +678,18 @@ class EtsyRateLimiter {
         this.requestCount = 0;
         this.dailyReset = new Date();
         this.lastRequestTime = 0;
+        this.isHeaderBasedLimiting = false;
+        this.currentRetryCount = 0;
         this.config = {
             maxRequestsPerDay: 10000,
             maxRequestsPerSecond: 10,
             minRequestInterval: 100,
+            maxRetries: 3,
+            baseDelayMs: 1000,
+            maxDelayMs: 30000,
+            jitter: 0.1,
+            qpdWarningThreshold: 80,
+            onApproachingLimit: undefined,
             ...config
         };
         this.setNextDailyReset();
@@ -688,19 +700,124 @@ class EtsyRateLimiter {
         this.dailyReset.setUTCDate(this.dailyReset.getUTCDate() + 1);
         this.dailyReset.setUTCHours(0, 0, 0, 0);
     }
+    updateFromHeaders(headers) {
+        if (!headers) {
+            return;
+        }
+        const parsed = this.parseRateLimitHeaders(headers);
+        if (parsed.limitPerSecond !== undefined) {
+            this.headerLimitPerSecond = parsed.limitPerSecond;
+            this.isHeaderBasedLimiting = true;
+        }
+        if (parsed.remainingThisSecond !== undefined) {
+            this.headerRemainingThisSecond = parsed.remainingThisSecond;
+        }
+        if (parsed.limitPerDay !== undefined) {
+            this.headerLimitPerDay = parsed.limitPerDay;
+            this.isHeaderBasedLimiting = true;
+        }
+        if (parsed.remainingToday !== undefined) {
+            this.headerRemainingToday = parsed.remainingToday;
+            this.checkApproachingLimit();
+        }
+    }
+    parseRateLimitHeaders(headers) {
+        const getHeader = (name) => {
+            if (headers instanceof Headers) {
+                return headers.get(name);
+            }
+            const lowerName = name.toLowerCase();
+            for (const key of Object.keys(headers)) {
+                if (key.toLowerCase() === lowerName) {
+                    return headers[key] ?? null;
+                }
+            }
+            return null;
+        };
+        const parseNumber = (value) => {
+            if (value === null)
+                return undefined;
+            const num = parseInt(value, 10);
+            return isNaN(num) ? undefined : num;
+        };
+        return {
+            limitPerSecond: parseNumber(getHeader('x-limit-per-second')),
+            remainingThisSecond: parseNumber(getHeader('x-remaining-this-second')),
+            limitPerDay: parseNumber(getHeader('x-limit-per-day')),
+            remainingToday: parseNumber(getHeader('x-remaining-today')),
+            retryAfter: parseNumber(getHeader('retry-after'))
+        };
+    }
+    checkApproachingLimit() {
+        if (!this.config.onApproachingLimit)
+            return;
+        const limit = this.headerLimitPerDay ?? this.config.maxRequestsPerDay;
+        const remaining = this.headerRemainingToday ?? this.getRemainingRequests();
+        const used = limit - remaining;
+        const percentageUsed = (used / limit) * 100;
+        if (percentageUsed >= this.config.qpdWarningThreshold) {
+            this.config.onApproachingLimit(remaining, limit, percentageUsed);
+        }
+    }
+    async handleRateLimitResponse(headers) {
+        const parsed = headers ? this.parseRateLimitHeaders(headers) : {};
+        this.updateFromHeaders(headers);
+        if (this.headerRemainingToday === 0) {
+            throw new EtsyRateLimitError('Daily rate limit exhausted. No requests remaining until limit resets.', parsed.retryAfter, 'qpd_exhausted');
+        }
+        this.currentRetryCount++;
+        if (this.currentRetryCount > this.config.maxRetries) {
+            this.currentRetryCount = 0;
+            throw new EtsyRateLimitError(`Max retries (${this.config.maxRetries}) exceeded for rate limit`, parsed.retryAfter, 'qps_exhausted');
+        }
+        const delayMs = this.calculateBackoffDelay(this.currentRetryCount, parsed.retryAfter);
+        return { shouldRetry: true, delayMs };
+    }
+    calculateBackoffDelay(attempt, retryAfterSeconds) {
+        const serverSuggestedMs = retryAfterSeconds ? retryAfterSeconds * 1000 : 0;
+        const exponentialDelay = this.config.baseDelayMs * Math.pow(2, attempt - 1);
+        let delay = Math.min(exponentialDelay, this.config.maxDelayMs);
+        delay = Math.max(delay, serverSuggestedMs);
+        if (this.config.jitter > 0) {
+            const jitterAmount = delay * this.config.jitter;
+            const randomJitter = Math.random() * jitterAmount * 2 - jitterAmount;
+            delay += randomJitter;
+        }
+        return Math.max(0, Math.floor(delay));
+    }
+    resetRetryCount() {
+        this.currentRetryCount = 0;
+    }
+    setApproachingLimitCallback(callback) {
+        this.config.onApproachingLimit = callback;
+    }
+    setWarningThreshold(threshold) {
+        this.config.qpdWarningThreshold = threshold;
+    }
+    getEffectiveMinInterval() {
+        if (this.headerLimitPerSecond !== undefined && this.headerLimitPerSecond > 0) {
+            return Math.ceil(1000 / this.headerLimitPerSecond);
+        }
+        return this.config.minRequestInterval;
+    }
     async waitForRateLimit() {
         const now = Date.now();
         if (now >= this.dailyReset.getTime()) {
             this.requestCount = 0;
             this.setNextDailyReset();
         }
-        if (this.requestCount >= this.config.maxRequestsPerDay) {
+        const effectiveDailyLimit = this.headerLimitPerDay ?? this.config.maxRequestsPerDay;
+        const effectiveRemaining = this.headerRemainingToday ??
+            (effectiveDailyLimit - this.requestCount);
+        if (effectiveRemaining <= 0) {
             const timeUntilReset = this.dailyReset.getTime() - now;
-            throw new EtsyRateLimitError(`Daily rate limit of ${this.config.maxRequestsPerDay} requests exceeded. Reset in ${Math.ceil(timeUntilReset / 1000 / 60)} minutes.`, timeUntilReset);
+            throw new EtsyRateLimitError(`Daily rate limit exhausted (${effectiveDailyLimit} requests). ` +
+                `Reset in approximately ${Math.ceil(timeUntilReset / 1000 / 60)} minutes.`, Math.ceil(timeUntilReset / 1000), 'qpd_exhausted');
         }
+        const minInterval = this.getEffectiveMinInterval();
         const timeSinceLastRequest = now - this.lastRequestTime;
-        if (timeSinceLastRequest < this.config.minRequestInterval) {
-            const waitTime = this.config.minRequestInterval - timeSinceLastRequest;
+        if (timeSinceLastRequest < minInterval) {
+            const waitTime = minInterval - timeSinceLastRequest;
             await new Promise(resolve => setTimeout(resolve, waitTime));
         }
         this.requestCount++;
@@ -712,19 +829,32 @@ class EtsyRateLimiter {
             this.requestCount = 0;
             this.setNextDailyReset();
         }
+        const effectiveRemaining = this.headerRemainingToday ??
+            Math.max(0, this.config.maxRequestsPerDay - this.requestCount);
         return {
-            remainingRequests: Math.max(0, this.config.maxRequestsPerDay - this.requestCount),
+            remainingRequests: effectiveRemaining,
             resetTime: this.dailyReset,
-            canMakeRequest: this.requestCount < this.config.maxRequestsPerDay &&
-                (now - this.lastRequestTime) >= this.config.minRequestInterval
+            canMakeRequest: effectiveRemaining > 0 &&
+                (now - this.lastRequestTime) >= this.getEffectiveMinInterval(),
+            isFromHeaders: this.isHeaderBasedLimiting,
+            limitPerSecond: this.headerLimitPerSecond,
+            remainingThisSecond: this.headerRemainingThisSecond,
+            limitPerDay: this.headerLimitPerDay
         };
     }
     getRemainingRequests() {
-        return Math.max(0, this.config.maxRequestsPerDay - this.requestCount);
+        return this.headerRemainingToday ??
+            Math.max(0, this.config.maxRequestsPerDay - this.requestCount);
     }
     reset() {
         this.requestCount = 0;
         this.lastRequestTime = 0;
+        this.currentRetryCount = 0;
+        this.headerLimitPerSecond = undefined;
+        this.headerRemainingThisSecond = undefined;
+        this.headerLimitPerDay = undefined;
+        this.headerRemainingToday = undefined;
+        this.isHeaderBasedLimiting = false;
         this.setNextDailyReset();
     }
     canMakeRequest() {
@@ -733,18 +863,21 @@ class EtsyRateLimiter {
             this.requestCount = 0;
             this.setNextDailyReset();
         }
-        if (this.requestCount >= this.config.maxRequestsPerDay) {
+        const effectiveRemaining = this.headerRemainingToday ??
+            (this.config.maxRequestsPerDay - this.requestCount);
+        if (effectiveRemaining <= 0) {
             return false;
         }
-        return (now - this.lastRequestTime) >= this.config.minRequestInterval;
+        return (now - this.lastRequestTime) >= this.getEffectiveMinInterval();
     }
     getTimeUntilNextRequest() {
         const now = Date.now();
         const timeSinceLastRequest = now - this.lastRequestTime;
-        if (timeSinceLastRequest >= this.config.minRequestInterval) {
+        const minInterval = this.getEffectiveMinInterval();
+        if (timeSinceLastRequest >= minInterval) {
             return 0;
         }
-        return this.config.minRequestInterval - timeSinceLastRequest;
+        return minInterval - timeSinceLastRequest;
     }
     getConfig() {
         return { ...this.config };
@@ -1208,7 +1341,13 @@ class EtsyClient {
             this.rateLimiter = new EtsyRateLimiter({
                 maxRequestsPerDay: config.rateLimiting?.maxRequestsPerDay || 10000,
                 maxRequestsPerSecond: config.rateLimiting?.maxRequestsPerSecond || 10,
-                minRequestInterval: config.rateLimiting?.minRequestInterval ?? 100
+                minRequestInterval: config.rateLimiting?.minRequestInterval ?? 100,
+                maxRetries: config.rateLimiting?.maxRetries,
+                baseDelayMs: config.rateLimiting?.baseDelayMs,
+                maxDelayMs: config.rateLimiting?.maxDelayMs,
+                jitter: config.rateLimiting?.jitter,
+                qpdWarningThreshold: config.rateLimiting?.qpdWarningThreshold,
+                onApproachingLimit: config.rateLimiting?.onApproachingLimit
             });
         }
         else {
@@ -1245,35 +1384,53 @@ class EtsyClient {
             'Accept': 'application/json',
             ...requestOptions.headers
         };
-        try {
-            const response = await this.fetch(url, {
-                ...requestOptions,
-                headers
-            });
-            if (!response.ok) {
-                const errorText = await response.text();
-                throw new EtsyApiError(`Etsy API error: ${response.status} ${response.statusText}`, response.status, errorText);
-            }
-            if (response.status === 204) {
-                return undefined;
-            }
-            const contentLength = response.headers?.get?.('content-length');
-            if (contentLength === '0') {
-                return undefined;
-            }
-            const data = await response.json();
-            if (useCache && this.cache && requestOptions.method === 'GET') {
-                await this.cache.set(cacheKey, JSON.stringify(data), this.cacheTtl);
+        return this.executeWithRetry(url, { ...requestOptions, headers }, cacheKey, useCache);
+    }
+    async executeWithRetry(url, options, cacheKey, useCache) {
+        while (true) {
+            try {
+                const response = await this.fetch(url, options);
+                if (response.status === 429) {
+                    const { shouldRetry, delayMs } = await this.rateLimiter.handleRateLimitResponse(response.headers);
+                    if (shouldRetry) {
+                        this.logger.warn(`Rate limited. Retrying in ${delayMs}ms...`);
+                        await this.sleep(delayMs);
+                        continue;
+                    }
+                }
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    throw new EtsyApiError(`Etsy API error: ${response.status} ${response.statusText}`, response.status, errorText);
+                }
+                this.rateLimiter.updateFromHeaders(response.headers);
+                this.rateLimiter.resetRetryCount();
+                if (response.status === 204) {
+                    return undefined;
+                }
+                const contentLength = response.headers?.get?.('content-length');
+                if (contentLength === '0') {
+                    return undefined;
+                }
+                const data = await response.json();
+                if (useCache && this.cache && options.method === 'GET') {
+                    await this.cache.set(cacheKey, JSON.stringify(data), this.cacheTtl);
+                }
+                return data;
             }
-            return data;
-        }
-        catch (error) {
-            if (error instanceof EtsyApiError || error instanceof EtsyAuthError) {
-                throw error;
+            catch (error) {
+                if (error instanceof EtsyRateLimitError) {
+                    throw error;
+                }
+                if (error instanceof EtsyApiError || error instanceof EtsyAuthError) {
+                    throw error;
+                }
+                throw new EtsyApiError(`Request failed: ${error instanceof Error ? error.message : 'Unknown error'}`, 0, error);
             }
-            throw new EtsyApiError(`Request failed: ${error instanceof Error ? error.message : 'Unknown error'}`, 0, error);
         }
     }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
     getApiKey() {
         if (this.sharedSecret) {
             return `${this.keystring}:${this.sharedSecret}`;
@@ -1652,6 +1809,12 @@ class EtsyClient {
     getRateLimitStatus() {
         return this.rateLimiter.getRateLimitStatus();
     }
+    onApproachingRateLimit(callback, threshold) {
+        if (threshold !== undefined) {
+            this.rateLimiter.setWarningThreshold(threshold);
+        }
+        this.rateLimiter.setApproachingLimitCallback(callback);
+    }
     async clearCache() {
         if (this.cache) {
             await this.cache.clear();