@profplum700/etsy-v3-api-client 3.0.0 → 4.0.0

package/dist/index.cjs

@@ -251,6 +251,26 @@ class EtsyRateLimitError extends Error {
         return this.errorType !== 'qpd_exhausted';
     }
 }
+const ETSY_WHEN_MADE_VALUES = [
+    '2020_2026',
+    '2010_2019',
+    '2007_2009',
+    'before_2007',
+    '2000_2006',
+    '1990s',
+    '1980s',
+    '1970s',
+    '1960s',
+    '1950s',
+    '1940s',
+    '1930s',
+    '1920s',
+    '1910s',
+    '1900s',
+    '1800s',
+    '1700s',
+    'before_1700'
+];
 
 const isBrowser$1 = typeof window !== 'undefined' && typeof window.document !== 'undefined';
 const isNode$1 = typeof process !== 'undefined' && !!process.versions?.node;
@@ -323,9 +343,12 @@ class MemoryTokenStorage {
 class TokenManager {
     constructor(config, storage, rotationConfig) {
         this.currentTokens = null;
+        this.tokenMutationGeneration = 0;
         this.keystring = config.keystring;
-        this.refreshCallback = config.refreshSave;
+        this.refreshCallback = config.refreshSaveAsync ?? config.refreshSave;
+        this.refreshClearRequired = config.refreshSaveAsync !== undefined;
         this.storage = storage;
+        this.clearCallback = config.refreshClearAsync;
         this.rotationConfig = rotationConfig;
         this.currentTokens = {
             access_token: config.accessToken,
@@ -362,21 +385,82 @@ class TokenManager {
         if (!this.currentTokens) {
             throw new EtsyAuthError('No tokens available to refresh', 'NO_REFRESH_TOKEN');
         }
-        this.refreshPromise = this.performTokenRefresh();
-        try {
-            const newTokens = await this.refreshPromise;
-            this.currentTokens = newTokens;
-            if (this.storage) {
-                await this.storage.save(newTokens);
+        const generation = this.tokenMutationGeneration;
+        const refreshPromise = (this.pendingTokens
+            ? this.retryPendingTokenPersistence()
+            : this.performTokenRefresh().then(async (newTokens) => {
+                this.throwIfSuperseded(generation);
+                this.pendingTokens = newTokens;
+                return this.persistRefreshedTokens(newTokens, generation);
+            })).finally(() => {
+            this.refreshPromise = undefined;
+        });
+        this.refreshPromise = refreshPromise;
+        return refreshPromise;
+    }
+    throwIfSuperseded(generation) {
+        if (generation !== this.tokenMutationGeneration) {
+            throw new EtsyAuthError('Token refresh was superseded by a token update or clear', 'TOKEN_REFRESH_SUPERSEDED');
+        }
+    }
+    async repairPersistenceToCurrentTokens() {
+        while (true) {
+            const generation = this.tokenMutationGeneration;
+            const current = this.currentTokens ? { ...this.currentTokens } : null;
+            try {
+                if (current) {
+                    if (this.storage)
+                        await this.storage.save(current);
+                    if (this.refreshCallback) {
+                        await this.refreshCallback(current.access_token, current.refresh_token, current.expires_at);
+                    }
+                }
+                else {
+                    if (this.storage)
+                        await this.storage.clear();
+                    if (this.clearCallback)
+                        await this.clearCallback();
+                    else if (this.refreshClearRequired) {
+                        throw new EtsyAuthError('A refresh persistence callback is configured without refreshClearAsync; durable tokens could not be cleared safely', 'TOKEN_CLEAR_CALLBACK_REQUIRED');
+                    }
+                }
+            }
+            catch (error) {
+                if (generation !== this.tokenMutationGeneration)
+                    continue;
+                throw error;
             }
-            if (this.refreshCallback) {
-                this.refreshCallback(newTokens.access_token, newTokens.refresh_token, newTokens.expires_at);
+            if (generation === this.tokenMutationGeneration)
+                return;
+        }
+    }
+    async persistRefreshedTokens(newTokens, generation) {
+        this.throwIfSuperseded(generation);
+        if (this.storage) {
+            await this.storage.save(newTokens);
+            if (generation !== this.tokenMutationGeneration) {
+                await this.repairPersistenceToCurrentTokens();
+                this.throwIfSuperseded(generation);
             }
-            return newTokens;
         }
-        finally {
-            this.refreshPromise = undefined;
+        this.throwIfSuperseded(generation);
+        if (this.refreshCallback) {
+            await this.refreshCallback(newTokens.access_token, newTokens.refresh_token, newTokens.expires_at);
+            if (generation !== this.tokenMutationGeneration) {
+                await this.repairPersistenceToCurrentTokens();
+                this.throwIfSuperseded(generation);
+            }
+        }
+        this.throwIfSuperseded(generation);
+        this.currentTokens = newTokens;
+        this.pendingTokens = undefined;
+        return newTokens;
+    }
+    async retryPendingTokenPersistence() {
+        if (!this.pendingTokens) {
+            throw new EtsyAuthError('No rotated tokens are pending persistence', 'NO_PENDING_TOKENS');
         }
+        return this.persistRefreshedTokens(this.pendingTokens, this.tokenMutationGeneration);
     }
     async performTokenRefresh() {
         if (!this.currentTokens) {
@@ -390,6 +474,7 @@ class TokenManager {
         try {
             const response = await this.fetch('https://api.etsy.com/v3/public/oauth/token', {
                 method: 'POST',
+                redirect: 'error',
                 headers: {
                     'Content-Type': 'application/x-www-form-urlencoded',
                     'Accept': 'application/json'
@@ -419,7 +504,9 @@ class TokenManager {
         return this.currentTokens ? { ...this.currentTokens } : null;
     }
     updateTokens(tokens) {
+        this.tokenMutationGeneration += 1;
         this.currentTokens = { ...tokens };
+        this.pendingTokens = undefined;
     }
     isTokenExpired() {
         if (!this.currentTokens) {
@@ -439,10 +526,19 @@ class TokenManager {
         return now.getTime() >= (expiresAt.getTime() - bufferTime);
     }
     async clearTokens() {
+        this.tokenMutationGeneration += 1;
         this.currentTokens = null;
+        this.pendingTokens = undefined;
+        if (this.refreshPromise)
+            await this.refreshPromise.catch(() => undefined);
         if (this.storage) {
             await this.storage.clear();
         }
+        if (this.clearCallback)
+            await this.clearCallback();
+        else if (this.refreshClearRequired) {
+            throw new EtsyAuthError('A refresh persistence callback is configured without refreshClearAsync; durable tokens could not be cleared safely', 'TOKEN_CLEAR_CALLBACK_REQUIRED');
+        }
     }
     getTimeUntilExpiration() {
         if (!this.currentTokens) {
@@ -682,13 +778,24 @@ const ETSY_RATE_LIMITS = {
     MAX_REQUESTS_PER_SECOND: 5,
     MIN_REQUEST_INTERVAL: 200,
 };
+const QPD_WINDOW_MS$1 = 24 * 60 * 60 * 1000;
 class EtsyRateLimiter {
     constructor(config) {
-        this.requestCount = 0;
-        this.dailyReset = new Date();
+        this.requestTimestamps = [];
+        this.uncertainRequestTimestamps = [];
         this.lastRequestTime = 0;
         this.isHeaderBasedLimiting = false;
+        this.headerQuotaAvailableAt = 0;
+        this.retryNotBefore = 0;
+        this.quotaProbeBackoffMs = 60000;
+        this.nextReservationId = 0;
+        this.latestHeaderReservationId = 0;
+        this.inFlightReservations = new Map();
+        this.quotaProbeInFlight = false;
+        this.stateWaiters = new Set();
         this.currentRetryCount = 0;
+        this.reservationQueue = Promise.resolve();
+        const overrides = Object.fromEntries(Object.entries(config ?? {}).filter(([, value]) => value !== undefined));
         this.config = {
             maxRequestsPerDay: ETSY_RATE_LIMITS.MAX_REQUESTS_PER_DAY,
             maxRequestsPerSecond: ETSY_RATE_LIMITS.MAX_REQUESTS_PER_SECOND,
@@ -699,21 +806,155 @@ class EtsyRateLimiter {
             jitter: 0.1,
             qpdWarningThreshold: 80,
             onApproachingLimit: undefined,
-            ...config
+            ...overrides
         };
-        this.setNextDailyReset();
     }
-    setNextDailyReset() {
-        const now = new Date();
-        this.dailyReset = new Date(now);
-        this.dailyReset.setUTCDate(this.dailyReset.getUTCDate() + 1);
-        this.dailyReset.setUTCHours(0, 0, 0, 0);
+    pruneRequestTimestamps(now) {
+        const oldestAllowed = now - QPD_WINDOW_MS$1;
+        while (this.requestTimestamps[0] !== undefined && this.requestTimestamps[0] <= oldestAllowed) {
+            this.requestTimestamps.shift();
+        }
+        while (this.uncertainRequestTimestamps[0] !== undefined && this.uncertainRequestTimestamps[0] <= oldestAllowed) {
+            this.uncertainRequestTimestamps.shift();
+        }
+    }
+    getLocalResetTime(now) {
+        this.pruneRequestTimestamps(now);
+        const oldestRequest = this.requestTimestamps[0] ?? now;
+        return new Date(oldestRequest + QPD_WINDOW_MS$1);
+    }
+    getLocalRemainingRequests(now) {
+        this.pruneRequestTimestamps(now);
+        const localLimit = this.headerLimitPerDay ?? this.config.maxRequestsPerDay;
+        return Math.max(0, localLimit - this.requestTimestamps.length);
+    }
+    getEffectiveRemainingRequests(now) {
+        this.pruneRequestTimestamps(now);
+        if (this.headerRemainingToday !== undefined) {
+            return Math.max(0, this.headerRemainingToday - this.inFlightReservations.size - this.uncertainRequestTimestamps.length);
+        }
+        return this.getLocalRemainingRequests(now);
+    }
+    isQuotaProbeReady(now) {
+        const exhausted = this.headerRemainingToday === 0;
+        const uncertainBudgetExhausted = this.inFlightReservations.size === 0 &&
+            this.uncertainRequestTimestamps.length > 0 &&
+            this.getEffectiveRemainingRequests(now) === 0;
+        return (exhausted || uncertainBudgetExhausted) &&
+            !this.quotaProbeInFlight &&
+            this.inFlightReservations.size === 0 &&
+            this.headerQuotaAvailableAt <= now;
+    }
+    refreshExpiredHeaderQuota(now) {
+        if (this.headerRemainingToday === 0 && this.headerQuotaAvailableAt > 0 && now >= this.headerQuotaAvailableAt) {
+            this.headerQuotaAvailableAt = 0;
+        }
+    }
+    notifyStateWaiters() {
+        for (const resolve of this.stateWaiters)
+            resolve();
+        this.stateWaiters.clear();
+    }
+    scheduleQuotaProbe() {
+        this.headerQuotaAvailableAt = Date.now() + this.quotaProbeBackoffMs;
+        this.quotaProbeBackoffMs = Math.min(this.quotaProbeBackoffMs * 2, 60 * 60 * 1000);
+    }
+    waitForStateChange() {
+        return new Promise((resolve) => this.stateWaiters.add(resolve));
+    }
+    finishReservation(reservationId, receivedQuotaHeader) {
+        const wasQuotaProbe = this.inFlightReservations.get(reservationId);
+        if (wasQuotaProbe === undefined)
+            return;
+        this.inFlightReservations.delete(reservationId);
+        if (wasQuotaProbe.isQuotaProbe) {
+            this.quotaProbeInFlight = false;
+            if (this.headerRemainingToday === 0 && !receivedQuotaHeader) {
+                this.scheduleQuotaProbe();
+            }
+        }
+        this.notifyStateWaiters();
+    }
+    async acquireRequestSlot() {
+        const previousReservation = this.reservationQueue;
+        let releaseReservation = () => undefined;
+        this.reservationQueue = new Promise((resolve) => {
+            releaseReservation = resolve;
+        });
+        await previousReservation;
+        try {
+            while (true) {
+                const now = Date.now();
+                this.pruneRequestTimestamps(now);
+                this.refreshExpiredHeaderQuota(now);
+                let isQuotaProbe = false;
+                if (this.headerRemainingToday === 0 || this.isQuotaProbeReady(now)) {
+                    if (this.quotaProbeInFlight || this.inFlightReservations.size > 0) {
+                        await this.waitForStateChange();
+                        continue;
+                    }
+                    const probeWait = this.headerQuotaAvailableAt - now;
+                    if (probeWait > 0) {
+                        await new Promise(resolve => setTimeout(resolve, probeWait));
+                        continue;
+                    }
+                    isQuotaProbe = true;
+                }
+                else {
+                    const effectiveRemaining = this.getEffectiveRemainingRequests(now);
+                    if (effectiveRemaining <= 0) {
+                        if (this.inFlightReservations.size > 0 && this.headerRemainingToday !== undefined) {
+                            await this.waitForStateChange();
+                            continue;
+                        }
+                        const effectiveDailyLimit = this.headerLimitPerDay ?? this.config.maxRequestsPerDay;
+                        const localResetTime = this.getLocalResetTime(now);
+                        const timeUntilReset = Math.max(0, localResetTime.getTime() - now);
+                        throw new EtsyRateLimitError(`Daily rate limit exhausted (${effectiveDailyLimit} requests in the local rolling 24-hour window). ` +
+                            `The oldest local request expires in approximately ${Math.ceil(timeUntilReset / 1000 / 60)} minutes.`, Math.ceil(timeUntilReset / 1000), 'qpd_exhausted');
+                    }
+                }
+                const intervalWait = Math.max(0, this.getEffectiveMinInterval() - (now - this.lastRequestTime));
+                const cooldownWait = Math.max(0, this.retryNotBefore - now);
+                const waitTime = Math.max(intervalWait, cooldownWait);
+                if (waitTime > 0) {
+                    await new Promise(resolve => setTimeout(resolve, waitTime));
+                    continue;
+                }
+                const requestStartedAt = Date.now();
+                const reservationId = ++this.nextReservationId;
+                this.requestTimestamps.push(requestStartedAt);
+                this.lastRequestTime = requestStartedAt;
+                this.inFlightReservations.set(reservationId, { isQuotaProbe, startedAt: requestStartedAt });
+                if (isQuotaProbe)
+                    this.quotaProbeInFlight = true;
+                return reservationId;
+            }
+        }
+        finally {
+            releaseReservation();
+        }
     }
-    updateFromHeaders(headers) {
+    releaseRequestSlot(reservationId) {
+        const reservation = this.inFlightReservations.get(reservationId);
+        if (!reservation)
+            return;
+        this.uncertainRequestTimestamps.push(reservation.startedAt);
+        this.finishReservation(reservationId, false);
+    }
+    updateFromHeaders(headers, reservationId) {
+        const matchedReservationId = reservationId;
+        const isQuotaProbe = matchedReservationId !== undefined &&
+            this.inFlightReservations.get(matchedReservationId)?.isQuotaProbe === true;
         if (!headers) {
+            if (matchedReservationId !== undefined)
+                this.finishReservation(matchedReservationId, false);
             return;
         }
         const parsed = this.parseRateLimitHeaders(headers);
+        if (matchedReservationId !== undefined) {
+            this.finishReservation(matchedReservationId, parsed.remainingToday !== undefined);
+        }
         if (parsed.limitPerSecond !== undefined) {
             this.headerLimitPerSecond = parsed.limitPerSecond;
             this.isHeaderBasedLimiting = true;
@@ -726,9 +967,39 @@ class EtsyRateLimiter {
             this.isHeaderBasedLimiting = true;
         }
         if (parsed.remainingToday !== undefined) {
-            this.headerRemainingToday = parsed.remainingToday;
+            const observationId = matchedReservationId ?? this.nextReservationId;
+            if (isQuotaProbe && parsed.remainingToday > 0) {
+                this.uncertainRequestTimestamps = [];
+            }
+            const exhaustedByEarlierObservation = this.headerRemainingToday === 0 &&
+                parsed.remainingToday > 0 && matchedReservationId !== undefined && !isQuotaProbe;
+            const exhaustedByUncorrelatedObservation = this.headerRemainingToday === 0 &&
+                parsed.remainingToday > 0 && matchedReservationId === undefined;
+            if (exhaustedByEarlierObservation || exhaustedByUncorrelatedObservation) ;
+            else if (isQuotaProbe || this.headerRemainingToday === undefined) {
+                this.headerRemainingToday = parsed.remainingToday;
+                this.latestHeaderReservationId = Math.max(this.latestHeaderReservationId, observationId);
+            }
+            else if (parsed.remainingToday < this.headerRemainingToday) {
+                this.headerRemainingToday = parsed.remainingToday;
+                this.latestHeaderReservationId = Math.max(this.latestHeaderReservationId, observationId);
+            }
+            if (this.headerRemainingToday !== undefined && this.headerRemainingToday > 0) {
+                this.headerQuotaAvailableAt = 0;
+                this.quotaProbeBackoffMs = 60000;
+            }
+            else if (this.headerQuotaAvailableAt === 0) {
+                this.scheduleQuotaProbe();
+            }
             this.checkApproachingLimit();
         }
+        else if (matchedReservationId !== undefined && this.headerRemainingToday !== undefined) {
+            this.headerRemainingToday = Math.max(0, this.headerRemainingToday - 1);
+            if (this.headerRemainingToday === 0 && this.headerQuotaAvailableAt === 0) {
+                this.scheduleQuotaProbe();
+            }
+        }
+        this.notifyStateWaiters();
     }
     parseRateLimitHeaders(headers) {
         const getHeader = (name) => {
@@ -768,18 +1039,27 @@ class EtsyRateLimiter {
             this.config.onApproachingLimit(remaining, limit, percentageUsed);
         }
     }
-    async handleRateLimitResponse(headers) {
+    async handleRateLimitResponse(headers, reservationId, retryAttempt) {
         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.updateFromHeaders(headers, reservationId);
+        if (parsed.remainingToday === 0) {
+            if (parsed.retryAfter !== undefined) {
+                this.headerQuotaAvailableAt = Date.now() + parsed.retryAfter * 1000;
+                this.retryNotBefore = Math.max(this.retryNotBefore, this.headerQuotaAvailableAt);
+            }
             this.currentRetryCount = 0;
+            throw new EtsyRateLimitError('Daily rate limit exhausted according to Etsy response headers.', parsed.retryAfter, 'qpd_exhausted');
+        }
+        const attempt = retryAttempt ?? this.currentRetryCount + 1;
+        if (retryAttempt === undefined)
+            this.currentRetryCount = attempt;
+        const delayMs = this.calculateBackoffDelay(attempt, parsed.retryAfter);
+        this.retryNotBefore = Math.max(this.retryNotBefore, Date.now() + delayMs);
+        if (attempt > this.config.maxRetries) {
+            if (retryAttempt === undefined)
+                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) {
@@ -792,7 +1072,7 @@ class EtsyRateLimiter {
             const randomJitter = Math.random() * jitterAmount * 2 - jitterAmount;
             delay += randomJitter;
         }
-        return Math.max(0, Math.floor(delay));
+        return Math.max(serverSuggestedMs, 0, Math.floor(delay));
     }
     resetRetryCount() {
         this.currentRetryCount = 0;
@@ -810,41 +1090,26 @@ class EtsyRateLimiter {
         return this.config.minRequestInterval;
     }
     async waitForRateLimit() {
-        const now = Date.now();
-        if (now >= this.dailyReset.getTime()) {
-            this.requestCount = 0;
-            this.setNextDailyReset();
-        }
-        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 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 < minInterval) {
-            const waitTime = minInterval - timeSinceLastRequest;
-            await new Promise(resolve => setTimeout(resolve, waitTime));
-        }
-        this.requestCount++;
-        this.lastRequestTime = Date.now();
+        const reservationId = await this.acquireRequestSlot();
+        this.finishReservation(reservationId, false);
+    }
+    async waitForRateLimitWithReservation() {
+        return this.acquireRequestSlot();
     }
     getRateLimitStatus() {
         const now = Date.now();
-        if (now >= this.dailyReset.getTime()) {
-            this.requestCount = 0;
-            this.setNextDailyReset();
-        }
-        const effectiveRemaining = this.headerRemainingToday ??
-            Math.max(0, this.config.maxRequestsPerDay - this.requestCount);
+        this.pruneRequestTimestamps(now);
+        this.refreshExpiredHeaderQuota(now);
+        const effectiveRemaining = this.getEffectiveRemainingRequests(now);
+        const qpdProbeReady = this.isQuotaProbeReady(now);
         return {
             remainingRequests: effectiveRemaining,
-            resetTime: this.dailyReset,
-            canMakeRequest: effectiveRemaining > 0 &&
-                (now - this.lastRequestTime) >= this.getEffectiveMinInterval(),
+            resetTime: this.headerRemainingToday === 0
+                ? new Date(this.headerQuotaAvailableAt || now)
+                : this.getLocalResetTime(now),
+            canMakeRequest: (effectiveRemaining > 0 || qpdProbeReady) &&
+                (now - this.lastRequestTime) >= this.getEffectiveMinInterval() &&
+                now >= this.retryNotBefore,
             isFromHeaders: this.isHeaderBasedLimiting,
             limitPerSecond: this.headerLimitPerSecond,
             remainingThisSecond: this.headerRemainingThisSecond,
@@ -852,41 +1117,47 @@ class EtsyRateLimiter {
         };
     }
     getRemainingRequests() {
-        return this.headerRemainingToday ??
-            Math.max(0, this.config.maxRequestsPerDay - this.requestCount);
+        const now = Date.now();
+        this.pruneRequestTimestamps(now);
+        this.refreshExpiredHeaderQuota(now);
+        return this.getEffectiveRemainingRequests(now);
     }
     reset() {
-        this.requestCount = 0;
+        this.requestTimestamps = [];
         this.lastRequestTime = 0;
         this.currentRetryCount = 0;
+        this.quotaProbeBackoffMs = 60000;
+        this.headerQuotaAvailableAt = 0;
+        this.retryNotBefore = 0;
         this.headerLimitPerSecond = undefined;
         this.headerRemainingThisSecond = undefined;
         this.headerLimitPerDay = undefined;
         this.headerRemainingToday = undefined;
         this.isHeaderBasedLimiting = false;
-        this.setNextDailyReset();
+        this.nextReservationId = 0;
+        this.latestHeaderReservationId = 0;
+        this.inFlightReservations.clear();
+        this.uncertainRequestTimestamps = [];
+        this.quotaProbeInFlight = false;
+        this.notifyStateWaiters();
     }
     canMakeRequest() {
         const now = Date.now();
-        if (now >= this.dailyReset.getTime()) {
-            this.requestCount = 0;
-            this.setNextDailyReset();
-        }
-        const effectiveRemaining = this.headerRemainingToday ??
-            (this.config.maxRequestsPerDay - this.requestCount);
-        if (effectiveRemaining <= 0) {
+        this.pruneRequestTimestamps(now);
+        this.refreshExpiredHeaderQuota(now);
+        const effectiveRemaining = this.getEffectiveRemainingRequests(now);
+        const qpdProbeReady = this.isQuotaProbeReady(now);
+        if (effectiveRemaining <= 0 && !qpdProbeReady) {
             return false;
         }
-        return (now - this.lastRequestTime) >= this.getEffectiveMinInterval();
+        return (now - this.lastRequestTime) >= this.getEffectiveMinInterval() &&
+            now >= this.retryNotBefore;
     }
     getTimeUntilNextRequest() {
         const now = Date.now();
         const timeSinceLastRequest = now - this.lastRequestTime;
         const minInterval = this.getEffectiveMinInterval();
-        if (timeSinceLastRequest >= minInterval) {
-            return 0;
-        }
-        return minInterval - timeSinceLastRequest;
+        return Math.max(0, minInterval - timeSinceLastRequest, this.retryNotBefore - now);
     }
     getConfig() {
         return { ...this.config };
@@ -1088,10 +1359,10 @@ class FieldValidator {
             const value = data[this.field];
             if (value === undefined || value === null)
                 return null;
-            if (typeof value !== 'number' || Number.isNaN(value)) {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
                 return {
                     field: this.field,
-                    message: options.message || `${this.field} must be a number`,
+                    message: options.message || `${this.field} must be a finite number`,
                     value
                 };
             }
@@ -1196,28 +1467,10 @@ const CreateListingSchema = new Validator()
     .rule(field('title').string({ min: 1, max: 140, message: 'title must be 1-140 characters' }))
     .rule(field('description').string({ max: 65535, message: 'description must be less than 65535 characters' }))
     .rule(field('price').required())
-    .rule(field('price').number({ min: 0.2, max: 50000, message: 'price must be between 0.20 and 50000.00' }))
+    .rule(field('price').number({ positive: true, message: 'price must be a finite positive number' }))
     .rule(field('who_made').enum(['i_did', 'someone_else', 'collective'], 'who_made must be one of: i_did, someone_else, collective'))
-    .rule(field('when_made').enum([
-    'made_to_order',
-    '2020_2024',
-    '2010_2019',
-    '2005_2009',
-    '2000_2004',
-    '1990s',
-    '1980s',
-    '1970s',
-    '1960s',
-    '1950s',
-    '1940s',
-    '1930s',
-    '1920s',
-    '1910s',
-    '1900s',
-    '1800s',
-    '1700s',
-    'before_1700'
-]))
+    .rule(field('when_made').required())
+    .rule(field('when_made').enum(['made_to_order', ...ETSY_WHEN_MADE_VALUES]))
     .rule(field('taxonomy_id').required())
     .rule(field('taxonomy_id').number({ integer: true, positive: true, message: 'taxonomy_id must be a positive integer' }));
 const UpdateListingSchema = new Validator()
@@ -1354,7 +1607,8 @@ class EtsyClient {
         this.logger = new DefaultLogger();
         this.keystring = config.keystring;
         this.sharedSecret = config.sharedSecret;
-        if (config.rateLimiting?.enabled !== false) {
+        this.rateLimitingEnabled = config.rateLimiting?.enabled !== false;
+        if (this.rateLimitingEnabled) {
             this.rateLimiter = new EtsyRateLimiter({
                 maxRequestsPerDay: config.rateLimiting?.maxRequestsPerDay || ETSY_RATE_LIMITS.MAX_REQUESTS_PER_DAY,
                 maxRequestsPerSecond: config.rateLimiting?.maxRequestsPerSecond || ETSY_RATE_LIMITS.MAX_REQUESTS_PER_SECOND,
@@ -1379,11 +1633,39 @@ class EtsyClient {
             stopOnError: false
         });
     }
+    async acquireRateLimitSlot() {
+        return this.rateLimitingEnabled
+            ? this.rateLimiter.acquireRequestSlot()
+            : undefined;
+    }
+    async fetchOnceWithRateLimit(url, options) {
+        const reservationId = await this.acquireRateLimitSlot();
+        let response;
+        try {
+            response = await this.fetch(url, options);
+        }
+        catch (error) {
+            if (reservationId !== undefined)
+                this.rateLimiter.releaseRequestSlot(reservationId);
+            throw error;
+        }
+        if (response.status === 429) {
+            await this.rateLimiter.handleRateLimitResponse(response.headers, reservationId);
+            this.rateLimiter.resetRetryCount();
+        }
+        else {
+            this.rateLimiter.updateFromHeaders(response.headers, reservationId);
+            if (response.ok)
+                this.rateLimiter.resetRetryCount();
+        }
+        return response;
+    }
     async makeRequest(endpoint, options = {}, useCache = true) {
         const url = `${this.baseUrl}${endpoint}`;
         const requestOptions = {
             method: 'GET',
-            ...options
+            ...options,
+            redirect: 'error'
         };
         const cacheKey = `${url}:${JSON.stringify(requestOptions)}`;
         if (useCache && this.cache && requestOptions.method === 'GET') {
@@ -1397,7 +1679,6 @@ class EtsyClient {
                 }
             }
         }
-        await this.rateLimiter.waitForRateLimit();
         const accessToken = await this.tokenManager.getAccessToken();
         const headers = {
             'Authorization': `Bearer ${accessToken}`,
@@ -1409,22 +1690,38 @@ class EtsyClient {
         return this.executeWithRetry(url, { ...requestOptions, headers }, cacheKey, useCache);
     }
     async executeWithRetry(url, options, cacheKey, useCache) {
+        let retryAttempt = 0;
         while (true) {
             try {
-                const response = await this.fetch(url, options);
+                const reservationId = await this.acquireRateLimitSlot();
+                let response;
+                try {
+                    response = await this.fetch(url, options);
+                }
+                catch (error) {
+                    if (reservationId !== undefined)
+                        this.rateLimiter.releaseRequestSlot(reservationId);
+                    throw error;
+                }
                 if (response.status === 429) {
-                    const { shouldRetry, delayMs } = await this.rateLimiter.handleRateLimitResponse(response.headers);
+                    const { shouldRetry, delayMs } = await this.rateLimiter.handleRateLimitResponse(response.headers, reservationId, ++retryAttempt);
                     if (shouldRetry) {
+                        const method = (options.method ?? 'GET').toUpperCase();
+                        if (method !== 'GET') {
+                            this.rateLimiter.resetRetryCount();
+                            const errorText = await response.text();
+                            throw new EtsyApiError(`Etsy API error: 429 ${response.statusText}; automatic retry skipped for ${method} requests`, 429, errorText);
+                        }
                         this.logger.warn(`Rate limited. Retrying in ${delayMs}ms...`);
                         await this.sleep(delayMs);
                         continue;
                     }
                 }
+                this.rateLimiter.updateFromHeaders(response.headers, reservationId);
                 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;
@@ -1727,9 +2024,87 @@ class EtsyClient {
     async updateListingInventory(listingId, params, options) {
         const legacy = options?.legacy;
         const query = legacy !== undefined ? `?legacy=${legacy}` : '';
+        if (!Array.isArray(params.products) || params.products.length === 0) {
+            throw new TypeError('Inventory update must contain at least one product.');
+        }
+        const body = {
+            products: params.products.map((product, productIndex) => {
+                if (product.is_deleted === true) {
+                    throw new TypeError(`Inventory product ${productIndex} is deleted and cannot be submitted for replacement.`);
+                }
+                if (!Array.isArray(product.offerings) || product.offerings.length === 0) {
+                    throw new TypeError(`Inventory product ${productIndex} must contain at least one offering.`);
+                }
+                if (!Array.isArray(product.property_values)) {
+                    throw new TypeError(`Inventory product ${productIndex} must include property_values; pass [] when it has no variation properties.`);
+                }
+                if (product.sku !== undefined && product.sku !== null && typeof product.sku !== 'string') {
+                    throw new TypeError(`Inventory product ${productIndex} sku must be a string or null.`);
+                }
+                return {
+                    ...(product.sku !== undefined ? { sku: product.sku } : {}),
+                    property_values: product.property_values.map((value, valueIndex) => {
+                        if (!Number.isInteger(value.property_id) || value.property_id < 1) {
+                            throw new TypeError(`Inventory product ${productIndex} property_values[${valueIndex}].property_id must be a positive integer.`);
+                        }
+                        if (!Array.isArray(value.value_ids) || value.value_ids.some((id) => !Number.isInteger(id))) {
+                            throw new TypeError(`Inventory product ${productIndex} property_values[${valueIndex}].value_ids must be an integer array.`);
+                        }
+                        if (!Array.isArray(value.values) || value.values.some((entry) => typeof entry !== 'string')) {
+                            throw new TypeError(`Inventory product ${productIndex} property_values[${valueIndex}].values must be a string array.`);
+                        }
+                        if (value.property_name !== undefined && typeof value.property_name !== 'string') {
+                            throw new TypeError(`Inventory product ${productIndex} property_values[${valueIndex}].property_name must be a string.`);
+                        }
+                        if (value.scale_id !== undefined && value.scale_id !== null &&
+                            (!Number.isInteger(value.scale_id) || value.scale_id < 1)) {
+                            throw new TypeError(`Inventory product ${productIndex} property_values[${valueIndex}].scale_id must be a positive integer or null.`);
+                        }
+                        return {
+                            property_id: value.property_id,
+                            ...(value.property_name !== undefined ? { property_name: value.property_name } : {}),
+                            ...(value.scale_id !== undefined ? { scale_id: value.scale_id } : {}),
+                            value_ids: value.value_ids,
+                            values: value.values,
+                        };
+                    }),
+                    offerings: product.offerings.map((offering, offeringIndex) => {
+                        if (offering.is_deleted === true) {
+                            throw new TypeError(`Inventory product ${productIndex} offering ${offeringIndex} is deleted and cannot be submitted for replacement.`);
+                        }
+                        if (typeof offering.price !== 'number' || !Number.isFinite(offering.price)) {
+                            throw new TypeError('Inventory offering price must be a finite decimal number in the listing currency.');
+                        }
+                        if (!Number.isInteger(offering.quantity)) {
+                            throw new TypeError(`Inventory product ${productIndex} offering ${offeringIndex} quantity must be an integer.`);
+                        }
+                        if (typeof offering.is_enabled !== 'boolean') {
+                            throw new TypeError(`Inventory product ${productIndex} offering ${offeringIndex} is_enabled must be a boolean.`);
+                        }
+                        if (offering.readiness_state_id === undefined ||
+                            (offering.readiness_state_id !== null &&
+                                (!Number.isInteger(offering.readiness_state_id) || offering.readiness_state_id < 1))) {
+                            throw new TypeError('Inventory offering readiness_state_id is required; use null when not set.');
+                        }
+                        return {
+                            price: offering.price,
+                            quantity: offering.quantity,
+                            is_enabled: offering.is_enabled,
+                            readiness_state_id: offering.readiness_state_id,
+                        };
+                    }),
+                };
+            }),
+            ...(params.price_on_property !== undefined ? { price_on_property: params.price_on_property } : {}),
+            ...(params.quantity_on_property !== undefined ? { quantity_on_property: params.quantity_on_property } : {}),
+            ...(params.sku_on_property !== undefined ? { sku_on_property: params.sku_on_property } : {}),
+            ...(params.readiness_state_on_property !== undefined
+                ? { readiness_state_on_property: params.readiness_state_on_property }
+                : {}),
+        };
         return this.makeRequest(`/listings/${listingId}/inventory${query}`, {
             method: 'PUT',
-            body: JSON.stringify(params)
+            body: JSON.stringify(body)
         }, false);
     }
     async uploadListingImage(shopId, listingId, imageData, params) {
@@ -1744,9 +2119,8 @@ class EtsyClient {
         if (params?.alt_text)
             formData.append('alt_text', params.alt_text);
         const url = `${this.baseUrl}/shops/${shopId}/listings/${listingId}/images`;
-        await this.rateLimiter.waitForRateLimit();
         const accessToken = await this.tokenManager.getAccessToken();
-        const response = await this.fetch(url, {
+        const response = await this.fetchOnceWithRateLimit(url, {
             method: 'POST',
             headers: {
                 'Authorization': `Bearer ${accessToken}`,
@@ -1941,10 +2315,11 @@ class EtsyClient {
     }
     async getShopPayment(shopId, paymentId) {
         const payments = await this.getPayments(shopId, [Number(paymentId)]);
-        if (payments.length === 0) {
+        const payment = payments[0];
+        if (!payment) {
             throw new EtsyApiError('Payment not found', 404);
         }
-        return payments[0];
+        return payment;
     }
     async getBuyerTaxonomyNodes() {
         const response = await this.makeRequest('/buyer-taxonomy/nodes');
@@ -1967,9 +2342,8 @@ class EtsyClient {
             body.append('scale_id', scaleId.toString());
         }
         const url = `${this.baseUrl}/shops/${shopId}/listings/${listingId}/properties/${propertyId}`;
-        await this.rateLimiter.waitForRateLimit();
         const accessToken = await this.tokenManager.getAccessToken();
-        const response = await this.fetch(url, {
+        const response = await this.fetchOnceWithRateLimit(url, {
             method: 'PUT',
             headers: {
                 'Authorization': `Bearer ${accessToken}`,
@@ -1978,8 +2352,6 @@ class EtsyClient {
             },
             body: body.toString()
         });
-        this.rateLimiter.updateFromHeaders(response.headers);
-        this.rateLimiter.resetRetryCount();
         if (!response.ok) {
             const errorText = await response.text();
             throw new EtsyApiError(`Failed to update listing property: ${response.status} ${response.statusText}`, response.status, errorText);
@@ -2079,9 +2451,8 @@ class EtsyClient {
         if (params?.listing_file_id !== undefined)
             formData.append('listing_file_id', params.listing_file_id.toString());
         const url = `${this.baseUrl}/shops/${shopId}/listings/${listingId}/files`;
-        await this.rateLimiter.waitForRateLimit();
         const accessToken = await this.tokenManager.getAccessToken();
-        const response = await this.fetch(url, {
+        const response = await this.fetchOnceWithRateLimit(url, {
             method: 'POST',
             headers: {
                 'Authorization': `Bearer ${accessToken}`,
@@ -2113,9 +2484,8 @@ class EtsyClient {
         if (params?.video_id !== undefined)
             formData.append('video_id', params.video_id.toString());
         const url = `${this.baseUrl}/shops/${shopId}/listings/${listingId}/videos`;
-        await this.rateLimiter.waitForRateLimit();
         const accessToken = await this.tokenManager.getAccessToken();
-        const response = await this.fetch(url, {
+        const response = await this.fetchOnceWithRateLimit(url, {
             method: 'POST',
             headers: {
                 'Authorization': `Bearer ${accessToken}`,
@@ -2537,6 +2907,7 @@ class AuthHelper {
             assertFetchSupport();
             const response = await fetch('https://api.etsy.com/v3/public/oauth/token', {
                 method: 'POST',
+                redirect: 'error',
                 headers: {
                     'Content-Type': 'application/x-www-form-urlencoded',
                     'Accept': 'application/json'
@@ -2629,18 +3000,17 @@ const COMMON_SCOPE_COMBINATIONS = {
     ]
 };
 
+const QPD_WINDOW_MS = 24 * 60 * 60 * 1000;
 class GlobalRequestQueue {
     constructor() {
         this.queue = [];
         this.processing = false;
         this.rateLimits = new Map();
-        this.requestCount = 0;
-        this.dailyReset = new Date();
+        this.requestTimestamps = [];
         this.lastRequestTime = 0;
         this.maxRequestsPerDay = ETSY_RATE_LIMITS.MAX_REQUESTS_PER_DAY;
         this.maxRequestsPerSecond = ETSY_RATE_LIMITS.MAX_REQUESTS_PER_SECOND;
         this.minRequestInterval = ETSY_RATE_LIMITS.MIN_REQUEST_INTERVAL;
-        this.setNextDailyReset();
     }
     static getInstance() {
         if (!this.instance) {
@@ -2672,11 +3042,13 @@ class GlobalRequestQueue {
         });
     }
     getStatus() {
+        const now = Date.now();
+        this.pruneRequestTimestamps(now);
         return {
             queueLength: this.queue.length,
             processing: this.processing,
-            remainingRequests: Math.max(0, this.maxRequestsPerDay - this.requestCount),
-            resetTime: this.dailyReset,
+            remainingRequests: Math.max(0, this.maxRequestsPerDay - this.requestTimestamps.length),
+            resetTime: this.getNextRequestExpiry(now),
         };
     }
     clear() {
@@ -2692,16 +3064,13 @@ class GlobalRequestQueue {
         this.processing = true;
         try {
             while (this.queue.length > 0) {
-                if (Date.now() >= this.dailyReset.getTime()) {
-                    this.requestCount = 0;
-                    this.setNextDailyReset();
-                }
-                if (this.requestCount >= this.maxRequestsPerDay) {
-                    const timeUntilReset = this.dailyReset.getTime() - Date.now();
-                    console.warn(`Daily rate limit reached. Waiting ${Math.ceil(timeUntilReset / 1000 / 60)} minutes until reset.`);
+                const now = Date.now();
+                this.pruneRequestTimestamps(now);
+                if (this.requestTimestamps.length >= this.maxRequestsPerDay) {
+                    const timeUntilReset = Math.max(0, this.getNextRequestExpiry(now).getTime() - now);
+                    console.warn(`Daily rate limit reached. Waiting ${Math.ceil(timeUntilReset / 1000 / 60)} minutes for the oldest request to leave the rolling 24-hour window.`);
                     await this.delay(timeUntilReset);
-                    this.requestCount = 0;
-                    this.setNextDailyReset();
+                    continue;
                 }
                 await this.waitForRateLimit();
                 this.queue.sort((a, b) => {
@@ -2736,7 +3105,7 @@ class GlobalRequestQueue {
                             }
                         });
                         try {
-                            result = await Promise.race([item.request(), timeoutPromise]);
+                            result = await Promise.race([this.startRequest(item.request), timeoutPromise]);
                         }
                         finally {
                             if (timeoutId) {
@@ -2745,11 +3114,9 @@ class GlobalRequestQueue {
                         }
                     }
                     else {
-                        result = await item.request();
+                        result = await this.startRequest(item.request);
                     }
                     item.resolve(result);
-                    this.requestCount++;
-                    this.lastRequestTime = Date.now();
                 }
                 catch (error) {
                     if (error instanceof EtsyRateLimitError) {
@@ -2769,7 +3136,7 @@ class GlobalRequestQueue {
         const globalRateLimit = this.rateLimits.get('global');
         if (globalRateLimit && now < globalRateLimit.resetAt) {
             const waitTime = globalRateLimit.resetAt - now;
-            console.log(`Global rate limit active. Waiting ${waitTime}ms`);
+            console.warn(`Global rate limit active. Waiting ${waitTime}ms`);
             await this.delay(waitTime);
         }
         const timeSinceLastRequest = now - this.lastRequestTime;
@@ -2787,11 +3154,23 @@ class GlobalRequestQueue {
             });
         }
     }
-    setNextDailyReset() {
-        const now = new Date();
-        this.dailyReset = new Date(now);
-        this.dailyReset.setUTCDate(this.dailyReset.getUTCDate() + 1);
-        this.dailyReset.setUTCHours(0, 0, 0, 0);
+    pruneRequestTimestamps(now) {
+        const oldestAllowed = now - QPD_WINDOW_MS;
+        while (this.requestTimestamps[0] !== undefined && this.requestTimestamps[0] <= oldestAllowed) {
+            this.requestTimestamps.shift();
+        }
+    }
+    getNextRequestExpiry(now) {
+        this.pruneRequestTimestamps(now);
+        const oldestRequest = this.requestTimestamps[0] ?? now;
+        return new Date(oldestRequest + QPD_WINDOW_MS);
+    }
+    startRequest(request) {
+        const startedAt = Date.now();
+        this.pruneRequestTimestamps(startedAt);
+        this.requestTimestamps.push(startedAt);
+        this.lastRequestTime = startedAt;
+        return request();
     }
     generateId() {
         return `${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
@@ -4302,7 +4681,7 @@ function createTokenManager(config, storage) {
 function createRateLimiter(config) {
     return new EtsyRateLimiter(config);
 }
-const VERSION = '2.2.0';
+const VERSION = '3.0.1';
 const LIBRARY_NAME = 'etsy-v3-api-client';
 function getLibraryInfo() {
     return {