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

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 interface EtsyClientConfig {
     keystring: string;
+    sharedSecret?: string;
     accessToken: string;
     refreshToken: string;
     expiresAt: Date;
@@ -10,6 +11,12 @@ interface EtsyClientConfig {
         maxRequestsPerDay?: number;
         maxRequestsPerSecond?: number;
         minRequestInterval?: number;
+        maxRetries?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        jitter?: number;
+        qpdWarningThreshold?: number;
+        onApproachingLimit?: (remainingRequests: number, totalLimit: number, percentageUsed: number) => void;
     };
     caching?: {
         enabled: boolean;
@@ -276,15 +283,34 @@ interface SearchParams {
     location?: string;
     shop_location?: string;
 }
+interface EtsyRateLimitHeaders {
+    limitPerSecond?: number;
+    remainingThisSecond?: number;
+    limitPerDay?: number;
+    remainingToday?: number;
+    retryAfter?: number;
+}
+type RateLimitErrorType = 'qpd_exhausted' | 'qps_exhausted' | 'unknown';
+type ApproachingLimitCallback = (remainingRequests: number, totalLimit: number, percentageUsed: number) => void;
 interface RateLimitConfig {
     maxRequestsPerDay: number;
     maxRequestsPerSecond: number;
     minRequestInterval: number;
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitter?: number;
+    qpdWarningThreshold?: number;
+    onApproachingLimit?: ApproachingLimitCallback;
 }
 interface RateLimitStatus {
     remainingRequests: number;
     resetTime: Date;
     canMakeRequest: boolean;
+    isFromHeaders: boolean;
+    limitPerSecond?: number;
+    remainingThisSecond?: number;
+    limitPerDay?: number;
 }
 interface EtsyErrorDetails {
     statusCode: number;
@@ -327,8 +353,10 @@ declare class EtsyAuthError extends Error {
 }
 declare class EtsyRateLimitError extends Error {
     _retryAfter?: number | undefined;
-    constructor(message: string, _retryAfter?: number | undefined);
+    readonly errorType: RateLimitErrorType;
+    constructor(message: string, _retryAfter?: number | undefined, errorType?: RateLimitErrorType);
     get retryAfter(): number | undefined;
+    isRetryable(): boolean;
 }
 interface CacheStorage {
     get(_key: string): Promise<string | null>;
@@ -1021,9 +1049,12 @@ declare class EtsyClient {
     private cache?;
     private cacheTtl;
     private keystring;
+    private sharedSecret?;
     private bulkOperationManager;
     constructor(config: EtsyClientConfig);
     private makeRequest;
+    private executeWithRetry;
+    private sleep;
     private getApiKey;
     getUser(): Promise<EtsyUser>;
     getShop(shopId?: string): Promise<EtsyShop>;
@@ -1082,6 +1113,7 @@ declare class EtsyClient {
     getShopProductionPartners(shopId: string): Promise<EtsyShopProductionPartner[]>;
     getRemainingRequests(): number;
     getRateLimitStatus(): RateLimitStatus;
+    onApproachingRateLimit(callback: ApproachingLimitCallback, threshold?: number): void;
     clearCache(): Promise<void>;
     getCurrentTokens(): EtsyTokens | null;
     isTokenExpired(): boolean;
@@ -1212,8 +1244,26 @@ declare class EtsyRateLimiter {
     private dailyReset;
     private lastRequestTime;
     private readonly config;
+    private headerLimitPerSecond?;
+    private headerRemainingThisSecond?;
+    private headerLimitPerDay?;
+    private headerRemainingToday?;
+    private isHeaderBasedLimiting;
+    private currentRetryCount;
     constructor(config?: Partial<RateLimitConfig>);
     private setNextDailyReset;
+    updateFromHeaders(headers: Headers | Record<string, string> | undefined | null): void;
+    private parseRateLimitHeaders;
+    private checkApproachingLimit;
+    handleRateLimitResponse(headers: Headers | Record<string, string> | undefined | null): Promise<{
+        shouldRetry: boolean;
+        delayMs: number;
+    }>;
+    private calculateBackoffDelay;
+    resetRetryCount(): void;
+    setApproachingLimitCallback(callback: ApproachingLimitCallback | undefined): void;
+    setWarningThreshold(threshold: number): void;
+    private getEffectiveMinInterval;
     waitForRateLimit(): Promise<void>;
     getRateLimitStatus(): RateLimitStatus;
     getRemainingRequests(): number;
@@ -1700,4 +1750,4 @@ declare function getLibraryInfo(): {
 };
 
 export { AuthHelper, BatchQueryExecutor, BulkOperationManager, COMMON_SCOPE_COMBINATIONS, CacheWithInvalidation, CreateListingSchema, DEFAULT_RETRY_CONFIG, ETSY_SCOPES, EncryptedFileTokenStorage, EtsyApiError, EtsyAuthError, EtsyClient, EtsyRateLimitError, EtsyRateLimiter, EtsyWebhookHandler, FieldValidator, FileTokenStorage, GlobalRequestQueue, LFUCache, LIBRARY_NAME, LRUCache, ListingQueryBuilder, LocalStorageTokenStorage, MemoryTokenStorage, PaginatedResults, PluginManager, ReceiptQueryBuilder, RedisCacheStorage, RetryManager, SecureTokenStorage, SessionStorageTokenStorage, TokenManager, UpdateListingSchema, UpdateShopSchema, VERSION, ValidationException, Validator, WebhookSecurity, combineValidators, createAnalyticsPlugin, createAuthHelper, createBatchQuery, createBulkOperationManager, createCacheStorage, createCacheWithInvalidation, createCachingPlugin, createCodeChallenge, createDefaultTokenStorage, createEtsyClient, createListingQuery, createLoggingPlugin, createPaginatedResults, createRateLimitPlugin, createRateLimiter, createReceiptQuery, createRedisCacheStorage, createRetryPlugin, createTokenManager, createValidator, createWebhookHandler, createWebhookSecurity, decryptAES256GCM, EtsyClient as default, defaultRateLimiter, deriveKeyFromPassword, encryptAES256GCM, executeBulkOperation, field, generateCodeVerifier, generateEncryptionKey, generateRandomBase64Url, generateState, getAvailableStorage, getEnvironmentInfo, getGlobalQueue, getLibraryInfo, hasLocalStorage, hasSessionStorage, isBrowser, isNode, isSecureStorageSupported, sha256, sha256Base64Url, validate, validateEncryptionKey, validateOrThrow, withQueryBuilder, withQueue, withRetry };
-export type { AdvancedCachingConfig, AnalyticsPluginConfig, AuthHelperConfig, BulkImageUploadOperation, BulkOperationConfig, BulkOperationError, BulkOperationResult, BulkOperationSummary, BulkUpdateListingOperation, CacheEntry, CacheStats, CacheStorage, CacheStrategy, CachingPluginConfig, CreateDraftListingParams, CreateReceiptShipmentParams, CreateShippingProfileDestinationParams, CreateShippingProfileParams, CreateShopSectionParams, EncryptedData, EncryptedStorageConfig, EtsyApiResponse, EtsyBuyerTaxonomyNode, EtsyBuyerTaxonomyProperty, EtsyBuyerTaxonomyPropertyScale, EtsyBuyerTaxonomyPropertyValue, EtsyClientConfig, EtsyClientWithQueryBuilder, EtsyErrorDetails, EtsyListing, EtsyListingImage, EtsyListingInventory, EtsyListingOffering, EtsyListingProduct, EtsyListingProperty, EtsyListingPropertyScale, EtsyListingPropertyValue, EtsyPagination, EtsyPayment, EtsyPaymentAccountLedgerEntry, EtsyPaymentAdjustment, EtsyPlugin, EtsySellerTaxonomyNode, EtsyShippingProfile, EtsyShippingProfileDestination, EtsyShippingProfileUpgrade, EtsyShop, EtsyShopProductionPartner, EtsyShopReceipt, EtsyShopReceiptShipment, EtsyShopReceiptTransaction, EtsyShopRefund, EtsyShopSection, EtsyTokenResponse, EtsyTokens, EtsyTransactionVariation, EtsyUser, EtsyWebhookEvent, EtsyWebhookEventType, GetPaymentAccountLedgerEntriesParams, GetShopReceiptsParams, ListingParams, ListingSortOn, ListingState, LoggerInterface, LoggingPluginConfig, PageFetcher, PaginationOptions, PluginRequestConfig, PluginResponse, QueueOptions, RateLimitConfig, RateLimitPluginConfig, RateLimitStatus, RedisClientLike, RedisConfig, RequestPriority, RetryConfig, RetryOptions, RetryPluginConfig, SearchParams, SecureTokenStorageConfig, SortOrder, TokenRefreshCallback, TokenRotationCallback, TokenRotationConfig, TokenStorage, UpdateListingInventoryParams, UpdateListingParams, UpdateShippingProfileDestinationParams, UpdateShippingProfileParams, UpdateShopParams, UpdateShopReceiptParams, UpdateShopSectionParams, UploadListingFileParams, UploadListingImageParams, ValidationError, ValidationOptions, ValidationResult, ValidationSchema, ValidatorFunction, WebhookConfig, WebhookEventHandler, WebhookSecurityConfig };
+export type { AdvancedCachingConfig, AnalyticsPluginConfig, ApproachingLimitCallback, AuthHelperConfig, BulkImageUploadOperation, BulkOperationConfig, BulkOperationError, BulkOperationResult, BulkOperationSummary, BulkUpdateListingOperation, CacheEntry, CacheStats, CacheStorage, CacheStrategy, CachingPluginConfig, CreateDraftListingParams, CreateReceiptShipmentParams, CreateShippingProfileDestinationParams, CreateShippingProfileParams, CreateShopSectionParams, EncryptedData, EncryptedStorageConfig, EtsyApiResponse, EtsyBuyerTaxonomyNode, EtsyBuyerTaxonomyProperty, EtsyBuyerTaxonomyPropertyScale, EtsyBuyerTaxonomyPropertyValue, EtsyClientConfig, EtsyClientWithQueryBuilder, EtsyErrorDetails, EtsyListing, EtsyListingImage, EtsyListingInventory, EtsyListingOffering, EtsyListingProduct, EtsyListingProperty, EtsyListingPropertyScale, EtsyListingPropertyValue, EtsyPagination, EtsyPayment, EtsyPaymentAccountLedgerEntry, EtsyPaymentAdjustment, EtsyPlugin, EtsyRateLimitHeaders, EtsySellerTaxonomyNode, EtsyShippingProfile, EtsyShippingProfileDestination, EtsyShippingProfileUpgrade, EtsyShop, EtsyShopProductionPartner, EtsyShopReceipt, EtsyShopReceiptShipment, EtsyShopReceiptTransaction, EtsyShopRefund, EtsyShopSection, EtsyTokenResponse, EtsyTokens, EtsyTransactionVariation, EtsyUser, EtsyWebhookEvent, EtsyWebhookEventType, GetPaymentAccountLedgerEntriesParams, GetShopReceiptsParams, ListingParams, ListingSortOn, ListingState, LoggerInterface, LoggingPluginConfig, PageFetcher, PaginationOptions, PluginRequestConfig, PluginResponse, QueueOptions, RateLimitConfig, RateLimitErrorType, RateLimitPluginConfig, RateLimitStatus, RedisClientLike, RedisConfig, RequestPriority, RetryConfig, RetryOptions, RetryPluginConfig, SearchParams, SecureTokenStorageConfig, SortOrder, TokenRefreshCallback, TokenRotationCallback, TokenRotationConfig, TokenStorage, UpdateListingInventoryParams, UpdateListingParams, UpdateShippingProfileDestinationParams, UpdateShippingProfileParams, UpdateShopParams, UpdateShopReceiptParams, UpdateShopSectionParams, UploadListingFileParams, UploadListingImageParams, ValidationError, ValidationOptions, ValidationResult, ValidationSchema, ValidatorFunction, WebhookConfig, WebhookEventHandler, WebhookSecurityConfig };

package/dist/index.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 };
@@ -1203,11 +1336,18 @@ class EtsyClient {
         this.baseUrl = config.baseUrl || 'https://api.etsy.com/v3/application';
         this.logger = new DefaultLogger();
         this.keystring = config.keystring;
+        this.sharedSecret = config.sharedSecret;
         if (config.rateLimiting?.enabled !== false) {
             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 {
@@ -1244,36 +1384,57 @@ 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}`;
+        }
         return this.keystring;
     }
     async getUser() {
@@ -1648,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();
@@ -2045,7 +2212,12 @@ class GlobalRequestQueue {
         return `${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
     }
     delay(ms) {
-        return new Promise(resolve => setTimeout(resolve, ms));
+        return new Promise(resolve => {
+            const timer = setTimeout(resolve, ms);
+            if (typeof timer.unref === 'function') {
+                timer.unref();
+            }
+        });
     }
 }
 GlobalRequestQueue.instance = null;